@skillsmith/core 0.9.0 → 0.10.0

package/dist/src/journal/journal.test.js

@@ -0,0 +1,171 @@
+/**
+ * @fileoverview Unit tests for the change-journal writer + reader
+ *               (SMI-5456 Wave 1 Step 3 / SMI-5470).
+ * @module @skillsmith/core/journal/journal.test
+ *
+ * Covers two of the three P-5 invariants named in
+ * docs/internal/implementation/smi-5456-skillsmith-agent-wave1.md's
+ * "Shared-State / Coordination Audit" table for `~/.skillsmith/journal`:
+ *   - "journal module: concurrent-apply serialization test" (below)
+ *   - "journal module: chain-verification test" (below)
+ * The third (undo round-trip / refusal / scope fence) lives in
+ * `@skillsmith/mcp-server`'s `tests/unit/undo-apply.test.ts`, since it
+ * needs the mcp-server apply-family tools to produce a realistic changeset.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { appendJournalRecord, isCorruptTailError } from './writer.js';
+import { verifyJournalChain } from './reader.js';
+import { getJournalFilePath, resetJournalSessionIdForTests } from './path.js';
+let TEST_DIR;
+let PREV_OVERRIDE;
+beforeEach(() => {
+    TEST_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'skillsmith-journal-'));
+    PREV_OVERRIDE = process.env['SKILLSMITH_JOURNAL_DIR'];
+    process.env['SKILLSMITH_JOURNAL_DIR'] = TEST_DIR;
+    resetJournalSessionIdForTests();
+});
+afterEach(() => {
+    if (PREV_OVERRIDE !== undefined)
+        process.env['SKILLSMITH_JOURNAL_DIR'] = PREV_OVERRIDE;
+    else
+        delete process.env['SKILLSMITH_JOURNAL_DIR'];
+    if (TEST_DIR && fs.existsSync(TEST_DIR))
+        fs.rmSync(TEST_DIR, { recursive: true, force: true });
+    resetJournalSessionIdForTests();
+});
+function fixtureRecord(suggestionId) {
+    return {
+        schema: 1,
+        ts: Date.now(),
+        session_id: 'test-session',
+        tool: 'apply_namespace_rename',
+        action: 'apply',
+        suggestion_id: suggestionId,
+        target_path: `/tmp/skill-${suggestionId}.md`,
+        before_hash: 'before-hash',
+        after_hash: 'after-hash',
+        approval: 'apply',
+        backup_ref: '/tmp/backup',
+        detail: null,
+    };
+}
+describe('journal chain verification', () => {
+    it('a valid chain (multiple sequential appends) passes verification', async () => {
+        await appendJournalRecord(fixtureRecord('a'));
+        await appendJournalRecord(fixtureRecord('b'));
+        await appendJournalRecord(fixtureRecord('c'));
+        const result = await verifyJournalChain();
+        expect(result.valid).toBe(true);
+        expect(result.records).toHaveLength(3);
+        expect(result.breakAt).toBeUndefined();
+        // The chain is genuinely linked, not just three independent records.
+        expect(result.records[1].prev_hash).toBe(result.records[0].record_hash);
+        expect(result.records[2].prev_hash).toBe(result.records[1].record_hash);
+    });
+    it('an empty / never-written journal is a valid, empty chain (never throws)', async () => {
+        const result = await verifyJournalChain();
+        expect(result).toEqual({ valid: true, records: [] });
+    });
+    it('a tampered middle record breaks the chain at the correct index', async () => {
+        await appendJournalRecord(fixtureRecord('a'));
+        await appendJournalRecord(fixtureRecord('b'));
+        await appendJournalRecord(fixtureRecord('c'));
+        const filePath = getJournalFilePath();
+        const lines = fs
+            .readFileSync(filePath, 'utf-8')
+            .split('\n')
+            .filter((l) => l.length > 0);
+        const tampered = JSON.parse(lines[1]);
+        tampered.suggestion_id = 'TAMPERED';
+        lines[1] = JSON.stringify(tampered);
+        fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf-8');
+        const result = await verifyJournalChain();
+        expect(result.valid).toBe(false);
+        expect(result.breakAt).toBe(1);
+        // Everything before the tamper is still reported as verified evidence.
+        expect(result.records).toHaveLength(1);
+        expect(result.records[0].suggestion_id).toBe('a');
+    });
+    it('a corrupt tail line is reported via breakAt, never thrown', async () => {
+        await appendJournalRecord(fixtureRecord('a'));
+        await appendJournalRecord(fixtureRecord('b'));
+        const filePath = getJournalFilePath();
+        fs.appendFileSync(filePath, 'this is not json\n', 'utf-8');
+        const outcome = await verifyJournalChain();
+        expect(outcome.valid).toBe(false);
+        expect(outcome.breakAt).toBe(2);
+        expect(outcome.records).toHaveLength(2);
+    });
+});
+describe('journal writer refuses to append past a corrupt tail (governance follow-up, SMI-5456)', () => {
+    it('rejects with a typed isCorruptTailError when the last line is unparseable', async () => {
+        await appendJournalRecord(fixtureRecord('a'));
+        const filePath = getJournalFilePath();
+        fs.appendFileSync(filePath, 'this is not json\n', 'utf-8');
+        let caught;
+        try {
+            await appendJournalRecord(fixtureRecord('b'));
+        }
+        catch (err) {
+            caught = err;
+        }
+        expect(caught).toBeDefined();
+        expect(isCorruptTailError(caught)).toBe(true);
+        expect(caught.message).toMatch(/corrupt|unverifiable/);
+        // The writer never wrote 'b' past the corrupt tail — the file still
+        // has exactly the original record plus the corrupt line.
+        const lines = fs
+            .readFileSync(filePath, 'utf-8')
+            .split('\n')
+            .filter((l) => l.length > 0);
+        expect(lines).toHaveLength(2);
+    });
+    it('does not wedge the write queue for subsequent callers — a fixed tail lets the next append through', async () => {
+        await appendJournalRecord(fixtureRecord('a'));
+        const filePath = getJournalFilePath();
+        fs.appendFileSync(filePath, 'this is not json\n', 'utf-8');
+        await expect(appendJournalRecord(fixtureRecord('b'))).rejects.toSatisfy(isCorruptTailError);
+        // Repair the tail (what a real operator/future recovery tool would do)
+        // and prove the queue moved forward rather than staying wedged on the
+        // rejected promise.
+        const lines = fs
+            .readFileSync(filePath, 'utf-8')
+            .split('\n')
+            .filter((l) => l.length > 0);
+        lines.pop();
+        fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf-8');
+        const record = await appendJournalRecord(fixtureRecord('c'));
+        expect(record.suggestion_id).toBe('c');
+        const result = await verifyJournalChain();
+        expect(result.valid).toBe(true);
+        expect(result.records.map((r) => r.suggestion_id)).toEqual(['a', 'c']);
+    });
+});
+describe('journal concurrent-apply serialization (P-5 single-writer invariant)', () => {
+    it('N concurrent journal writes produce N well-formed, correctly-chained records with no interleaved/torn lines', async () => {
+        const N = 25;
+        // Fire all N appends without awaiting between them — simulates
+        // apply_namespace_rename and apply_recommended_edit racing inside the
+        // same server process.
+        await Promise.all(Array.from({ length: N }, (_, i) => appendJournalRecord(fixtureRecord(`concurrent-${i}`))));
+        const filePath = getJournalFilePath();
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const lines = raw.split('\n').filter((l) => l.length > 0);
+        // No torn/interleaved lines: every line parses as JSON on its own.
+        expect(lines).toHaveLength(N);
+        for (const line of lines) {
+            expect(() => JSON.parse(line)).not.toThrow();
+        }
+        const result = await verifyJournalChain();
+        expect(result.valid).toBe(true);
+        expect(result.records).toHaveLength(N);
+        // Every suggestion_id we wrote shows up exactly once — no lost or
+        // duplicated writes from the race.
+        const seen = new Set(result.records.map((r) => r.suggestion_id));
+        expect(seen.size).toBe(N);
+    });
+});
+//# sourceMappingURL=journal.test.js.map

package/dist/src/journal/journal.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.test.js","sourceRoot":"","sources":["../../../src/journal/journal.test.ts"],"names":[],"mappings":"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"}

package/dist/src/journal/path.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Journal file-layout + process session-id resolution
+ *               (SMI-5456 Wave 1 Step 3 / SMI-5470).
+ * @module @skillsmith/core/journal/path
+ *
+ * File layout: `<configDir>/journal/journal.jsonl` — JSON Lines (one JSON
+ * object per line), append-only. Chosen over a single JSON array because:
+ *   - Appends are O(1) — no read-modify-rewrite of the whole file, unlike
+ *     `audit/namespace-overrides.ts`'s ledger (appropriate there because
+ *     that file is small, mutable config, not an ever-growing log).
+ *   - A line is the unit of both a write and a crash boundary: fsync'ing
+ *     one appended line can't corrupt any earlier line, so a torn last
+ *     write degrades to "one unreadable tail line" rather than an
+ *     unparseable whole file — exactly what `reader.ts`'s
+ *     "corrupt tail = report, never throw" contract needs.
+ *   - It's streamable / greppable for ad-hoc forensics without a parser.
+ *
+ * `SKILLSMITH_JOURNAL_DIR` overrides the default, mirroring
+ * `SKILLSMITH_AGENT_MARKER_DIR` (`../telemetry/agent-marker.ts`) — needed
+ * because macOS `os.homedir()` resolves via `getpwuid()` and ignores
+ * `process.env.HOME` mutations in tests.
+ */
+/** Env var overriding the journal directory (test isolation). */
+export declare const JOURNAL_DIR_ENV_VAR = "SKILLSMITH_JOURNAL_DIR";
+/** Absolute path to the journal file. Read-time resolved (not memoised) so
+ * tests can flip `SKILLSMITH_JOURNAL_DIR` between cases. */
+export declare function getJournalFilePath(): string;
+/**
+ * Process-lifetime session id shared by every journal record this server
+ * process writes, and by the in-process undo stack
+ * (`@skillsmith/mcp-server`'s `tools/apply-session.helpers.ts`) that keys
+ * "session-scoped undo" off the same lifetime: restarting the MCP server
+ * both mints a new session id here AND resets the undo stack (a fresh
+ * module load), so the two always agree without explicit coordination.
+ */
+export declare function getJournalSessionId(): string;
+/**
+ * Test-only reset. The session id is memoised for the process lifetime by
+ * design, but a single Vitest process runs many logically-independent
+ * "sessions" (test cases) — call this in `afterEach`/`beforeEach` to avoid
+ * cross-test bleed.
+ */
+export declare function resetJournalSessionIdForTests(): void;
+//# sourceMappingURL=path.d.ts.map

