diff --git a/docs/decisions/2026-11-20-code-strata-journal-root-failures.md b/docs/decisions/2026-11-20-code-strata-journal-root-failures.md new file mode 100644 index 00000000..5538ef30 --- /dev/null +++ b/docs/decisions/2026-11-20-code-strata-journal-root-failures.md @@ -0,0 +1,38 @@ +--- +date: 2026-11-20 +title: "Code Strata process-journal root failures as IO errors" +--- + +# 2026-11-20 — Code Strata process-journal root failures as IO errors + +- **Context:** `StrataProcessJournal.open` in `src/runtime/strata/strata-process-journal.ts` prepares + its root before it reads any record. The three calls that do this — + `mkdir(root, { recursive: true, mode: 0o700 })`, `lstat(root)` and `realpath(root)` — were + unguarded, while every later filesystem step in the same method maps failures through `corrupt()` + to `AtomicCoreError('IO_ERROR', …)`. `wireStrata` in `src/core/strata.ts` opens that journal + directly, so a system error escaped core startup as a plain `Error`. In production + (`atomic-chat-core@0.24.4` and `0.24.7`, Windows x64) that surfaced as the fatal + `core startup: unknown` with `error_code=ENOENT` and an unmapped `ENOENT` cause. Opening the + journal must stay fatal — it is the durable GPU-ownership evidence — but an untyped Error must + not cross the core boundary. ADR `2026-11-12-wrap-model-claim-filesystem-failures-as-coded-io-errors` + fixed the same class for model claims. +- **Decision:** Wrap only the root preparation in that method. An existing `AtomicCoreError` (from + `corrupt()`) is rethrown unchanged so its message and code survive; any other failure becomes + `AtomicCoreError('IO_ERROR', 'Strata process journal is unavailable; GPU ownership remains + blocked.', undefined, { cause })`, keeping the native filesystem error as `cause`. Nothing else + changes: no route, no classification table, no severity, no reporting frequency. +- **Consequences:** A journal root that cannot be prepared still aborts startup, and the GPU claim + is still treated as blocked, but the refusal now crosses the boundary with a code from + `ERROR_CODES`. `errorChain` follows `cause`, so `cause_code` stays `ENOENT`. Telemetry sees the + event's `error_code` tag change from `ENOENT` to `IO_ERROR` and the exception type from `Error` + to `IO_ERROR`; `failure_category`/`failure_reason` stay `unknown` because `ENOENT` and + `IO_ERROR` both have no mapping, so the rendered message is still `core startup: unknown`. Watch + for new `IO_ERROR` startup reports on hosts whose data folder is read-only, missing or replaced + during startup; the Windows host state that produced the dangling journal root is a separate + operational question. +- **Owner:** team. +- **Links:** `src/runtime/strata/strata-process-journal.ts`, + `src/runtime/strata/strata-process-journal-open.test.ts`, + `docs/decisions/2026-11-12-wrap-model-claim-filesystem-failures-as-coded-io-errors.md`, + `docs/decisions/2026-11-03-preserve-filesystem-cause-on-instance-lock-io-errors.md`, + Sentry ATOMIC-CHAT-CORE-D1. diff --git a/docs/decisions/INDEX.md b/docs/decisions/INDEX.md index 77a55ce8..93481690 100644 --- a/docs/decisions/INDEX.md +++ b/docs/decisions/INDEX.md @@ -291,3 +291,4 @@ add a new one that says which record it supersedes. - [Select Strata releases compatible with the running core](2026-11-19-skip-incompatible-strata-releases.md) - [Start Windows DeepSeek from existing Strata packs](2026-11-19-start-windows-deepseek-from-existing-strata-packs.md) - [Retry Strata session health checks before unloading](2026-11-19-retry-strata-session-health-checks.md) +- [Code Strata process-journal root failures as IO errors](2026-11-20-code-strata-journal-root-failures.md) diff --git a/src/runtime/strata/strata-process-journal-open.test.ts b/src/runtime/strata/strata-process-journal-open.test.ts new file mode 100644 index 00000000..3dcaea0a --- /dev/null +++ b/src/runtime/strata/strata-process-journal-open.test.ts @@ -0,0 +1,28 @@ +import { mkdir, mkdtemp, rm, symlink } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { afterEach, expect, it } from 'vitest' +import { AtomicCoreError } from '../../contracts/index.js' +import { StrataProcessJournal } from './strata-process-journal.js' + +const dirs: string[] = [] +afterEach(async () => { + await Promise.all(dirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true }))) +}) + +it('reports a journal root that cannot be prepared as a coded core error', async () => { + const base = await mkdtemp(join(tmpdir(), 'atomic-strata-journal-open-')) + dirs.push(base) + const core = join(base, 'core') + await mkdir(core, { recursive: true }) + // A leftover link whose target is gone: the same shape an interrupted reinstall of the data + // folder leaves on Windows, where the root preparation loses the filesystem error. + const root = join(core, 'strata') + await symlink(join(base, 'gone'), root) + + const failure: unknown = await StrataProcessJournal.open(root, 'strata-v1').catch((error: unknown) => error) + + expect(failure).toBeInstanceOf(AtomicCoreError) + expect((failure as AtomicCoreError).code).toBe('IO_ERROR') + expect((failure as AtomicCoreError & { cause?: unknown }).cause).toMatchObject({ code: 'ENOENT' }) +}) diff --git a/src/runtime/strata/strata-process-journal.ts b/src/runtime/strata/strata-process-journal.ts index 35997658..2d5598ce 100644 --- a/src/runtime/strata/strata-process-journal.ts +++ b/src/runtime/strata/strata-process-journal.ts @@ -121,9 +121,22 @@ export class StrataProcessJournal { scopeId: string, verify: Verify = verifyProcessIdentity ): Promise { - await mkdir(root, { recursive: true, mode: 0o700 }) - if (!(await lstat(root)).isDirectory()) corrupt() - const canonical = await realpath(root) + let canonical: string + try { + await mkdir(root, { recursive: true, mode: 0o700 }) + if (!(await lstat(root)).isDirectory()) corrupt() + canonical = await realpath(root) + } catch (error) { + // The journal root is the GPU-ownership evidence, so refusal stays fatal here. It must + // cross the core boundary as a coded error that keeps the filesystem cause. + if (error instanceof AtomicCoreError) throw error + throw new AtomicCoreError( + 'IO_ERROR', + 'Strata process journal is unavailable; GPU ownership remains blocked.', + undefined, + { cause: error } + ) + } let state: State = { version: 1, scopeId, entries: [] } const path = join(canonical, 'processes.json') try {