@a5c-ai/hooks-mux-core 5.0.1-staging.05a8c224

package/README.md

@@ -0,0 +1,37 @@
+# @a5c-ai/hooks-mux-core
+
+Canonical schemas, types, session store, merge engine, and programmatic runtime for hooks-mux.
+
+## Install
+
+```bash
+npm install @a5c-ai/hooks-mux-core
+```
+
+This package ships the built runtime in `dist/` and this package README for npm publish-surface auditing.
+
+## Usage
+
+```ts
+import {
+  createHooksEngine,
+  createAdapter,
+  registerHandler,
+  runNormalized,
+  type UnifiedHookEvent,
+  type UnifiedHookResult,
+} from "@a5c-ai/hooks-mux-core";
+```
+
+The public surface includes:
+
+- canonical event, result, adapter, plan, and session types
+- normalization, merge, propagation, and diagnostics helpers
+- session-store utilities and harness discovery
+- the programmatic hooks engine for in-process integrations
+
+See the workspace overview in [`packages/hooks-mux/README.md`](../README.md) and the adapter guide in `packages/hooks-mux/docs/`.
+
+## License
+
+MIT © a5c-ai

package/dist/api.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Programmatic integration API.
+ *
+ * Spec section 19.2.
+ */
+import type { UnifiedHookEvent } from './types/event';
+import type { AdapterCapabilities } from './types/adapter';
+import type { HookPlanEntry } from './types/plan';
+import { type MergedExecutionResult } from './merge-engine';
+/**
+ * Implementation callbacks provided by an adapter.
+ */
+export interface AdapterImpl {
+    /** Normalize raw input into a UnifiedHookEvent. */
+    normalize(rawInput: unknown): UnifiedHookEvent;
+    /** Render a merged result into harness-native output. */
+    renderOutput?(mergedResult: MergedExecutionResult): unknown;
+}
+/**
+ * A registered adapter with capabilities and implementation.
+ */
+export interface RegisteredAdapter {
+    name: string;
+    capabilities: AdapterCapabilities;
+    impl: AdapterImpl;
+}
+/**
+ * Register a new adapter with its capabilities and implementation.
+ */
+export declare function createAdapter(name: string, capabilities: AdapterCapabilities, impl: AdapterImpl): RegisteredAdapter;
+/**
+ * Register a handler in the global plan.
+ */
+export declare function registerHandler(planEntry: HookPlanEntry): void;
+/**
+ * Run the full normalized pipeline: execute all matching handlers for
+ * the event's phase and return the merged result.
+ */
+export declare function runNormalized(event: UnifiedHookEvent): Promise<MergedExecutionResult>;
+/**
+ * Get a registered adapter by name.
+ */
+export declare function getAdapter(name: string): RegisteredAdapter | undefined;
+/**
+ * Clear all registrations (useful for testing).
+ */
+export declare function clearRegistries(): void;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAgB,KAAK,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAE1E;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,mDAAmD;IACnD,SAAS,CAAC,QAAQ,EAAE,OAAO,GAAG,gBAAgB,CAAC;IAC/C,yDAAyD;IACzD,YAAY,CAAC,CAAC,YAAY,EAAE,qBAAqB,GAAG,OAAO,CAAC;CAC7D;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,mBAAmB,CAAC;IAClC,IAAI,EAAE,WAAW,CAAC;CACnB;AAaD;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,mBAAmB,EACjC,IAAI,EAAE,WAAW,GAChB,iBAAiB,CAInB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,aAAa,GAAG,IAAI,CAE9D;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,qBAAqB,CAAC,CAyBhC;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAEtE;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAGtC"}