package/dist/src/journal/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../../src/journal/path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAMH,iEAAiE;AACjE,eAAO,MAAM,mBAAmB,2BAA2B,CAAA;AAO3D;4DAC4D;AAC5D,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAID;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAK5C;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD"}

package/dist/src/journal/path.js

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview Journal file-layout + process session-id resolution
+ *               (SMI-5456 Wave 1 Step 3 / SMI-5470).
+ * @module @skillsmith/core/journal/path
+ *
+ * File layout: `<configDir>/journal/journal.jsonl` — JSON Lines (one JSON
+ * object per line), append-only. Chosen over a single JSON array because:
+ *   - Appends are O(1) — no read-modify-rewrite of the whole file, unlike
+ *     `audit/namespace-overrides.ts`'s ledger (appropriate there because
+ *     that file is small, mutable config, not an ever-growing log).
+ *   - A line is the unit of both a write and a crash boundary: fsync'ing
+ *     one appended line can't corrupt any earlier line, so a torn last
+ *     write degrades to "one unreadable tail line" rather than an
+ *     unparseable whole file — exactly what `reader.ts`'s
+ *     "corrupt tail = report, never throw" contract needs.
+ *   - It's streamable / greppable for ad-hoc forensics without a parser.
+ *
+ * `SKILLSMITH_JOURNAL_DIR` overrides the default, mirroring
+ * `SKILLSMITH_AGENT_MARKER_DIR` (`../telemetry/agent-marker.ts`) — needed
+ * because macOS `os.homedir()` resolves via `getpwuid()` and ignores
+ * `process.env.HOME` mutations in tests.
+ */
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { getConfigDir } from '../config/index.js';
+/** Env var overriding the journal directory (test isolation). */
+export const JOURNAL_DIR_ENV_VAR = 'SKILLSMITH_JOURNAL_DIR';
+function getJournalDir() {
+    const override = process.env[JOURNAL_DIR_ENV_VAR];
+    return override && override.length > 0 ? override : join(getConfigDir(), 'journal');
+}
+/** Absolute path to the journal file. Read-time resolved (not memoised) so
+ * tests can flip `SKILLSMITH_JOURNAL_DIR` between cases. */
+export function getJournalFilePath() {
+    return join(getJournalDir(), 'journal.jsonl');
+}
+let processSessionId;
+/**
+ * Process-lifetime session id shared by every journal record this server
+ * process writes, and by the in-process undo stack
+ * (`@skillsmith/mcp-server`'s `tools/apply-session.helpers.ts`) that keys
+ * "session-scoped undo" off the same lifetime: restarting the MCP server
+ * both mints a new session id here AND resets the undo stack (a fresh
+ * module load), so the two always agree without explicit coordination.
+ */
+export function getJournalSessionId() {
+    if (processSessionId === undefined) {
+        processSessionId = randomUUID();
+    }
+    return processSessionId;
+}
+/**
+ * Test-only reset. The session id is memoised for the process lifetime by
+ * design, but a single Vitest process runs many logically-independent
+ * "sessions" (test cases) — call this in `afterEach`/`beforeEach` to avoid
+ * cross-test bleed.
+ */
+export function resetJournalSessionIdForTests() {
+    processSessionId = undefined;
+}
+//# sourceMappingURL=path.js.map

