@meetless/mla 0.1.4

package/dist/commands/internal-evidence-hooks.js

@@ -0,0 +1,240 @@
+"use strict";
+// The CE0 hook subcommands: the live wiring between Claude Code's UserPromptSubmit,
+// PostToolUse, and Stop hooks and the CE0 durable store
+// (notes/20260617-evidence-consultation-forcing-function-proposal.md §4.1, the one
+// remaining durable-layer piece). The managed ce0-*.sh hooks pipe their raw hook stdin
+// into one of these subcommands; each is a thin IO shell over a committed adapter.
+//
+// Every subcommand obeys the same RECORD_ONLY discipline as the adapters it wraps:
+//   - It ALWAYS writes the empty `{}` body to stdout and exits 0. It can never inject an
+//     additionalContext, never deny, never block a turn. Injection is a CE2 concern that
+//     demands a new immutable rule version; CE0 is a measurement harness.
+//   - It is dormant when no workspace resolves (a repo CE0 is not bound to): it opens no
+//     store and writes nothing, it just emits the pass-through body. The workspace
+//     resolution IS the activation gate; the scripts carry no activation check.
+//   - It fails soft on every error. Malformed stdin, a missing store directory, a
+//     persistence fault: all are swallowed, leaving the clean `{}` exit-0 pass-through.
+//     A CE0 bookkeeping failure must never disturb the turn it observed.
+//
+// The subcommands take no argv flags (the hook pipes everything on stdin), mirroring
+// `_internal pretool-observe`.
+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.runInternalEvidenceTurnOpen = runInternalEvidenceTurnOpen;
+exports.runInternalEvidenceCapture = runInternalEvidenceCapture;
+exports.runInternalEvidenceStop = runInternalEvidenceStop;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const perf_hooks_1 = require("perf_hooks");
+const evidence_1 = require("./evidence");
+const workspace_1 = require("../lib/workspace");
+const ce0_store_1 = require("../lib/rules/ce0-store");
+const prompt_submit_adapter_1 = require("../lib/rules/prompt-submit-adapter");
+const consultation_capture_adapter_1 = require("../lib/rules/consultation-capture-adapter");
+const stop_adapter_1 = require("../lib/rules/stop-adapter");
+const runtime_scope_1 = require("../lib/rules/runtime-scope");
+const consult_evidence_binding_1 = require("../lib/rules/consult-evidence-binding");
+const ce0_telemetry_1 = require("../lib/rules/ce0-telemetry");
+const ce0_emit_1 = require("../lib/rules/ce0-emit");
+/** The single response a CE0 hook is ever allowed to emit: the empty no-decision body. */
+const CE0_HOOK_PASS_THROUGH = "{}";
+function readStdinReal() {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        process.stdin.on("data", (c) => chunks.push(c));
+        process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        process.stdin.on("error", reject);
+    });
+}
+/** Best-effort pull of the hook payload's session_id; null when stdin is absent or malformed. The
+ * STOP operationIdentity and the telemetry envelope both join on it, so it is parsed once in the shell. */
+function parseSessionId(raw) {
+    try {
+        const p = JSON.parse(raw);
+        return typeof p.session_id === "string" ? p.session_id : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The shared IO shell for every CE0 hook subcommand. Reads stdin best-effort, resolves the
+ * workspace (the activation gate), opens the store, runs `body`, closes the store, and ALWAYS
+ * writes the empty pass-through body + returns exit 0. Every fault is swallowed so the hook
+ * never blocks a turn. `body` runs one adapter (discarding its injection-free response) and returns
+ * the coordinate it acted on; when a coordinate is present the shell appends the §6.4 evidence_hook_health
+ * watchdog event via the fail-soft live-telemetry sink (durable store write already committed; telemetry
+ * is strictly best-effort on top, P0.2).
+ */
+async function runCe0Hook(io, hook, body) {
+    const monotonicNow = io.monotonicNowMs ?? (() => perf_hooks_1.performance.now());
+    const enteredAtMs = monotonicNow();
+    const writeOut = io.writeOut ?? ((s) => process.stdout.write(s));
+    let raw = "";
+    try {
+        raw = await (io.readStdin ?? readStdinReal)();
+    }
+    catch {
+        raw = "";
+    }
+    const sessionId = parseSessionId(raw);
+    try {
+        const workspaceId = (io.resolveWorkspaceId ?? workspace_1.resolveWorkspaceIdWithEnv)();
+        if (workspaceId) {
+            const dbPath = io.storePath ?? (0, evidence_1.defaultCe0StorePath)();
+            fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+            const store = (io.openStore ?? ce0_store_1.openCe0Store)(dbPath);
+            let result;
+            try {
+                result = body(store, workspaceId, raw, sessionId);
+            }
+            finally {
+                (0, ce0_store_1.closeCe0Store)(store);
+            }
+            const emit = io.emit ?? ce0_emit_1.emitCe0Event;
+            const now = io.now ?? Date.now;
+            const coords = { workspaceId, sessionId, nowMs: now() };
+            // The primary event (the fact the hook produced) ships first; the health watchdog's monotonic
+            // durationMs is sampled after, so it covers the primary append (§6.4 P0.2).
+            if (result.primaryEvent) {
+                emit(result.primaryEvent, coords);
+            }
+            if (result.operationIdentity) {
+                const durationMs = Math.round(monotonicNow() - enteredAtMs);
+                const event = (0, ce0_telemetry_1.buildEvidenceHookHealthEvent)({
+                    hook,
+                    operationIdentity: result.operationIdentity,
+                    durationMs,
+                    failed: false,
+                    reason: null,
+                });
+                emit(event, coords);
+            }
+        }
+    }
+    catch {
+        // Fail-soft: a CE0 record (or telemetry) failure must never escalate into a blocking hook.
+    }
+    writeOut(CE0_HOOK_PASS_THROUGH);
+    return 0;
+}
+/**
+ * `mla _internal evidence-turn-open` -- the UserPromptSubmit hook entry. Classifies the
+ * turn's memory requirement, persists its assessment, and (only for a REQUIRED turn) creates
+ * the turn's TurnRuleObligation. Always emits `{}` exit 0.
+ */
+async function runInternalEvidenceTurnOpen(_argv, deps = {}) {
+    return runCe0Hook(deps, "USER_PROMPT_SUBMIT", (store, workspaceId, raw) => {
+        // Resolve the obligation's rule identity from the active runtime scope (P0.51): the LIVE attested
+        // consult-evidence version when an operator has armed this checkout, the frozen compile-time identity
+        // otherwise. The obligation is stamped with whichever this returns, so arming binds with no behavior
+        // change (the rule stays RECORD_ONLY -- arming only gives the obligation a durable version to claim).
+        const runtimeScopeId = (deps.resolveRuntimeScopeId ?? runtime_scope_1.resolveActiveRuntimeScopeId)();
+        const ruleBinding = (0, consult_evidence_binding_1.resolveConsultEvidenceRuleBinding)(store, runtimeScopeId);
+        const { outcome } = (0, prompt_submit_adapter_1.observeUserPromptSubmit)(raw, {
+            store,
+            workspaceId,
+            ruleBinding,
+            now: deps.now,
+            newId: deps.newId,
+        });
+        // §6.4: the UserPromptSubmit health event's operation identity is the assessmentId of the turn it
+        // opened. An INFRA outcome opened no turn and has no assessmentId, so it emits no health event.
+        return { operationIdentity: outcome.kind === "ASSESSED" ? outcome.assessmentId : undefined };
+    });
+}
+/**
+ * `mla _internal evidence-capture` -- the PostToolUse hook entry. When the agent calls a
+ * governed-memory pull, records the FACT of that consultation as a ConsultationAttempt under
+ * the live turn's identity; a non-governed tool is a no-op. Always emits `{}` exit 0.
+ */
+async function runInternalEvidenceCapture(_argv, deps = {}) {
+    return runCe0Hook(deps, "CONSULTATION_CAPTURE", (store, workspaceId, raw) => {
+        const { outcome } = (0, consultation_capture_adapter_1.captureMemoryConsultation)(raw, {
+            store,
+            workspaceId,
+            now: deps.now,
+            newId: deps.newId,
+        });
+        if (outcome.kind !== "CAPTURED") {
+            // A non-governed tool (NOT_APPLICABLE) or an INFRA outcome records no consultation: no primary event
+            // and no operation identity, so the shell emits nothing for this invocation (§6.4 P0.2).
+            return {};
+        }
+        // §6.4: a governed-memory pull emits one evidence_consultation_completed primary event keyed by the
+        // consultationId, plus the health watchdog under the same consultationId. A CE0 capture carries neither
+        // a rule version (the obligation is finalized offline) nor a timed retrieval latency, so both stay
+        // absent (R4 P1.2 / P0.2). delivered_to_answering_context is true: the agent pulled the evidence into
+        // its own answering context, mirroring the persisted ConsultationAttempt row.
+        const primaryEvent = (0, ce0_telemetry_1.buildEvidenceConsultationCompletedEvent)({
+            consultationId: outcome.consultationId,
+            localTurnSequence: outcome.localTurnSequence,
+            source: outcome.source,
+            execution: outcome.execution,
+            result: outcome.result,
+            deliveredToAnsweringContext: true,
+        });
+        return { operationIdentity: outcome.consultationId, primaryEvent };
+    });
+}
+/**
+ * `mla _internal evidence-stop` -- the Stop hook entry. The first Stop of a turn runs §2.3's two
+ * stages: Stage A stamps stopObservedAt and freezes the obligation's eligibility boundary at the
+ * high-water consultation token (I/O-free), then Stage B best-effort snapshots the response from the
+ * payload's transcript_path. A later Stop is an idempotent no-op on both. The boundary is a stored
+ * token and the clock defaults to Date.now inside the adapter, so this entry needs no minter. Always
+ * emits `{}` exit 0.
+ */
+async function runInternalEvidenceStop(_argv, deps = {}) {
+    return runCe0Hook(deps, "STOP", (store, workspaceId, raw, sessionId) => {
+        // Re-resolve the same binding the turn-open adapter stamped the obligation with (P0.51): claimFirstStop
+        // joins the obligation on (ws, session, seq, ruleVersionId), so the Stop MUST claim with the active
+        // runtime scope's bound version (the LIVE attested one when armed, the frozen compile-time identity
+        // when unarmed), or it would orphan the armed obligation and never freeze its boundary. This is the
+        // symmetric Stop half of the binding; the rule stays RECORD_ONLY (the version only gives Stop a durable
+        // identity to claim against).
+        const runtimeScopeId = (deps.resolveRuntimeScopeId ?? runtime_scope_1.resolveActiveRuntimeScopeId)();
+        const ruleBinding = (0, consult_evidence_binding_1.resolveConsultEvidenceRuleBinding)(store, runtimeScopeId);
+        const { outcome } = (0, stop_adapter_1.observeStop)(raw, { store, workspaceId, ruleVersionId: ruleBinding.ruleVersionId });
+        // §6.4: the Stop health event's operation identity is the rendered LocalTurnIdentity of the turn it
+        // claimed (`${workspaceId}:${sessionId}:${localTurnSequence}`). CLAIMED/ALREADY_CLAIMED carry the
+        // localTurnSequence but not the workspace or session, so the shell composes the key from the body's
+        // workspaceId and the parsed sessionId. A NOT_APPLICABLE / INFRA Stop claimed no obligation and a
+        // sessionId-less payload cannot form the key, so either emits no health event.
+        const claimed = outcome.kind === "CLAIMED" || outcome.kind === "ALREADY_CLAIMED";
+        const operationIdentity = claimed && sessionId !== null ? `${workspaceId}:${sessionId}:${outcome.localTurnSequence}` : undefined;
+        return { operationIdentity };
+    });
+}

package/dist/commands/internal-evidence-inject.js

@@ -0,0 +1,231 @@
+"use strict";
+// `mla _internal evidence-inject` -- emit one mla_evidence_inject analytics event.
+//
+// Fired DETACHED from the user-prompt-submit hook (spawn_evidence_inject) on a turn
+// where mla actually injected evidence (INJECTED=true). It builds the typed,
+// PII-bounded inject payload (buildInjectPayload), records it to the local
+// events.jsonl immediately as the start of a pending window (the Stop-hook
+// correlator closes the window later and appends mla_evidence_outcome,
+// INV-CORRELATOR-1), and best-effort forwards to control when telemetry is on.
+//
+// It rides OFF the session's hot path: every failure is swallowed and the command
+// exits 0 (except a strict argv parse error -> 2), so analytics can never disturb
+// the session it spawned from.
+//
+// The spawn is a fresh process with NO run context, so trace_id arrives via
+// --trace-id (the SAME trace as the enrichment that produced the inject, so the
+// inject joins to it in Langfuse) and a fresh run_id is minted for this invocation
+// (INV-RUN-1: one run_id per invocation, never derived from trace_id).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
+exports.runInternalEvidenceInject = runInternalEvidenceInject;
+const config_1 = require("../lib/config");
+const observability_1 = require("../lib/observability");
+const evidence_1 = require("../lib/analytics/evidence");
+const coverage_gap_1 = require("../lib/analytics/coverage-gap");
+const recorder_1 = require("../lib/analytics/recorder");
+const store_1 = require("../lib/analytics/store");
+function parseArgs(argv) {
+    const out = {
+        turnIndex: null,
+        offered: null,
+        offeredIds: [],
+        tokens: 0,
+        confidence: "low",
+        latencyMs: 0,
+        traceId: null,
+        workspaceId: null,
+        sessionId: null,
+        injectId: null,
+        retrievalError: false,
+        permissionFiltered: false,
+        stale: false,
+        topicCategory: null,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const value = () => {
+            const v = argv[++i];
+            if (v === undefined)
+                throw new Error(`Flag ${a} requires a value.`);
+            return v;
+        };
+        switch (a) {
+            case "--turn-index": {
+                const v = Number(value());
+                out.turnIndex = Number.isInteger(v) ? v : null;
+                break;
+            }
+            case "--offered": {
+                const v = Number(value());
+                out.offered = Number.isFinite(v) ? v : null;
+                break;
+            }
+            // Source ids are filename-derived (e.g. NT:20260529-notes.md) and never
+            // contain commas, so a comma-separated list is unambiguous from a bash hook.
+            case "--offered-ids":
+                out.offeredIds = value()
+                    .split(",")
+                    .map((s) => s.trim())
+                    .filter(Boolean);
+                break;
+            case "--tokens": {
+                const v = Number(value());
+                out.tokens = Number.isFinite(v) ? v : 0;
+                break;
+            }
+            case "--latency-ms": {
+                const v = Number(value());
+                out.latencyMs = Number.isFinite(v) ? v : 0;
+                break;
+            }
+            case "--confidence":
+                out.confidence = value();
+                break;
+            case "--trace-id":
+                out.traceId = value();
+                break;
+            case "--workspace-id":
+                out.workspaceId = value();
+                break;
+            case "--session-id":
+                out.sessionId = value();
+                break;
+            case "--inject-id":
+                out.injectId = value();
+                break;
+            // Coverage-gap signal flags. Boolean flags take no value (a retrieval that
+            // errored / was permission-filtered / returned stale candidates); the
+            // topic category is a closed-enum string coerced at emit time.
+            case "--retrieval-error":
+                out.retrievalError = true;
+                break;
+            case "--permission-filtered":
+                out.permissionFiltered = true;
+                break;
+            case "--stale":
+                out.stale = true;
+                break;
+            case "--topic-category":
+                out.topicCategory = value();
+                break;
+            default:
+                throw new Error(`Unknown flag for \`mla _internal evidence-inject\`: ${a}`);
+        }
+    }
+    return out;
+}
+async function runInternalEvidenceInject(argv, deps = {}) {
+    let args;
+    try {
+        args = parseArgs(argv);
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    const env = deps.env ?? process.env;
+    try {
+        const sessionId = args.sessionId ?? ((env.CLAUDE_CODE_SESSION_ID || "").trim() || null);
+        // trace_id is mandatory for a joinable event; the spawn passes it explicitly.
+        // Without one, record nothing (a local line with no trace cannot join the
+        // enrichment) and no-op.
+        const traceId = args.traceId ?? (0, observability_1.getRunTraceId)();
+        if (!traceId) {
+            console.log(JSON.stringify({ recorded: false, reason: "no_trace_id" }));
+            return 0;
+        }
+        const nowMs = deps.nowMs ?? Date.now();
+        const offeredCount = args.offered ?? args.offeredIds.length;
+        const payload = (0, evidence_1.buildInjectPayload)({
+            turn_index: args.turnIndex,
+            evidence_offered: offeredCount,
+            offered_source_ids: args.offeredIds,
+            evidence_tokens: args.tokens,
+            retrieval_confidence: args.confidence,
+            retrieval_latency_ms: args.latencyMs,
+            createdAtMs: nowMs,
+            ...(args.injectId ? { injectId: args.injectId } : {}),
+        });
+        const readCfg = deps.readCfg ??
+            (() => {
+                try {
+                    return (0, config_1.readConfig)();
+                }
+                catch {
+                    return null;
+                }
+            });
+        const cfg = readCfg();
+        const mId = (deps.machineId ?? store_1.machineId)();
+        const runId = (deps.mintRunId ?? observability_1.mintRunId)();
+        const ctx = {
+            workspaceId: args.workspaceId,
+            sessionId,
+            // The hook cannot cheaply resolve the actor cuid; prefer the configured
+            // actor when present, else the hashed machine id (a workspace-scoped
+            // anonymous id, never end-user PII).
+            distinctId: cfg?.actorUserId ?? mId,
+            runId,
+            traceId,
+            source: "hook",
+            now: new Date(nowMs).toISOString(),
+        };
+        const record = deps.record ?? recorder_1.recordAnalyticsEvent;
+        // event_id == inject_id: one inject produces exactly one inject event, so the
+        // business key IS the idempotency key. A re-ship dedupes on
+        // (workspace_id, inject_id) in control (§10.2, INV-REMOTE-DEDUPE-1).
+        record(ctx, {
+            eventType: "mla_evidence_inject",
+            eventId: payload.inject_id,
+            payload: payload,
+        }, env);
+        // Typed coverage gap (spec §7.5, INV-COVERAGE-GAP-1): if this inject failed
+        // to help (errored / permission-filtered / empty / stale / low-confidence),
+        // emit a paired mla_coverage_gap keyed to the same inject_id so `mla stats`
+        // can sort the backlog by cause. A confident, non-empty retrieval classifies
+        // to null and emits nothing. Reuses the inject's already-coerced confidence
+        // and zero_results so the two events never disagree.
+        const coverageGapType = (0, coverage_gap_1.classifyCoverageGap)({
+            retrievalError: args.retrievalError,
+            permissionFiltered: args.permissionFiltered,
+            zeroResults: payload.zero_results,
+            staleOrConflicting: args.stale,
+            retrievalConfidence: payload.retrieval_confidence,
+        });
+        if (coverageGapType) {
+            record(ctx, {
+                eventType: "mla_coverage_gap",
+                eventId: (0, coverage_gap_1.coverageGapEventId)(payload.inject_id),
+                payload: (0, coverage_gap_1.buildCoverageGapPayload)({
+                    injectId: payload.inject_id,
+                    coverageGapType,
+                    queryTopicCategory: (0, coverage_gap_1.coerceTopicCategory)(args.topicCategory),
+                    retrievalConfidence: payload.retrieval_confidence,
+                    zeroResults: payload.zero_results,
+                }),
+            }, env);
+        }
+        // Best-effort, bounded, telemetry-gated forward (the consent gate is inside
+        // the forwarder). Skipped entirely when the run has no control config.
+        if (cfg) {
+            const flush = deps.flush ?? recorder_1.flushAnalyticsEvents;
+            await flush(cfg, env);
+        }
+        console.log(JSON.stringify({
+            recorded: true,
+            inject_id: payload.inject_id,
+            turn_index: payload.turn_index,
+            offered: payload.evidence_offered,
+            outcome: "pending",
+            window_deadline: payload.window_deadline,
+            coverage_gap_type: coverageGapType,
+        }));
+        return 0;
+    }
+    catch {
+        // Fail-soft: an inject failing to record never disturbs the session.
+        console.log(JSON.stringify({ recorded: false, reason: "error" }));
+        return 0;
+    }
+}