package/dist/api.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Programmatic integration API.
+ *
+ * Spec section 19.2.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAdapter = createAdapter;
+exports.registerHandler = registerHandler;
+exports.runNormalized = runNormalized;
+exports.getAdapter = getAdapter;
+exports.clearRegistries = clearRegistries;
+const merge_engine_1 = require("./merge-engine");
+// ---------------------------------------------------------------------------
+// Internal registries
+// ---------------------------------------------------------------------------
+const adapterRegistry = new Map();
+const handlerRegistry = [];
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Register a new adapter with its capabilities and implementation.
+ */
+function createAdapter(name, capabilities, impl) {
+    const adapter = { name, capabilities, impl };
+    adapterRegistry.set(name, adapter);
+    return adapter;
+}
+/**
+ * Register a handler in the global plan.
+ */
+function registerHandler(planEntry) {
+    handlerRegistry.push(planEntry);
+}
+/**
+ * Run the full normalized pipeline: execute all matching handlers for
+ * the event's phase and return the merged result.
+ */
+async function runNormalized(event) {
+    const matchingEntries = handlerRegistry
+        .filter((e) => e.phase === event.phase)
+        .sort((a, b) => {
+        if (a.priority !== b.priority)
+            return a.priority - b.priority;
+        const sp = a.pluginId.localeCompare(b.pluginId);
+        if (sp !== 0)
+            return sp;
+        return a.id.localeCompare(b.id);
+    });
+    const results = [];
+    for (const entry of matchingEntries) {
+        // Handler.source is the shell command to execute as a child process.
+        const { runHandler } = await Promise.resolve().then(() => __importStar(require('./normalizer/runner')));
+        try {
+            const result = await runHandler(event, entry.handler);
+            results.push(result);
+        }
+        catch (_err) {
+            // Fail-open by default in programmatic API
+            results.push({ decision: 'noop', reason: 'handler error (fail-open)' });
+        }
+    }
+    return (0, merge_engine_1.mergeResults)(results);
+}
+/**
+ * Get a registered adapter by name.
+ */
+function getAdapter(name) {
+    return adapterRegistry.get(name);
+}
+/**
+ * Clear all registrations (useful for testing).
+ */
+function clearRegistries() {
+    adapterRegistry.clear();
+    handlerRegistry.length = 0;
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCH,sCAQC;AAKD,0CAEC;AAMD,sCA2BC;AAKD,gCAEC;AAKD,0CAGC;AAlGD,iDAA0E;AAqB1E,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E,MAAM,eAAe,GAAG,IAAI,GAAG,EAA6B,CAAC;AAC7D,MAAM,eAAe,GAAoB,EAAE,CAAC;AAE5C,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;GAEG;AACH,SAAgB,aAAa,CAC3B,IAAY,EACZ,YAAiC,EACjC,IAAiB;IAEjB,MAAM,OAAO,GAAsB,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;IAChE,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe,CAAC,SAAwB;IACtD,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,aAAa,CACjC,KAAuB;IAEvB,MAAM,eAAe,GAAG,eAAe;SACpC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK,CAAC;SACtC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACb,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ;YAAE,OAAO,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;QAC9D,MAAM,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;QAChD,IAAI,EAAE,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACxB,OAAO,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEL,MAAM,OAAO,GAAwB,EAAE,CAAC;IAExC,KAAK,MAAM,KAAK,IAAI,eAAe,EAAE,CAAC;QACpC,qEAAqE;QACrE,MAAM,EAAE,UAAU,EAAE,GAAG,wDAAa,qBAAqB,GAAC,CAAC;QAC3D,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;YACtD,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC;QAAC,OAAO,IAAI,EAAE,CAAC;YACd,2CAA2C;YAC3C,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,2BAA2B,EAAE,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;IAED,OAAO,IAAA,2BAAY,EAAC,OAAO,CAAC,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,SAAgB,UAAU,CAAC,IAAY;IACrC,OAAO,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe;IAC7B,eAAe,CAAC,KAAK,EAAE,CAAC;IACxB,eAAe,CAAC,MAAM,GAAG,CAAC,CAAC;AAC7B,CAAC"}

package/dist/diagnostics/index.d.ts

@@ -0,0 +1,4 @@
+export type { DiagnosticEntry, DiagnosticLoggerOptions, MergeDecisionSummary, SessionIdQuality, TraceWriterOptions, TraceRecord, TraceHandlerRecord, } from './types';
+export { DiagnosticLogger, createDiagnosticLogger } from './logger';
+export { TraceWriter, createTraceWriter, generateTraceId, buildTraceRecord, } from './trace';
+//# sourceMappingURL=index.d.ts.map

package/dist/diagnostics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/diagnostics/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,eAAe,EACf,uBAAuB,EACvB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,kBAAkB,GACnB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAGpE,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,gBAAgB,GACjB,MAAM,SAAS,CAAC"}

package/dist/diagnostics/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTraceRecord = exports.generateTraceId = exports.createTraceWriter = exports.TraceWriter = exports.createDiagnosticLogger = exports.DiagnosticLogger = void 0;
+// Logger
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "DiagnosticLogger", { enumerable: true, get: function () { return logger_1.DiagnosticLogger; } });
+Object.defineProperty(exports, "createDiagnosticLogger", { enumerable: true, get: function () { return logger_1.createDiagnosticLogger; } });
+// Trace
+var trace_1 = require("./trace");
+Object.defineProperty(exports, "TraceWriter", { enumerable: true, get: function () { return trace_1.TraceWriter; } });
+Object.defineProperty(exports, "createTraceWriter", { enumerable: true, get: function () { return trace_1.createTraceWriter; } });
+Object.defineProperty(exports, "generateTraceId", { enumerable: true, get: function () { return trace_1.generateTraceId; } });
+Object.defineProperty(exports, "buildTraceRecord", { enumerable: true, get: function () { return trace_1.buildTraceRecord; } });
+//# sourceMappingURL=index.js.map