package/dist/src/journal/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../../../src/journal/path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjD,iEAAiE;AACjE,MAAM,CAAC,MAAM,mBAAmB,GAAG,wBAAwB,CAAA;AAE3D,SAAS,aAAa;IACpB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAA;IACjD,OAAO,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,SAAS,CAAC,CAAA;AACrF,CAAC;AAED;4DAC4D;AAC5D,MAAM,UAAU,kBAAkB;IAChC,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,eAAe,CAAC,CAAA;AAC/C,CAAC;AAED,IAAI,gBAAoC,CAAA;AAExC;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB;IACjC,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACnC,gBAAgB,GAAG,UAAU,EAAE,CAAA;IACjC,CAAC;IACD,OAAO,gBAAgB,CAAA;AACzB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B;IAC3C,gBAAgB,GAAG,SAAS,CAAA;AAC9B,CAAC"}

package/dist/src/journal/reader.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Change-journal reader — hash-chain verification
+ *               (SMI-5456 Wave 1 Step 3 / SMI-5470).
+ * @module @skillsmith/core/journal/reader
+ *
+ * Never throws. The journal exists to be evidence (PRD §7 / §10 exclusion
+ * 1); a reader that raises on the first bad byte can't produce that
+ * evidence when it matters most (after a tamper or a crash mid-write). A
+ * missing file is a valid, empty chain. A corrupt or tampered line is
+ * reported via `breakAt` — the caller (e.g. `undo_apply`, or a future audit
+ * surface) decides what to do with a break, but the reader never decides
+ * for them by throwing.
+ */
+import type { JournalRecord } from './types.js';
+export interface ChainVerificationResult {
+    /** `true` iff every line parsed, chained, and hash-verified cleanly. */
+    valid: boolean;
+    /** Records verified so far — the full chain when `valid` is `true`, or
+     * every record BEFORE the break when `valid` is `false`. */
+    records: JournalRecord[];
+    /** 0-based line index of the first unparseable / malformed / tampered
+     * record. Present iff `valid` is `false`. */
+    breakAt?: number;
+}
+/**
+ * Verify the journal's hash chain line-by-line: each record's `prev_hash`
+ * must equal the previous record's `record_hash` (or `JOURNAL_GENESIS_HASH`
+ * for the first line), and each record's own `record_hash` must match a
+ * fresh recomputation from its other fields (SMI-5456 §7 tamper signal).
+ *
+ * @param filePath - Override for tests; defaults to the resolved journal path.
+ */
+export declare function verifyJournalChain(filePath?: string): Promise<ChainVerificationResult>;
+/** Convenience wrapper: the verified records, or as many as verified before
+ * a break. Callers that need the break position should use
+ * `verifyJournalChain` directly. */
+export declare function readJournalRecords(filePath?: string): Promise<JournalRecord[]>;
+//# sourceMappingURL=reader.d.ts.map

