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
Original file line number Diff line number Diff line change
@@ -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`.
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)
- [Preserve the filesystem cause on settings write IO_ERRORs](2026-11-21-preserve-filesystem-cause-on-settings-write-errors.md)
62 changes: 62 additions & 0 deletions src/settings/store-persist-cause.test.ts
Original file line number Diff line number Diff line change
@@ -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<string, string>()
renameError: Error | undefined

async readFile(path: string): Promise<string> {
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<void> {
this.files.set(path, data)
}
async rename(from: string, to: string): Promise<void> {
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<string | undefined> {
return undefined
}
async stat(path: string): Promise<unknown> {
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' })
})
})
6 changes: 5 additions & 1 deletion src/settings/store.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
})
}
}
}
Expand Down
Loading