Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions docs/contracts.md
Original file line number Diff line number Diff line change
Expand Up @@ -363,9 +363,13 @@ with recursively sorted object keys, preserved array order, and no whitespace
or trailing newline. `strataCanonicalDescriptor` and `strataSourceDigest` provide
the shared client implementation. It is not a readiness marker.

- `POST /atomic/v1/models/strata/check`: `{descriptor}` or `{model_id}`; returns
verdict/reason, requirements, capabilities, preparation status, separate disk
and RAM/VRAM/unified-memory estimates, compatible devices and evidence.
- `POST /atomic/v1/models/strata/check` accepts `{descriptor, staged_bytes?}` or `{model_id}`. It
returns verdict/reason, requirements, capabilities, preparation status, disk and
RAM/VRAM/unified-memory estimates, compatible devices and evidence. For a descriptor
check, `staged_bytes` is the client's reusable source byte count on the destination
volume. It defaults to zero and must be an integer from zero through the descriptor's
total source size. It reduces only remaining download bytes and the disk estimate.
Source hashes and preparation readiness are still verified on disk.
- `POST /atomic/v1/strata/preparations`: `{request_id, model_id, source_digest,
maintenance_id?}`; `202` with the operation. List/get use `GET` at the same
root and `/:id`; cancel/resume use `POST /:id/{cancel,resume}` with `{}`.
Expand Down
11 changes: 11 additions & 0 deletions docs/decisions/2026-11-17-credit-strata-staging-in-preflight.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
date: 2026-11-17
title: "Account for staged Strata sources in compatibility checks"
---

# 2026-11-17 — Account for staged Strata sources in compatibility checks

- **Context.** A resumed Strata download needs less free disk space because the client has already staged some of the pinned sources.
- **Decision.** Allow the authenticated control client to supply a bounded `staged_bytes` count on a descriptor check. Subtract the count from the remaining source estimate and apply the usual disk and memory checks to the result.
- **Consequences.** The client measures reusable bytes for its own staging directory. Core keeps the derivative and temporary space estimates, and validates the complete input files during preparation.
- **Alternative.** Retrying without the disk verdict would lose the preparation space reservation and could hide an independent memory failure.
1 change: 1 addition & 0 deletions docs/decisions/INDEX.md
Original file line number Diff line number Diff line change
Expand Up @@ -277,3 +277,4 @@ add a new one that says which record it supersedes.
- [2026-11-16 — Report confirmed Strata startup VRAM exhaustion](2026-11-16-report-strata-startup-vram-exhaustion.md)