package/dist/diagnostics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/diagnostics/index.ts"],"names":[],"mappings":";;;AAWA,SAAS;AACT,mCAAoE;AAA3D,0GAAA,gBAAgB,OAAA;AAAE,gHAAA,sBAAsB,OAAA;AAEjD,QAAQ;AACR,iCAKiB;AAJf,oGAAA,WAAW,OAAA;AACX,0GAAA,iBAAiB,OAAA;AACjB,wGAAA,eAAe,OAAA;AACf,yGAAA,gBAAgB,OAAA"}

package/dist/diagnostics/logger.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Structured diagnostic logger for hooks-mux execution.
+ *
+ * Outputs to stderr with structured fields per spec section 23:
+ * adapter, canonical phase, native event name, session ID quality,
+ * handler IDs executed, merge decisions, output degradation flags.
+ */
+import type { DiagnosticEntry, DiagnosticLoggerOptions, MergeDecisionSummary, SessionIdQuality } from './types';
+declare const LOG_LEVELS: {
+    readonly debug: 0;
+    readonly info: 1;
+    readonly warn: 2;
+    readonly error: 3;
+};
+type LogLevel = keyof typeof LOG_LEVELS;
+/**
+ * Structured logger that emits diagnostics to stderr (or a custom stream).
+ *
+ * Separates diagnostic output (stderr) from hook output (stdout) per
+ * the security requirement in spec section 22.
+ */
+export declare class DiagnosticLogger {
+    private readonly minLevel;
+    private readonly output;
+    private readonly json;
+    private adapter;
+    private canonicalPhase;
+    private nativeEventName;
+    private sessionIdQuality;
+    private sessionId;
+    private handlerIds;
+    private mergeDecisions;
+    private outputDegradationFlags;
+    constructor(options?: DiagnosticLoggerOptions);
+    /**
+     * Set the adapter context for subsequent log entries.
+     */
+    setAdapter(adapter: string): void;
+    /**
+     * Set the phase context for subsequent log entries.
+     */
+    setPhase(canonicalPhase: string, nativeEventName: string): void;
+    /**
+     * Set session context for subsequent log entries.
+     */
+    setSession(sessionId: string | undefined, quality: SessionIdQuality): void;
+    /**
+     * Record the handler IDs that were executed.
+     */
+    setHandlerIds(ids: string[]): void;
+    /**
+     * Record merge decisions from the fan-out merge phase.
+     */
+    setMergeDecisions(decisions: MergeDecisionSummary[]): void;
+    /**
+     * Record output degradation flags.
+     */
+    setOutputDegradationFlags(flags: string[]): void;
+    /**
+     * Emit a debug-level diagnostic.
+     */
+    debug(message: string, extra?: Record<string, unknown>): void;
+    /**
+     * Emit an info-level diagnostic.
+     */
+    info(message: string, extra?: Record<string, unknown>): void;
+    /**
+     * Emit a warn-level diagnostic.
+     */
+    warn(message: string, extra?: Record<string, unknown>): void;
+    /**
+     * Emit an error-level diagnostic.
+     */
+    error(message: string, extra?: Record<string, unknown>): void;
+    /**
+     * Build and return a DiagnosticEntry without emitting it.
+     * Useful for testing or collecting entries.
+     */
+    buildEntry(level: LogLevel, message: string, extra?: Record<string, unknown>): DiagnosticEntry;
+    private emit;
+    private formatHuman;
+}
+/**
+ * Create a DiagnosticLogger with default settings.
+ * Intended for use by the invoke pipeline.
+ */
+export declare function createDiagnosticLogger(options?: DiagnosticLoggerOptions): DiagnosticLogger;
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/dist/diagnostics/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/diagnostics/logger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,uBAAuB,EACvB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAEjB,QAAA,MAAM,UAAU;;;;;CAAoD,CAAC;AACrE,KAAK,QAAQ,GAAG,MAAM,OAAO,UAAU,CAAC;AAExC;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAC/C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAU;IAG/B,OAAO,CAAC,OAAO,CAAM;IACrB,OAAO,CAAC,cAAc,CAAM;IAC5B,OAAO,CAAC,eAAe,CAAM;IAC7B,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,cAAc,CAA8B;IACpD,OAAO,CAAC,sBAAsB,CAAgB;gBAElC,OAAO,CAAC,EAAE,uBAAuB;IAM7C;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIjC;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI;IAK/D;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAK1E;;OAEG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI;IAIlC;;OAEG;IACH,iBAAiB,CAAC,SAAS,EAAE,oBAAoB,EAAE,GAAG,IAAI;IAI1D;;OAEG;IACH,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAIhD;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI7D;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI7D;;;OAGG;IACH,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe;IAiB9F,OAAO,CAAC,IAAI;IAYZ,OAAO,CAAC,WAAW;CAoBpB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,gBAAgB,CAE1F"}

