@skillsmith/core 0.9.0 → 0.11.0

package/dist/src/journal/writer.js

@@ -0,0 +1,125 @@
+/**
+ * @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 { mkdir, open, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { JOURNAL_GENESIS_HASH, sha256Hex } from './hash.js';
+import { getJournalFilePath } from './path.js';
+/**
+ * Canonical (fixed-key-order) JSON of every hash-chain-relevant field,
+ * INCLUDING `prev_hash` but EXCLUDING `record_hash` itself. Plain
+ * `JSON.stringify` is sufficient canonicalization here because the object
+ * literal below is always constructed with the same key order — a full
+ * canonical-JSON library would be overkill for a single fixed shape.
+ */
+function canonicalFields(record) {
+    const ordered = {
+        schema: record.schema,
+        ts: record.ts,
+        session_id: record.session_id,
+        tool: record.tool,
+        action: record.action,
+        suggestion_id: record.suggestion_id,
+        target_path: record.target_path,
+        before_hash: record.before_hash,
+        after_hash: record.after_hash,
+        approval: record.approval,
+        backup_ref: record.backup_ref,
+        detail: record.detail,
+        prev_hash: record.prev_hash,
+    };
+    return JSON.stringify(ordered);
+}
+/**
+ * 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 function computeRecordHash(record) {
+    return sha256Hex(canonicalFields(record));
+}
+export function isCorruptTailError(err) {
+    return (err instanceof Error &&
+        err.kind === 'journal.write.corrupt_tail');
+}
+async function getLastRecordHash(filePath) {
+    let raw;
+    try {
+        raw = await readFile(filePath, 'utf-8');
+    }
+    catch {
+        return JOURNAL_GENESIS_HASH;
+    }
+    const lines = raw.split('\n').filter((line) => line.trim().length > 0);
+    if (lines.length === 0)
+        return JOURNAL_GENESIS_HASH;
+    const lastLine = lines[lines.length - 1];
+    try {
+        const parsed = JSON.parse(lastLine);
+        if (typeof parsed.record_hash === 'string' && parsed.record_hash.length > 0) {
+            return parsed.record_hash;
+        }
+    }
+    catch {
+        // fall through to the corrupt-tail error below
+    }
+    const err = new Error('journal tail is corrupt or unparseable; refusing to append past an unverifiable chain head');
+    err.kind = 'journal.write.corrupt_tail';
+    throw err;
+}
+// P-5 single-writer invariant: every append in this process funnels through
+// this one queue, regardless of which apply-family tool called it.
+let writeQueue = Promise.resolve();
+/**
+ * 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 function appendJournalRecord(input) {
+    const task = writeQueue.then(() => doAppend(input));
+    // A rejected append must not wedge the queue for subsequent callers.
+    writeQueue = task.then(() => undefined, () => undefined);
+    return task;
+}
+async function doAppend(input) {
+    const filePath = getJournalFilePath();
+    await mkdir(dirname(filePath), { recursive: true });
+    // Propagates as-is (including `JournalCorruptTailError`) — callers use
+    // `isCorruptTailError` to distinguish it from a generic I/O failure.
+    const prevHash = await getLastRecordHash(filePath);
+    const withoutHash = { ...input, prev_hash: prevHash };
+    const record = { ...withoutHash, record_hash: computeRecordHash(withoutHash) };
+    const line = JSON.stringify(record) + '\n';
+    const handle = await open(filePath, 'a');
+    try {
+        await handle.appendFile(line, 'utf-8');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    return record;
+}
+//# sourceMappingURL=writer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../../src/journal/writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC,OAAO,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAG9C;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,MAA0C;IACjE,MAAM,OAAO,GAAG;QACd,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,EAAE,EAAE,MAAM,CAAC,EAAE;QACb,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,SAAS,EAAE,MAAM,CAAC,SAAS;KAC5B,CAAA;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;AAChC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAA0C;IAC1E,OAAO,SAAS,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAA;AAC3C,CAAC;AAeD,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,OAAO,CACL,GAAG,YAAY,KAAK;QACnB,GAAwC,CAAC,IAAI,KAAK,4BAA4B,CAChF,CAAA;AACH,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAC,QAAgB;IAC/C,IAAI,GAAW,CAAA;IACf,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,oBAAoB,CAAA;IAC7B,CAAC;IAED,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IACtE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,oBAAoB,CAAA;IAEnD,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAE,CAAA;IACzC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAA2B,CAAA;QAC7D,IAAI,OAAO,MAAM,CAAC,WAAW,KAAK,QAAQ,IAAI,MAAM,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5E,OAAO,MAAM,CAAC,WAAW,CAAA;QAC3B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,+CAA+C;IACjD,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,KAAK,CACnB,4FAA4F,CAClE,CAAA;IAC5B,GAAG,CAAC,IAAI,GAAG,4BAA4B,CAAA;IACvC,MAAM,GAAG,CAAA;AACX,CAAC;AAED,4EAA4E;AAC5E,mEAAmE;AACnE,IAAI,UAAU,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAA;AAEjD;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAyB;IAC3D,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAA;IACnD,qEAAqE;IACrE,UAAU,GAAG,IAAI,CAAC,IAAI,CACpB,GAAG,EAAE,CAAC,SAAS,EACf,GAAG,EAAE,CAAC,SAAS,CAChB,CAAA;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,KAAyB;IAC/C,MAAM,QAAQ,GAAG,kBAAkB,EAAE,CAAA;IACrC,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAEnD,uEAAuE;IACvE,qEAAqE;IACrE,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,QAAQ,CAAC,CAAA;IAElD,MAAM,WAAW,GAAuC,EAAE,GAAG,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAA;IACzF,MAAM,MAAM,GAAkB,EAAE,GAAG,WAAW,EAAE,WAAW,EAAE,iBAAiB,CAAC,WAAW,CAAC,EAAE,CAAA;IAE7F,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,IAAI,CAAA;IAC1C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAA;IACxC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QACtC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;IACrB,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAA;IACtB,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/src/logging/context.d.ts

@@ -0,0 +1,58 @@
+/**
+ * SMI-5615: Correlation-ID context for the shared logging + telemetry pipeline.
+ *
+ * Lives in `logging/` (not `telemetry/wrap.ts`) so both `telemetry/wrap.ts`
+ * and the future `logging/logger.ts` (Wave 2) can read/write it without a
+ * circular import between the `telemetry` and `logging` subtrees (F4). This
+ * module imports ONLY `node:async_hooks` — it must never import from
+ * `../telemetry/*`, or the one-directional `telemetry -> logging` boundary
+ * this split exists to guarantee breaks. An ESLint `no-restricted-imports`
+ * boundary guard (Wave 2, §1) enforces this mechanically; keep it true by
+ * construction here regardless.
+ *
+ * Mirrors the existing `markerStorage` / `runWithMarkerContext` pattern in
+ * `packages/core/src/telemetry/wrap.ts`: a module-scoped `AsyncLocalStorage`
+ * instance, installed per-call via a `runWith*` function, read live via
+ * `.getStore()` — never memoised. `AsyncLocalStorage` (not a module-scoped
+ * variable) because harnesses batch PARALLEL tool calls to one server
+ * process; a plain module slot would let call A's completion clear call B's
+ * still-in-flight correlation ID.
+ *
+ * Install-site correction (F1, see `docs/internal/implementation/production-error-logging.md`):
+ * the correlation ID is installed by `withTelemetry` around its *entire*
+ * `wrappedFn` body (try + finally), not just the inner `handler(...args)`
+ * call — otherwise the emit path's `getCorrelationId()` read happens after
+ * the scope has already unwound and always returns `undefined`.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * Per-call correlation ID, scoped via `runWithCorrelationId`. Read live via
+ * `getCorrelationId()` — never memoised — so every consumer (the
+ * `withTelemetry` emit path, and later `logging/logger.ts`) observes the ID
+ * for its OWN call's async continuation, never a sibling's.
+ */
+export declare const correlationIdStorage: AsyncLocalStorage<string>;
+/**
+ * Run `fn` with `id` installed as the correlation ID for every telemetry
+ * emit / log call inside its async continuation. Concurrency-safe: parallel
+ * invocations each see only their own ID; code outside any
+ * `runWithCorrelationId` scope sees no ID (`getCorrelationId()` returns
+ * `undefined`).
+ *
+ * Callers should mint-if-absent (`getCorrelationId() ?? randomUUID()`)
+ * before calling this, so a wrapped call nested inside another wrapped
+ * call's continuation inherits the outer ID instead of fragmenting one
+ * logical request's trace across multiple IDs.
+ */
+export declare function runWithCorrelationId<T>(id: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Read the correlation ID installed for the current async continuation, or
+ * `undefined` if called outside any `runWithCorrelationId` scope (e.g.
+ * fire-and-forget work started before any tool call establishes a scope).
+ *
+ * Must be read synchronously at the log/emit call site — never deferred to
+ * an async flush/rotation callback, which could fire outside the
+ * originating call's scope (F3).
+ */
+export declare function getCorrelationId(): string | undefined;
+//# sourceMappingURL=context.d.ts.map

package/dist/src/logging/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/logging/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,2BAAkC,CAAA;AAEnE;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEpF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAErD"}

package/dist/src/logging/context.js

@@ -0,0 +1,62 @@
+/**
+ * SMI-5615: Correlation-ID context for the shared logging + telemetry pipeline.
+ *
+ * Lives in `logging/` (not `telemetry/wrap.ts`) so both `telemetry/wrap.ts`
+ * and the future `logging/logger.ts` (Wave 2) can read/write it without a
+ * circular import between the `telemetry` and `logging` subtrees (F4). This
+ * module imports ONLY `node:async_hooks` — it must never import from
+ * `../telemetry/*`, or the one-directional `telemetry -> logging` boundary
+ * this split exists to guarantee breaks. An ESLint `no-restricted-imports`
+ * boundary guard (Wave 2, §1) enforces this mechanically; keep it true by
+ * construction here regardless.
+ *
+ * Mirrors the existing `markerStorage` / `runWithMarkerContext` pattern in
+ * `packages/core/src/telemetry/wrap.ts`: a module-scoped `AsyncLocalStorage`
+ * instance, installed per-call via a `runWith*` function, read live via
+ * `.getStore()` — never memoised. `AsyncLocalStorage` (not a module-scoped
+ * variable) because harnesses batch PARALLEL tool calls to one server
+ * process; a plain module slot would let call A's completion clear call B's
+ * still-in-flight correlation ID.
+ *
+ * Install-site correction (F1, see `docs/internal/implementation/production-error-logging.md`):
+ * the correlation ID is installed by `withTelemetry` around its *entire*
+ * `wrappedFn` body (try + finally), not just the inner `handler(...args)`
+ * call — otherwise the emit path's `getCorrelationId()` read happens after
+ * the scope has already unwound and always returns `undefined`.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * Per-call correlation ID, scoped via `runWithCorrelationId`. Read live via
+ * `getCorrelationId()` — never memoised — so every consumer (the
+ * `withTelemetry` emit path, and later `logging/logger.ts`) observes the ID
+ * for its OWN call's async continuation, never a sibling's.
+ */
+export const correlationIdStorage = new AsyncLocalStorage();
+/**
+ * Run `fn` with `id` installed as the correlation ID for every telemetry
+ * emit / log call inside its async continuation. Concurrency-safe: parallel
+ * invocations each see only their own ID; code outside any
+ * `runWithCorrelationId` scope sees no ID (`getCorrelationId()` returns
+ * `undefined`).
+ *
+ * Callers should mint-if-absent (`getCorrelationId() ?? randomUUID()`)
+ * before calling this, so a wrapped call nested inside another wrapped
+ * call's continuation inherits the outer ID instead of fragmenting one
+ * logical request's trace across multiple IDs.
+ */
+export function runWithCorrelationId(id, fn) {
+    return correlationIdStorage.run(id, fn);
+}
+/**
+ * Read the correlation ID installed for the current async continuation, or
+ * `undefined` if called outside any `runWithCorrelationId` scope (e.g.
+ * fire-and-forget work started before any tool call establishes a scope).
+ *
+ * Must be read synchronously at the log/emit call site — never deferred to
+ * an async flush/rotation callback, which could fire outside the
+ * originating call's scope (F3).
+ */
+export function getCorrelationId() {
+    return correlationIdStorage.getStore();
+}
+//# sourceMappingURL=context.js.map

package/dist/src/logging/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/logging/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAEpD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,iBAAiB,EAAU,CAAA;AAEnE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAAI,EAAU,EAAE,EAAoB;IACtE,OAAO,oBAAoB,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAA;AACzC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,oBAAoB,CAAC,QAAQ,EAAE,CAAA;AACxC,CAAC"}

package/dist/src/logging/context.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * SMI-5615: Unit tests for `correlationIdStorage` / `runWithCorrelationId` /
+ * `getCorrelationId`. Mirrors the pattern of the `markerStorage` coverage in
+ * `packages/core/src/telemetry/wrap.marker.test.ts` — a module-scoped
+ * `AsyncLocalStorage` instance, installed per-call via a `runWith*` function,
+ * read live via `.getStore()`.
+ *
+ * These are direct, in-isolation tests of the primitive itself; the
+ * `withTelemetry` install-site contract (mint-if-absent, whole-`wrappedFn`-
+ * body scope) is covered separately in
+ * `packages/core/src/telemetry/wrap.correlation.test.ts`.
+ */
+export {};
+//# sourceMappingURL=context.test.d.ts.map

package/dist/src/logging/context.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.test.d.ts","sourceRoot":"","sources":["../../../src/logging/context.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/src/logging/context.test.js

@@ -0,0 +1,88 @@
+/**
+ * SMI-5615: Unit tests for `correlationIdStorage` / `runWithCorrelationId` /
+ * `getCorrelationId`. Mirrors the pattern of the `markerStorage` coverage in
+ * `packages/core/src/telemetry/wrap.marker.test.ts` — a module-scoped
+ * `AsyncLocalStorage` instance, installed per-call via a `runWith*` function,
+ * read live via `.getStore()`.
+ *
+ * These are direct, in-isolation tests of the primitive itself; the
+ * `withTelemetry` install-site contract (mint-if-absent, whole-`wrappedFn`-
+ * body scope) is covered separately in
+ * `packages/core/src/telemetry/wrap.correlation.test.ts`.
+ */
+import { describe, it, expect } from 'vitest';
+import { correlationIdStorage, runWithCorrelationId, getCorrelationId } from './context.js';
+describe('getCorrelationId', () => {
+    it('returns undefined outside any runWithCorrelationId scope', () => {
+        expect(getCorrelationId()).toBeUndefined();
+    });
+});
+describe('runWithCorrelationId', () => {
+    it('installs the ID for the duration of the callback', async () => {
+        let observed;
+        await runWithCorrelationId('id-1', async () => {
+            observed = getCorrelationId();
+        });
+        expect(observed).toBe('id-1');
+    });
+    it('auto-unwinds after the callback resolves', async () => {
+        await runWithCorrelationId('id-2', async () => {
+            // no-op
+        });
+        expect(getCorrelationId()).toBeUndefined();
+    });
+    it('auto-unwinds after the callback rejects', async () => {
+        await expect(runWithCorrelationId('id-3', async () => {
+            throw new Error('boom');
+        })).rejects.toThrow('boom');
+        expect(getCorrelationId()).toBeUndefined();
+    });
+    it('returns the callback resolved value', async () => {
+        const result = await runWithCorrelationId('id-4', async () => 42);
+        expect(result).toBe(42);
+    });
+    it('nested scopes — inner ID shadows the outer ID inside its own callback', async () => {
+        const seen = [];
+        await runWithCorrelationId('outer', async () => {
+            seen.push(getCorrelationId());
+            await runWithCorrelationId('inner', async () => {
+                seen.push(getCorrelationId()); // 'inner' — shadows the outer ID
+            });
+            // Outer scope resumes after the inner one unwinds — back to 'outer'.
+            seen.push(getCorrelationId());
+        });
+        expect(seen).toEqual(['outer', 'inner', 'outer']);
+    });
+    it('concurrent, overlapping scopes each observe only their own ID (P-5 invariant)', async () => {
+        let releaseA;
+        let releaseB;
+        const blockA = new Promise((r) => (releaseA = r));
+        const blockB = new Promise((r) => (releaseB = r));
+        const observedA = [];
+        const observedB = [];
+        const callA = runWithCorrelationId('id-a', async () => {
+            observedA.push(getCorrelationId());
+            await blockA;
+            observedA.push(getCorrelationId());
+        });
+        const callB = runWithCorrelationId('id-b', async () => {
+            observedB.push(getCorrelationId());
+            await blockB;
+            observedB.push(getCorrelationId());
+        });
+        // A completes first while B is still awaiting; B must never observe A's ID.
+        releaseA();
+        await callA;
+        releaseB();
+        await callB;
+        expect(observedA).toEqual(['id-a', 'id-a']);
+        expect(observedB).toEqual(['id-b', 'id-b']);
+    });
+    it('the exported correlationIdStorage is the same instance read.write path', async () => {
+        // Sanity: getCorrelationId is a thin wrapper over correlationIdStorage.getStore().
+        await correlationIdStorage.run('direct-id', async () => {
+            expect(getCorrelationId()).toBe('direct-id');
+        });
+    });
+});
+//# sourceMappingURL=context.test.js.map

package/dist/src/logging/context.test.js.map

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

package/dist/src/logging/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SMI-5615: Logging Module Exports
+ *
+ * Shared structured JSON-line error logging (`~/.skillsmith/logs/`) with
+ * SMI-883 redaction, per-surface write serialization, and correlation-ID
+ * threading with `@skillsmith/core/telemetry`'s `withTelemetry`. Consumed by
+ * the MCP server and CLI via the `"./logging"` package export.
+ */
+export { createLogger, getLogger, type CreateLoggerOptions, type Logger } from './logger.js';
+export { runWithCorrelationId, getCorrelationId } from './context.js';
+export { redactSensitiveData, redactSensitiveObject } from './redact.js';
+export type { LogLevel, Surface, LogRecord, LogRecordError, LogDetails } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/logging/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/logging/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,KAAK,mBAAmB,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAA;AAE5F,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAErE,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAExE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA"}

package/dist/src/logging/index.js

@@ -0,0 +1,12 @@
+/**
+ * SMI-5615: Logging Module Exports
+ *
+ * Shared structured JSON-line error logging (`~/.skillsmith/logs/`) with
+ * SMI-883 redaction, per-surface write serialization, and correlation-ID
+ * threading with `@skillsmith/core/telemetry`'s `withTelemetry`. Consumed by
+ * the MCP server and CLI via the `"./logging"` package export.
+ */
+export { createLogger, getLogger } from './logger.js';
+export { runWithCorrelationId, getCorrelationId } from './context.js';
+export { redactSensitiveData, redactSensitiveObject } from './redact.js';
+//# sourceMappingURL=index.js.map

package/dist/src/logging/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/logging/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,SAAS,EAAyC,MAAM,aAAa,CAAA;AAE5F,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAErE,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA"}

package/dist/src/logging/logger.d.ts

@@ -0,0 +1,71 @@
+/**
+ * SMI-5615: Shared structured JSON-line logger.
+ *
+ * Generalized from the dead `packages/mcp-server/src/logger.ts` (SMI-883
+ * redaction) into a surface-agnostic module usable by the MCP server, CLI,
+ * and VS Code extension independently — `createLogger(surface)` is a
+ * factory, not a singleton, so each host process can mint its own logger
+ * (optionally stamped with its own package version) while still writing to
+ * per-surface files that are safe to share across processes for the same
+ * surface (see `rotation.ts`).
+ *
+ * Call-site invariants (see
+ * docs/internal/implementation/production-error-logging.md §1 and the
+ * Shared-State / Coordination Audit table, F2/F3):
+ *
+ *   - `getCorrelationId()` is read SYNCHRONOUSLY at the call site, inside
+ *     `buildRecord`, never inside an async flush/rotation callback (F3) — a
+ *     deferred read could observe a different call's (or no) correlation ID
+ *     once the originating call's `AsyncLocalStorage` scope has unwound.
+ *   - The full JSON-line record (including the synchronously-read
+ *     correlation ID and synchronously-applied redaction) is built and
+ *     `JSON.stringify`'d BEFORE handing the string off to `rotation.ts`'s
+ *     serialized per-surface writer (F2) — only the actual disk write may
+ *     complete asynchronously; by the time it starts, the record content is
+ *     already frozen.
+ *   - Logger calls never throw. Any failure while assembling or persisting a
+ *     record falls back to `console.error`/`console.warn` (matching level,
+ *     with `info`/`debug` also routed to `console.error`) rather than being
+ *     fully silent — stderr remains the safety net of last resort. This
+ *     differs from the old logger's "silently fail" comment intent, which is
+ *     no longer acceptable once this is the only durable failure signal.
+ *   - `warn`/`error` ALWAYS mirror to `console.warn`/`console.error`,
+ *     synchronously, regardless of whether the disk write succeeds — this is
+ *     NOT a failure-only fallback for those two levels (only `info`/`debug`
+ *     use console purely as a write-failure fallback). This is what makes
+ *     `logger.error`/`logger.warn` a safe drop-in replacement for existing
+ *     `console.error`/`console.warn` call sites in the MCP server and CLI —
+ *     the caller-visible terminal/stderr output stays identical to today,
+ *     with redacted disk persistence added on top rather than instead of it.
+ */
+import type { LogDetails, Surface } from './types.js';
+export interface CreateLoggerOptions {
+    /**
+     * Package/CLI version stamped on every record from this logger instance.
+     * Defaults to `'unknown'` — pass each host package's own `version` (e.g.
+     * from its own `package.json`) at its entrypoint for an accurate value.
+     */
+    version?: string;
+}
+export interface Logger {
+    info(message: string, details?: LogDetails): void;
+    warn(message: string, details?: LogDetails): void;
+    error(message: string, details?: LogDetails): void;
+    debug(message: string, details?: LogDetails): void;
+}
+/**
+ * Creates a logger bound to `surface`. Independent instances for different
+ * surfaces (or the same surface with different `version` stamps) are safe to
+ * create concurrently — they only share state at the `rotation.ts` layer,
+ * which is itself safe for concurrent writers to the same surface (F2).
+ */
+export declare function createLogger(surface: Surface, options?: CreateLoggerOptions): Logger;
+/**
+ * Memoized per-surface logger created with default options
+ * (`version: 'unknown'`). Prefer calling `createLogger(surface, { version })`
+ * once at each package's entrypoint so records carry that package's real
+ * version; `getLogger` is a convenience for call sites that don't need a
+ * custom version stamp and want a single shared instance per surface.
+ */
+export declare function getLogger(surface: Surface): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/src/logging/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/logging/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAuB,OAAO,EAAE,MAAM,YAAY,CAAA;AA2L1E,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IACjD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IACjD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;IAClD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAA;CACnD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CA0BxF;AAID;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAOlD"}