package/dist/src/journal/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../../src/journal/reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,MAAM,WAAW,uBAAuB;IACtC,wEAAwE;IACxE,KAAK,EAAE,OAAO,CAAA;IACd;gEAC4D;IAC5D,OAAO,EAAE,aAAa,EAAE,CAAA;IACxB;iDAC6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAwBD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CA6C5F;AAED;;oCAEoC;AACpC,wBAAsB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAGpF"}

package/dist/src/journal/reader.js

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview Change-journal reader — hash-chain verification
+ *               (SMI-5456 Wave 1 Step 3 / SMI-5470).
+ * @module @skillsmith/core/journal/reader
+ *
+ * Never throws. The journal exists to be evidence (PRD §7 / §10 exclusion
+ * 1); a reader that raises on the first bad byte can't produce that
+ * evidence when it matters most (after a tamper or a crash mid-write). A
+ * missing file is a valid, empty chain. A corrupt or tampered line is
+ * reported via `breakAt` — the caller (e.g. `undo_apply`, or a future audit
+ * surface) decides what to do with a break, but the reader never decides
+ * for them by throwing.
+ */
+import { readFile } from 'node:fs/promises';
+import { getJournalFilePath } from './path.js';
+import { computeRecordHash } from './writer.js';
+import { JOURNAL_GENESIS_HASH } from './hash.js';
+/** Narrow an arbitrary parsed JSON value down to the `JournalRecord` shape. */
+function isJournalRecordShape(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const r = value;
+    return (typeof r.schema === 'number' &&
+        typeof r.ts === 'number' &&
+        typeof r.session_id === 'string' &&
+        typeof r.tool === 'string' &&
+        (r.action === 'apply' || r.action === 'error' || r.action === 'undo') &&
+        (r.suggestion_id === null || typeof r.suggestion_id === 'string') &&
+        (r.target_path === null || typeof r.target_path === 'string') &&
+        (r.before_hash === null || typeof r.before_hash === 'string') &&
+        (r.after_hash === null || typeof r.after_hash === 'string') &&
+        (r.approval === null || typeof r.approval === 'string') &&
+        (r.backup_ref === null || typeof r.backup_ref === 'string') &&
+        (r.detail === null || typeof r.detail === 'string') &&
+        typeof r.prev_hash === 'string' &&
+        typeof r.record_hash === 'string');
+}
+/**
+ * Verify the journal's hash chain line-by-line: each record's `prev_hash`
+ * must equal the previous record's `record_hash` (or `JOURNAL_GENESIS_HASH`
+ * for the first line), and each record's own `record_hash` must match a
+ * fresh recomputation from its other fields (SMI-5456 §7 tamper signal).
+ *
+ * @param filePath - Override for tests; defaults to the resolved journal path.
+ */
+export async function verifyJournalChain(filePath) {
+    const path = filePath ?? getJournalFilePath();
+    let raw;
+    try {
+        raw = await readFile(path, 'utf-8');
+    }
+    catch {
+        // Missing file (never written yet) — a valid, empty chain.
+        return { valid: true, records: [] };
+    }
+    const lines = raw.split('\n').filter((line) => line.trim().length > 0);
+    const records = [];
+    let expectedPrevHash = JOURNAL_GENESIS_HASH;
+    for (let i = 0; i < lines.length; i++) {
+        let parsed;
+        try {
+            parsed = JSON.parse(lines[i]);
+        }
+        catch {
+            // Corrupt/torn line (e.g. a crash mid-append) — report, don't throw.
+            return { valid: false, records, breakAt: i };
+        }
+        if (!isJournalRecordShape(parsed)) {
+            return { valid: false, records, breakAt: i };
+        }
+        if (parsed.prev_hash !== expectedPrevHash) {
+            // Chain discontinuity — a record was deleted, reordered, or its
+            // neighbor was tampered.
+            return { valid: false, records, breakAt: i };
+        }
+        const { record_hash, ...rest } = parsed;
+        if (computeRecordHash(rest) !== record_hash) {
+            // The record's own content was edited after the fact.
+            return { valid: false, records, breakAt: i };
+        }
+        records.push(parsed);
+        expectedPrevHash = record_hash;
+    }
+    return { valid: true, records };
+}
+/** Convenience wrapper: the verified records, or as many as verified before
+ * a break. Callers that need the break position should use
+ * `verifyJournalChain` directly. */
+export async function readJournalRecords(filePath) {
+    const result = await verifyJournalChain(filePath);
+    return result.records;
+}
+//# sourceMappingURL=reader.js.map