package/dist/diagnostics/logger.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * Structured diagnostic logger for hooks-mux execution.
+ *
+ * Outputs to stderr with structured fields per spec section 23:
+ * adapter, canonical phase, native event name, session ID quality,
+ * handler IDs executed, merge decisions, output degradation flags.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiagnosticLogger = void 0;
+exports.createDiagnosticLogger = createDiagnosticLogger;
+const LOG_LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };
+/**
+ * Structured logger that emits diagnostics to stderr (or a custom stream).
+ *
+ * Separates diagnostic output (stderr) from hook output (stdout) per
+ * the security requirement in spec section 22.
+ */
+class DiagnosticLogger {
+    minLevel;
+    output;
+    json;
+    // Contextual fields set once and reused across log calls within one invocation.
+    adapter = '';
+    canonicalPhase = '';
+    nativeEventName = '';
+    sessionIdQuality = 'none';
+    sessionId;
+    handlerIds = [];
+    mergeDecisions = [];
+    outputDegradationFlags = [];
+    constructor(options) {
+        this.minLevel = LOG_LEVELS[options?.level ?? 'info'];
+        this.output = options?.output ?? process.stderr;
+        this.json = options?.json ?? true;
+    }
+    /**
+     * Set the adapter context for subsequent log entries.
+     */
+    setAdapter(adapter) {
+        this.adapter = adapter;
+    }
+    /**
+     * Set the phase context for subsequent log entries.
+     */
+    setPhase(canonicalPhase, nativeEventName) {
+        this.canonicalPhase = canonicalPhase;
+        this.nativeEventName = nativeEventName;
+    }
+    /**
+     * Set session context for subsequent log entries.
+     */
+    setSession(sessionId, quality) {
+        this.sessionId = sessionId;
+        this.sessionIdQuality = quality;
+    }
+    /**
+     * Record the handler IDs that were executed.
+     */
+    setHandlerIds(ids) {
+        this.handlerIds = ids;
+    }
+    /**
+     * Record merge decisions from the fan-out merge phase.
+     */
+    setMergeDecisions(decisions) {
+        this.mergeDecisions = decisions;
+    }
+    /**
+     * Record output degradation flags.
+     */
+    setOutputDegradationFlags(flags) {
+        this.outputDegradationFlags = flags;
+    }
+    /**
+     * Emit a debug-level diagnostic.
+     */
+    debug(message, extra) {
+        this.emit('debug', message, extra);
+    }
+    /**
+     * Emit an info-level diagnostic.
+     */
+    info(message, extra) {
+        this.emit('info', message, extra);
+    }
+    /**
+     * Emit a warn-level diagnostic.
+     */
+    warn(message, extra) {
+        this.emit('warn', message, extra);
+    }
+    /**
+     * Emit an error-level diagnostic.
+     */
+    error(message, extra) {
+        this.emit('error', message, extra);
+    }
+    /**
+     * Build and return a DiagnosticEntry without emitting it.
+     * Useful for testing or collecting entries.
+     */
+    buildEntry(level, message, extra) {
+        return {
+            timestamp: new Date().toISOString(),
+            level,
+            message,
+            adapter: this.adapter,
+            canonicalPhase: this.canonicalPhase,
+            nativeEventName: this.nativeEventName,
+            sessionIdQuality: this.sessionIdQuality,
+            sessionId: this.sessionId,
+            handlerIds: [...this.handlerIds],
+            mergeDecisions: [...this.mergeDecisions],
+            outputDegradationFlags: [...this.outputDegradationFlags],
+            extra,
+        };
+    }
+    emit(level, message, extra) {
+        if (LOG_LEVELS[level] < this.minLevel)
+            return;
+        const entry = this.buildEntry(level, message, extra);
+        if (this.json) {
+            this.output.write(JSON.stringify(entry) + '\n');
+        }
+        else {
+            this.output.write(this.formatHuman(entry) + '\n');
+        }
+    }
+    formatHuman(entry) {
+        const parts = [
+            `[${entry.level.toUpperCase()}]`,
+            `[${entry.adapter || '-'}]`,
+            `[${entry.canonicalPhase || '-'}]`,
+            entry.message,
+        ];
+        if (entry.sessionId) {
+            parts.push(`session=${entry.sessionId}`);
+        }
+        if (entry.handlerIds.length > 0) {
+            parts.push(`handlers=[${entry.handlerIds.join(',')}]`);
+        }
+        if (entry.outputDegradationFlags.length > 0) {
+            parts.push(`degraded=[${entry.outputDegradationFlags.join(',')}]`);
+        }
+        return parts.join(' ');
+    }
+}
+exports.DiagnosticLogger = DiagnosticLogger;
+/**
+ * Create a DiagnosticLogger with default settings.
+ * Intended for use by the invoke pipeline.
+ */
+function createDiagnosticLogger(options) {
+    return new DiagnosticLogger(options);
+}
+//# sourceMappingURL=logger.js.map