- [Report optimal-backend cache write failures as core IO_ERROR with their cause](2026-11-18-optimal-backend-write-failures-are-core-io-errors.md)
- [2026-11-17 — Account for staged Strata sources in compatibility checks](2026-11-17-credit-strata-staging-in-preflight.md)
9 changes: 8 additions & 1 deletion src/contracts/strata.ts
Original file line number Diff line number Diff line change
Expand Up @@ -93,8 +93,15 @@ export interface ModelYmlStrata {
}
export type StrataPreparationStatus =
'files-ready' | 'preparing' | 'ready' | 'preparation-required' | 'failed'
export type StrataCheckRequest = { descriptor: StrataModelDescriptor } | { model_id: string }
export type StrataCheckRequest =
| {
descriptor: StrataModelDescriptor
/** Reusable source bytes already occupying disk in the caller's staging directory. */
staged_bytes?: number
}
| { model_id: string }
export interface StrataResourceEstimate {
/** Remaining source bytes for this request, after any reported staging credit. */
download_bytes: number
derivative_bytes: number
temporary_bytes: number
Expand Down
30 changes: 28 additions & 2 deletions src/core/strata.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -46,13 +46,39 @@ it('checks a descriptor without writing and reports disk, unified memory and pla
emit: () => {},
})
const request = { descriptor }
expect(await strata.check(request)).toMatchObject({
const uncredited = await strata.check(request)
expect(uncredited).toMatchObject({
verdict: 'insufficient-disk',
estimates: { download_bytes: descriptor.requirements.download_bytes, ram_bytes: 0, vram_bytes: 0 },
qualification: descriptor.qualification,
})
freeBytes = 128 * 2 ** 30
const original = uncredited.estimates!
const staged = Math.floor(original.download_bytes / 2)
freeBytes = original.required_disk_bytes - staged
expect(await strata.check(request)).toMatchObject({ verdict: 'insufficient-disk' })
expect(await strata.check({ ...request, staged_bytes: staged })).toMatchObject({
verdict: 'ok',
estimates: {
...original,
download_bytes: original.download_bytes - staged,
required_disk_bytes: freeBytes,
},
})
freeBytes = original.derivative_bytes + original.temporary_bytes
expect(await strata.check({ ...request, staged_bytes: original.download_bytes })).toMatchObject({
verdict: 'ok',
estimates: { ...original, download_bytes: 0, required_disk_bytes: freeBytes },
})
freeBytes--
expect(await strata.check({ ...request, staged_bytes: original.download_bytes })).toMatchObject({
verdict: 'insufficient-disk',
})
freeBytes++
facts.devices[0]!.memoryBytes = 8 * 2 ** 30
expect(await strata.check({ ...request, staged_bytes: original.download_bytes })).toMatchObject({
verdict: 'insufficient-memory',
})
freeBytes = 128 * 2 ** 30
expect(await strata.check(request)).toMatchObject({ verdict: 'insufficient-memory' })
facts.osVersion = '14.9'
expect(await strata.check(request)).toMatchObject({ verdict: 'platform-unsupported' })
Expand Down
30 changes: 26 additions & 4 deletions src/core/strata.ts
Original file line number Diff line number Diff line change
Expand Up @@ -411,10 +411,18 @@ export async function wireStrata(options: Options) {
},
})
const check = async (raw: unknown): Promise<StrataCheckResult> => {
if (!raw || typeof raw !== 'object' || Object.keys(raw).length !== 1)
const body = raw as Record<string, unknown> | null
const keys = body && typeof body === 'object' && !Array.isArray(body) ? Object.keys(body) : []
const modelId =
keys.length === 1 && keys[0] === 'model_id' && typeof body?.model_id === 'string'
? body.model_id
: undefined
const hasDescriptor =
keys.includes('descriptor') && keys.every((key) => key === 'descriptor' || key === 'staged_bytes')
if (!body || (!modelId && !hasDescriptor))
throw new AtomicCoreError('INVALID_ARGUMENT', 'Send a Strata descriptor or model_id.')
const body = raw as Record<string, unknown>
let descriptor: StrataModelDescriptor | undefined
let descriptor: StrataModelDescriptor
let stagedBytes = 0
const result: StrataCheckResult = {
verdict: 'ok',
reason: null,
Expand All @@ -431,7 +439,6 @@ export async function wireStrata(options: Options) {
verdict,
reason,
})
const modelId = typeof body.model_id === 'string' ? body.model_id : undefined
let entry: StrataModelEntry | undefined
if (modelId) {
if (maintenance.list().some((o) => o.model_id === modelId && o.state !== 'completed'))
Expand All @@ -448,6 +455,20 @@ export async function wireStrata(options: Options) {
} catch (error) {
throw new AtomicCoreError('INVALID_ARGUMENT', (error as Error).message)
}
if (keys.includes('staged_bytes')) {
const count = body.staged_bytes
if (
typeof count !== 'number' ||
!Number.isSafeInteger(count) ||
count < 0 ||
count > descriptor.requirements.download_bytes
)
throw new AtomicCoreError(
'INVALID_ARGUMENT',
'Strata staged_bytes must be an integer between zero and the total source size.'
)
stagedBytes = count
}
}
result.capabilities = descriptor.capabilities
result.requirements = descriptor.requirements
Expand Down Expand Up @@ -513,6 +534,7 @@ export async function wireStrata(options: Options) {
installed: !!entry,
prepared: !!ready,
previousBytes,
stagedBytes,
memoryMode: settings.memory_mode,
minimumVramBytes: memory.minimumVramBytes,
})
Expand Down
3 changes: 2 additions & 1 deletion src/runtime/strata/strata-check.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ interface Inputs {
installed: boolean
prepared: boolean
previousBytes: number
stagedBytes?: number
memoryMode?: StrataMemoryMode
minimumVramBytes?: number | undefined
}
Expand Down Expand Up @@ -55,7 +56,7 @@ export function strataRamModeBytes(d: StrataModelDescriptor): number {
/** Conservative planning estimates for the pinned recipes. Values are not hardware qualification. */
export function estimateStrata(d: StrataModelDescriptor, input: Inputs): StrataResourceEstimate {
const weights = d.files.filter((f) => f.role === 'weights').reduce((total, file) => total + file.size, 0)
const download_bytes = input.installed ? 0 : d.requirements.download_bytes
const download_bytes = input.installed ? 0 : d.requirements.download_bytes - (input.stagedBytes ?? 0)
let derivative_bytes = 0
let temporary_bytes = 0
if (!input.prepared) {
Expand Down
20 changes: 20 additions & 0 deletions test/contract/strata-control.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,26 @@ it('connects Strata check and operation endpoints to the owner without a runtime
})
})

it('accepts only a bounded staged byte count on the Strata descriptor check', async () => {
const core = await createCore()
const client = new CoreClient({ baseUrl: core.control.url, token: core.controlToken })
const descriptor = parseStrataDescriptor(Object.values(catalog.models)[0]!.definition)
await expect(client.checkStrataModel({ descriptor, staged_bytes: 1 })).resolves.toMatchObject({
verdict: 'engine-not-installed',
})
await expect(client.checkStrataModel({ model_id: 'absent' })).resolves.toMatchObject({
verdict: 'invalid-installation',
})
for (const staged_bytes of [-1, 0.5, '1', descriptor.requirements.download_bytes + 1]) {
await expect(
client.request('POST', '/models/strata/check', { descriptor, staged_bytes })
).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' })
}
await expect(
client.request('POST', '/models/strata/check', { model_id: 'model', staged_bytes: 0 })
).rejects.toMatchObject({ code: 'INVALID_ARGUMENT' })
})

it('restores an interrupted Strata preparation and exposes its revision after restart', async () => {
const first = await createCore()
await first.shutdown()
Expand Down
Loading