package/dist/src/journal/reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.js","sourceRoot":"","sources":["../../../src/journal/reader.ts"],"names":[],"mappings":"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"}

package/dist/src/journal/types.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview Change-journal record shape (SMI-5456 Wave 1 Step 3 / SMI-5470).
+ * @module @skillsmith/core/journal/types
+ *
+ * The journal is the trust-loop evidence base described in
+ * docs/internal/product/prd-skillsmith-agent.md §7: an append-only,
+ * hash-chained record of every mutation the apply-family MCP tools make
+ * (`apply_namespace_rename`, `apply_recommended_edit`) plus the `undo_apply`
+ * tool that reverses them. It is the substrate PRD §10 exclusion 1 points at
+ * before autonomy can ever be relaxed ("90 days of journal data shows ≥95%
+ * suggestion-acceptance and zero rollback incidents").
+ *
+ * Field naming is snake_case (not the package's usual camelCase) because the
+ * journal is a durable on-disk wire format, not an in-memory TS shape — it
+ * mirrors the telemetry wire format's convention (SMI-5012) for the same
+ * reason: an on-disk/over-the-wire record should read the same regardless of
+ * which language eventually parses it.
+ */
+/** Bump on a breaking shape change to `JournalRecord`. */
+export declare const JOURNAL_SCHEMA_VERSION = 1;
+/**
+ * `'apply'`   — an apply-family tool successfully mutated a file.
+ * `'error'`   — an apply-family tool attempted a mutation and it failed
+ *               (the `detail` field carries the typed error kind).
+ * `'undo'`    — `undo_apply` successfully reversed a prior `'apply'` record.
+ */
+export type JournalAction = 'apply' | 'error' | 'undo';
+/**
+ * Every field the caller supplies. The writer (`writer.ts`) fills in
+ * `prev_hash` + `record_hash` to complete a `JournalRecord`.
+ *
+ * Field semantics:
+ * - `suggestion_id` — the `collisionId` the mutation was applied for.
+ * - `target_path` — the on-disk file whose CONTENT the record's hashes
+ *   describe. For a single-file mutation (prose edit, command/agent rename)
+ *   this is the mutated file itself. For a skill-directory rename
+ *   (`rename_skill_dir_and_frontmatter`) this is `<newSkillDir>/SKILL.md` —
+ *   the one file whose bytes actually changed; the directory rename itself
+ *   is not content-hashable and is intentionally out of this record's scope
+ *   (see `tools/apply-journal.helpers.ts` header in `@skillsmith/mcp-server`
+ *   for the full rationale).
+ * - `before_hash` / `after_hash` — sha256 of `target_path`'s content
+ *   immediately before / after the mutation. `null` where not applicable
+ *   (e.g. an `'error'` record where the mutation never reached a
+ *   content-changing step, so there is no "after" state to hash).
+ * - `approval` — the caller-supplied approval mode that authorized the
+ *   mutation, e.g. `'apply'` / `'custom'` (namespace rename) or
+ *   `'apply_with_confirmation'` (recommended edit). Always non-null for
+ *   `'apply'`/`'error'` records (the confirmation gate ran); `'undo'` for
+ *   undo records.
+ * - `backup_ref` — absolute path to the apply tool's own pre-mutation
+ *   backup directory (from `createSkillBackup` / `createProseBackup`).
+ *   `null` for `'error'` and `'undo'` records — an error may not have
+ *   reached the backup step, and an undo record documents a restore that
+ *   already happened rather than creating a new backup.
+ * - `detail` — free-text elaboration. Populated with the typed error
+ *   `kind` (e.g. `'namespace.rename.backup_failed'`) on `'error'` records;
+ *   `null` otherwise.
+ */
+export interface JournalRecordFields {
+    schema: number;
+    ts: number;
+    session_id: string;
+    tool: string;
+    action: JournalAction;
+    suggestion_id: string | null;
+    target_path: string | null;
+    before_hash: string | null;
+    after_hash: string | null;
+    approval: string | null;
+    backup_ref: string | null;
+    detail: string | null;
+}
+/** Input to `appendJournalRecord` — the writer computes the rest. */
+export type JournalRecordInput = JournalRecordFields;
+/**
+ * A fully-formed, on-disk journal record (one JSON-Lines row). `prev_hash`
+ * chains to the previous record's `record_hash` (or `JOURNAL_GENESIS_HASH`
+ * for the first record); `record_hash` commits to every other field
+ * INCLUDING `prev_hash`, so any single-record tamper is detectable by
+ * recomputing it — see `reader.ts:verifyJournalChain`.
+ */
+export interface JournalRecord extends JournalRecordFields {
+    prev_hash: string;
+    record_hash: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/journal/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/journal/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,0DAA0D;AAC1D,eAAO,MAAM,sBAAsB,IAAI,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAA;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,EAAE,EAAE,MAAM,CAAA;IACV,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,aAAa,CAAA;IACrB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED,qEAAqE;AACrE,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,CAAA;AAEpD;;;;;;GAMG;AACH,MAAM,WAAW,aAAc,SAAQ,mBAAmB;IACxD,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;CACpB"}

package/dist/src/journal/types.js

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Change-journal record shape (SMI-5456 Wave 1 Step 3 / SMI-5470).
+ * @module @skillsmith/core/journal/types
+ *
+ * The journal is the trust-loop evidence base described in
+ * docs/internal/product/prd-skillsmith-agent.md §7: an append-only,
+ * hash-chained record of every mutation the apply-family MCP tools make
+ * (`apply_namespace_rename`, `apply_recommended_edit`) plus the `undo_apply`
+ * tool that reverses them. It is the substrate PRD §10 exclusion 1 points at
+ * before autonomy can ever be relaxed ("90 days of journal data shows ≥95%
+ * suggestion-acceptance and zero rollback incidents").
+ *
+ * Field naming is snake_case (not the package's usual camelCase) because the
+ * journal is a durable on-disk wire format, not an in-memory TS shape — it
+ * mirrors the telemetry wire format's convention (SMI-5012) for the same
+ * reason: an on-disk/over-the-wire record should read the same regardless of
+ * which language eventually parses it.
+ */
+/** Bump on a breaking shape change to `JournalRecord`. */
+export const JOURNAL_SCHEMA_VERSION = 1;
+//# sourceMappingURL=types.js.map

package/dist/src/journal/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/journal/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,0DAA0D;AAC1D,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAA"}

package/dist/src/journal/writer.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Change-journal writer — single-writer, fsync'd, hash-chained
+ *               append (SMI-5456 Wave 1 Step 3 / SMI-5470).
+ * @module @skillsmith/core/journal/writer
+ *
+ * P-5 single-writer invariant (docs/internal/implementation/smi-5456-skillsmith-agent-wave1.md
+ * "Shared-State / Coordination Audit"): the journal file is written by the
+ * apply-family MCP tools ONLY, and every writer in this process funnels
+ * through `appendJournalRecord`, which serializes behind ONE module-scoped
+ * promise queue. That queue — not any per-caller locking — is what makes
+ * concurrent `apply_namespace_rename` / `apply_recommended_edit` / `undo_apply`
+ * calls in the same server process produce well-formed, correctly-chained
+ * lines instead of interleaved/torn writes.
+ *
+ * Durability: each append opens the file, writes the line, calls
+ * `FileHandle.sync()` (fsync), then closes — so a record that returns
+ * successfully is durable on disk before the caller's apply/undo response
+ * goes out, matching the "fsync'd appends" requirement in the plan's P-5
+ * table.
+ */
+import type { JournalRecord, JournalRecordInput } from './types.js';
+/**
+ * Recompute a record's `record_hash` from its other fields. Exported so the
+ * reader can independently verify each line without duplicating the
+ * canonicalization logic (drift between writer and reader would silently
+ * break every chain-verification call).
+ */
+export declare function computeRecordHash(record: Omit<JournalRecord, 'record_hash'>): string;
+/**
+ * Error thrown when the journal's last line cannot be parsed as a valid
+ * record — the writer cannot safely determine the chain head to append
+ * after. This is distinct from the reader's "corrupt tail = report, never
+ * throw" contract: a reader is producing evidence about the past and must
+ * degrade gracefully; a writer is about to create NEW evidence and silently
+ * starting a fresh chain over a corrupt/tampered tail would hide exactly
+ * the tamper signal the chain exists to surface.
+ */
+export interface JournalCorruptTailError extends Error {
+    kind: 'journal.write.corrupt_tail';
+}
+export declare function isCorruptTailError(err: unknown): err is JournalCorruptTailError;
+/**
+ * Append a record to the journal. Serialized behind the module-scoped
+ * write queue and fsync'd before the returned promise resolves.
+ *
+ * Callers (the apply-family tools) should treat a rejection as fail-soft —
+ * the journal is an evidence trail, not a gate on the user's mutation —
+ * and log rather than propagate. See `tools/apply-journal.helpers.ts` in
+ * `@skillsmith/mcp-server` for the call-site convention.
+ */
+export declare function appendJournalRecord(input: JournalRecordInput): Promise<JournalRecord>;
+//# sourceMappingURL=writer.d.ts.map

package/dist/src/journal/writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../../src/journal/writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AA4BnE;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC,GAAG,MAAM,CAEpF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAwB,SAAQ,KAAK;IACpD,IAAI,EAAE,4BAA4B,CAAA;CACnC;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,uBAAuB,CAK/E;AAkCD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAQrF"}