diff --git a/docs/contracts.md b/docs/contracts.md index 425e2d7e..4e9b4c7a 100644 --- a/docs/contracts.md +++ b/docs/contracts.md @@ -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 `{}`. diff --git a/docs/decisions/2026-11-17-credit-strata-staging-in-preflight.md b/docs/decisions/2026-11-17-credit-strata-staging-in-preflight.md new file mode 100644 index 00000000..2be53db6 --- /dev/null +++ b/docs/decisions/2026-11-17-credit-strata-staging-in-preflight.md @@ -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. diff --git a/docs/decisions/INDEX.md b/docs/decisions/INDEX.md index 2c72bb5e..7dca71b6 100644 --- a/docs/decisions/INDEX.md +++ b/docs/decisions/INDEX.md @@ -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) diff --git a/src/contracts/strata.ts b/src/contracts/strata.ts index 8e69c90c..a8cfef8d 100644 --- a/src/contracts/strata.ts +++ b/src/contracts/strata.ts @@ -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 diff --git a/src/core/strata.test.ts b/src/core/strata.test.ts index c230de21..da5f1c51 100644 --- a/src/core/strata.test.ts +++ b/src/core/strata.test.ts @@ -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' }) diff --git a/src/core/strata.ts b/src/core/strata.ts index d582b658..d47fb386 100644 --- a/src/core/strata.ts +++ b/src/core/strata.ts @@ -411,10 +411,18 @@ export async function wireStrata(options: Options) { }, }) const check = async (raw: unknown): Promise => { - if (!raw || typeof raw !== 'object' || Object.keys(raw).length !== 1) + const body = raw as Record | 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 - let descriptor: StrataModelDescriptor | undefined + let descriptor: StrataModelDescriptor + let stagedBytes = 0 const result: StrataCheckResult = { verdict: 'ok', reason: null, @@ -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')) @@ -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 @@ -513,6 +534,7 @@ export async function wireStrata(options: Options) { installed: !!entry, prepared: !!ready, previousBytes, + stagedBytes, memoryMode: settings.memory_mode, minimumVramBytes: memory.minimumVramBytes, }) diff --git a/src/runtime/strata/strata-check.ts b/src/runtime/strata/strata-check.ts index cd30b4e0..d24eda65 100644 --- a/src/runtime/strata/strata-check.ts +++ b/src/runtime/strata/strata-check.ts @@ -13,6 +13,7 @@ interface Inputs { installed: boolean prepared: boolean previousBytes: number + stagedBytes?: number memoryMode?: StrataMemoryMode minimumVramBytes?: number | undefined } @@ -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) { diff --git a/test/contract/strata-control.test.ts b/test/contract/strata-control.test.ts index e11b6c85..d8140eb7 100644 --- a/test/contract/strata-control.test.ts +++ b/test/contract/strata-control.test.ts @@ -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()