diff --git a/docs/decisions/2026-11-21-preserve-filesystem-cause-on-settings-write-errors.md b/docs/decisions/2026-11-21-preserve-filesystem-cause-on-settings-write-errors.md new file mode 100644 index 00000000..d25a5bf0 --- /dev/null +++ b/docs/decisions/2026-11-21-preserve-filesystem-cause-on-settings-write-errors.md @@ -0,0 +1,27 @@ +--- +date: 2026-11-21 +title: "Preserve the filesystem cause on settings write IO_ERRORs" +--- + +# 2026-11-21 — Preserve the filesystem cause on settings write IO_ERRORs + +- **Context:** `SettingsStore.persist` in `src/settings/store.ts` wraps a failed `mkdir`, + `writeFile` or `rename` into `new AtomicCoreError('IO_ERROR', ...)` without passing + `{ cause: e }`. The OS errno (`EPERM`, `EACCES`, `EBUSY`, `ENOSPC`, `EIO`, …) on the thrown + `ErrnoException` is therefore dropped before `classifyFailure` and `diagnosticTags` in + `src/telemetry/diagnostics.ts` can see it: `errorChain` stops at the `AtomicCoreError`, every + settings write failure is reported as `category: 'unknown', reason: 'unknown'` without a + `cause_code`, and the control route surfaces it as `IO_ERROR: http request: unknown` even for + an ordinary permission or file-lock condition (event ATOMIC-CHAT-CORE-DN, win32). +- **Decision:** Pass `{ cause: e }` to that `AtomicCoreError` in `SettingsStore.persist`. + Message, `code`, `details` and error behaviour stay as they are. +- **Consequences:** `ErrorBody` and `toJSON()` remain byte-identical on the wire, while internal + failure classification and telemetry retain the underlying OS errno through `Error.cause` and + can report `disk_permission`, `disk_file_locked`, `disk_full`, `disk_path_too_long`, + `disk_io` or `disk_device_lost` with the real `cause_code`. This makes the next occurrence + diagnosable; it does not retry the write and does not make the failing Windows write succeed. + The same repair was already applied to `src/lock/instance-lock.ts` and to engine installs. +- **Owner:** team. +- **Links:** `src/settings/store.ts`, `src/settings/store-persist-cause.test.ts`, + `docs/decisions/2026-11-03-preserve-filesystem-cause-on-instance-lock-io-errors.md`, + `docs/decisions/2026-11-06-preserve-cause-on-staged-engine-install-errors.md`. diff --git a/docs/decisions/INDEX.md b/docs/decisions/INDEX.md index 77a55ce8..fb9801b8 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) +- [Preserve the filesystem cause on settings write IO_ERRORs](2026-11-21-preserve-filesystem-cause-on-settings-write-errors.md) diff --git a/src/settings/store-persist-cause.test.ts b/src/settings/store-persist-cause.test.ts new file mode 100644 index 00000000..a0ccfb47 --- /dev/null +++ b/src/settings/store-persist-cause.test.ts @@ -0,0 +1,62 @@ +import { describe, expect, it } from 'vitest' +import { AtomicCoreError } from '../contracts/index.js' +import { classifyFailure, diagnosticTags, errorChain } from '../telemetry/diagnostics.js' +import { SettingsStore, type SettingsFs } from './store.js' + +const PATH = '/data/atomic-core/settings.json' + +/** In-memory `node:fs/promises` subset whose rename can fail with a real errno code. */ +class FakeFs implements SettingsFs { + readonly files = new Map() + renameError: Error | undefined + + async readFile(path: string): Promise { + const text = this.files.get(path) + if (text === undefined) throw Object.assign(new Error(`ENOENT: ${path}`), { code: 'ENOENT' }) + return text + } + async writeFile(path: string, data: string): Promise { + this.files.set(path, data) + } + async rename(from: string, to: string): Promise { + if (this.renameError) throw this.renameError + const text = this.files.get(from) + if (text === undefined) throw Object.assign(new Error(`ENOENT: ${from}`), { code: 'ENOENT' }) + this.files.delete(from) + this.files.set(to, text) + } + async mkdir(): Promise { + return undefined + } + async stat(path: string): Promise { + if (!this.files.has(path)) throw Object.assign(new Error(`ENOENT: ${path}`), { code: 'ENOENT' }) + return {} + } +} + +describe('SettingsStore.persist failure', () => { + it('keeps the filesystem error behind a failed settings write', async () => { + const fs = new FakeFs() + const store = await SettingsStore.open(PATH, { fs, now: () => Date.UTC(2026, 10, 20) }) + // Windows commonly reports EPERM/EACCES when another process holds the target file open. + const locked = Object.assign(new Error('EPERM: operation not permitted, rename settings.json.tmp'), { + code: 'EPERM', + }) + fs.renameError = locked + + const failure = await store.update('llamacpp', { mlock: true }).then( + () => undefined, + (error: unknown) => error + ) + expect(failure).toBeInstanceOf(AtomicCoreError) + const error = failure as AtomicCoreError + expect(error.code).toBe('IO_ERROR') + // The HTTP body stays exactly as before: the cause is internal-only. + expect(error.toJSON()).toEqual({ code: 'IO_ERROR', message: error.message }) + expect(errorChain(error)).toEqual([error, locked]) + + const diagnostic = classifyFailure(error, { component: 'http', operation: 'request' }) + expect(diagnostic).toMatchObject({ category: 'operational', reason: 'disk_permission' }) + expect(diagnosticTags(error, diagnostic)).toMatchObject({ cause_code: 'EPERM' }) + }) +}) diff --git a/src/settings/store.ts b/src/settings/store.ts index e963eb64..0d5d43c1 100644 --- a/src/settings/store.ts +++ b/src/settings/store.ts @@ -580,7 +580,11 @@ export class SettingsStore { await this.fs.writeFile(tmp, text, { encoding: 'utf8', mode: 0o600 }) await this.fs.rename(tmp, this.path) } catch (e) { - throw new AtomicCoreError('IO_ERROR', `cannot write ${this.path}: ${(e as Error).message}`) + // Keep the OS errno (`EPERM`, `EACCES`, `ENOSPC`, …) reachable for failure diagnostics; the + // wire body still carries only code and message. + throw new AtomicCoreError('IO_ERROR', `cannot write ${this.path}: ${(e as Error).message}`, undefined, { + cause: e, + }) } } }