package/dist/diagnostics/logger.js.map

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

package/dist/diagnostics/trace.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Optional JSONL trace file support for debugging.
+ *
+ * Spec section 23 (optional future support: JSONL trace files).
+ *
+ * When enabled, writes one JSON line per hook invocation to a trace file.
+ * Useful for post-hoc debugging of hook execution sequences.
+ */
+import type { TraceRecord, TraceWriterOptions, TraceHandlerRecord, SessionIdQuality } from './types';
+/**
+ * Writer that appends JSONL trace records to a file.
+ */
+export declare class TraceWriter {
+    private readonly filePath;
+    private readonly append;
+    private initialized;
+    constructor(options: TraceWriterOptions);
+    /**
+     * Ensure the trace directory exists and the file is ready for writing.
+     */
+    private ensureInitialized;
+    /**
+     * Write a trace record as a single JSONL line.
+     */
+    writeRecord(record: TraceRecord): Promise<void>;
+    /**
+     * Get the trace file path.
+     */
+    getFilePath(): string;
+}
+/**
+ * Create a trace writer. Returns null if no trace file path is configured.
+ */
+export declare function createTraceWriter(options?: TraceWriterOptions | null): TraceWriter | null;
+/**
+ * Generate a simple trace ID for this invocation.
+ */
+export declare function generateTraceId(): string;
+/**
+ * Build a complete TraceRecord from invocation data.
+ */
+export declare function buildTraceRecord(params: {
+    traceId: string;
+    startedAt: string;
+    completedAt: string;
+    adapter: string;
+    phase: string;
+    nativeEventName: string;
+    sessionIdQuality: SessionIdQuality;
+    sessionId?: string;
+    handlers: TraceHandlerRecord[];
+    mergedDecision: string;
+    degraded: boolean;
+    errors: string[];
+}): TraceRecord;
+//# sourceMappingURL=trace.d.ts.map

package/dist/diagnostics/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/diagnostics/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAErG;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,WAAW,CAAS;gBAEhB,OAAO,EAAE,kBAAkB;IAKvC;;OAEG;YACW,iBAAiB;IAU/B;;OAEG;IACG,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAMrD;;OAEG;IACH,WAAW,IAAI,MAAM;CAGtB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,IAAI,GAAG,WAAW,GAAG,IAAI,CAGzF;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAIxC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,WAAW,CAoBd"}