Skip to content
Open
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
38 changes: 38 additions & 0 deletions docs/decisions/2026-11-20-code-strata-journal-root-failures.md
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions docs/decisions/INDEX.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
28 changes: 28 additions & 0 deletions src/runtime/strata/strata-process-journal-open.test.ts
Original file line number Diff line number Diff line change
@@ -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' })
})
19 changes: 16 additions & 3 deletions src/runtime/strata/strata-process-journal.ts
Original file line number Diff line number Diff line change
Expand Up @@ -121,9 +121,22 @@ export class StrataProcessJournal {
scopeId: string,
verify: Verify = verifyProcessIdentity
): Promise<StrataProcessJournal> {
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 {
Expand Down
Loading