@mmnto/totem 1.105.0 → 1.107.0

package/dist/ledger.js

@@ -1,8 +1,34 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { z } from 'zod';
+import { checkQbdCorrelationId } from './qbd/correlation-id.js';
 // ─── Schema ─────────────────────────────────────────
-export const LedgerEventSchema = z.object({
+/**
+ * Every ledger event type, in one place.
+ *
+ * Consumers that need to partition the type space (e.g. the query-before-derive
+ * scanner, which must tell "another subsystem's row" from "a row that concerns
+ * me") MUST derive their sets from this constant rather than hand-mirroring it.
+ * A hand-copied list silently rots the moment a type is added here, and for the
+ * QBD scanner that rot changes a DEGRADED verdict — see `qbd/compliance.ts`.
+ */
+export const LEDGER_EVENT_TYPES = [
+    'suppress',
+    'override',
+    'exemption',
+    'mcp_call',
+    'tool_call_first_significant',
+    'hook_fire',
+    'session_start',
+    'compile_run',
+    'claim_discipline_finding',
+    'compile_cache_decision',
+    'corpus_query',
+    'derive_action',
+];
+/** Ledger event types that belong to the query-before-derive metric (#2510). */
+export const QBD_EVENT_TYPES = ['corpus_query', 'derive_action'];
+const LedgerEventShape = z.object({
     /** ISO 8601 timestamp */
     timestamp: z.string().datetime(),
     /**
@@ -31,22 +57,21 @@ export const LedgerEventSchema = z.object({
      *                                    `cache_miss_fingerprint_changed` / `cache_miss_force` /
      *                                    `cache_miss_no_prior_record`) per Proposal 281.
      *
+     *  Query-before-derive events (mmnto-ai/totem#2510; see `qbd/`):
+     *  - `corpus_query`  — a corpus query fired (`totem search` CLI or the MCP `search_knowledge`
+     *                      tool); `activity_name` carries which surface. Mints a fresh
+     *                      `qbd_correlation_id` at write time.
+     *  - `derive_action` — a derive-class action ran (`totem spec` synthesis, `totem orient`
+     *                      derivation, `totem review` grounding); `activity_name` carries which.
+     *                      Carries the `qbd_correlation_id` of the query that grounded it, or
+     *                      NO id when nothing grounded it — an uncorrelated derive is a real,
+     *                      countable data point, never a dropped row (#2510 falsifier 1).
+     *
      *  Schema-level: `ruleId` + `file` are optional to accommodate activity events. Writer-side
      *  discipline enforces required-by-type. Promotion to `z.discriminatedUnion` deferred to A.3.c
      *  per design doc OQ-1 (.handoff/_shared/2026-05-15-a3a-schema-extension-design.md).
      */
-    type: z.enum([
-        'suppress',
-        'override',
-        'exemption',
-        'mcp_call',
-        'tool_call_first_significant',
-        'hook_fire',
-        'session_start',
-        'compile_run',
-        'claim_discipline_finding',
-        'compile_cache_decision',
-    ]),
+    type: z.enum(LEDGER_EVENT_TYPES),
     /** Rule ID (lessonHash) for override events. Optional; required by writer for suppress/override/exemption. */
     ruleId: z.string().trim().min(1).optional(),
     /** File where the suppression/override occurred. Optional; required by writer for suppress/override/exemption. */
@@ -122,6 +147,59 @@ export const LedgerEventSchema = z.object({
      * writer convention even though the field lives on the base schema.
      */
     addressed_in_pr: z.boolean().optional(),
+    /**
+     * Query-before-derive correlation ID (mmnto-ai/totem#2510) — the join key
+     * between a `corpus_query` row and the `derive_action` rows that query
+     * grounded. Distinct from `correlation_id` (ADR-014 orchestrator→MCP trace),
+     * which this slice is explicitly not chartered to build on.
+     *
+     * Self-dating by construction: the ID embeds its own mint instant, and
+     * `LedgerEventSchema`'s refinement below cross-checks that instant against
+     * this row's `timestamp`. That is what makes "minted at event-write time" a
+     * schema constraint rather than a convention — see `qbd/correlation-id.ts`
+     * for the exact contract and its honest limits.
+     *
+     * Absent on a `derive_action` = that derive was not grounded by a query. That
+     * is the metric's most important signal, not a gap: it must be counted in the
+     * denominator (#2510 falsifier 1, denominator gaming).
+     */
+    qbd_correlation_id: z.string().trim().min(1).optional(),
+});
+/**
+ * The Trap Ledger event schema.
+ *
+ * The refinement enforces the #2510 minted-at-write-time contract structurally:
+ * a row whose `qbd_correlation_id` could not have been minted when the row was
+ * written fails to parse. Per the charter, "a backfilled ID is a schema
+ * violation, not a data point" — so such a row is never counted as compliant by
+ * anyone reading through this schema.
+ *
+ * Note for readers: `readLedgerEvents` SKIPS schema-invalid lines, so a
+ * violating row silently disappears from generic consumers. The compliance
+ * scanner (`qbd/compliance.ts`) therefore does NOT read through that helper —
+ * it counts every rejected row per-item so a tampered or torn ledger renders as
+ * DEGRADED instead of as a clean number (ADR-115 § 2).
+ */
+export const LedgerEventSchema = LedgerEventShape.superRefine((event, ctx) => {
+    if (event.qbd_correlation_id === undefined)
+        return;
+    const eventMs = Date.parse(event.timestamp);
+    if (!Number.isFinite(eventMs)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['qbd_correlation_id'],
+            message: 'qbd_correlation_id present on a row with an unparseable timestamp',
+        });
+        return;
+    }
+    const check = checkQbdCorrelationId(event.qbd_correlation_id, event.type, eventMs);
+    if (!check.ok) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['qbd_correlation_id'],
+            message: `${check.violation ?? 'invalid'}: ${check.detail ?? 'invalid qbd_correlation_id'}`,
+        });
+    }
 });
 // ─── Constants ──────────────────────────────────────
 const LEDGER_DIR = 'ledger';

package/dist/ledger.js.map

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

package/dist/qbd/compliance.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Query-before-derive compliance — the metric (mmnto-ai/totem#2510).
+ *
+ * ## The number
+ *
+ * Of the derive-class actions in an agent session (spec synthesis, orientation
+ * derivation, review grounding), what fraction was preceded by a corpus query
+ * correlated to that action?
+ *
+ *     compliance = correlated derive events / ALL derive events
+ *
+ * ## Denominator discipline (#2510 falsifier 1)
+ *
+ * The denominator is **every** derive-class event in the evaluated sessions,
+ * including sessions that fired zero queries. A session that derived without
+ * ever querying is the exact behaviour this metric exists to catch, so it must
+ * pull the number DOWN, not vanish from it. Two places this could have been
+ * gamed, and how each is closed:
+ *
+ *  - *at the ratio level* — counting only derives that carry an ID. Closed: the
+ *    denominator counts derive rows, correlated or not.
+ *  - *at the window level* — enumerating only sessions that contain queries.
+ *    Closed: session selection keys on "carries ≥1 derive-class event,
+ *    regardless of query count", which is the operator-pinned window phrasing.
+ *
+ * ## Numerator discipline (#2510 falsifier 2)
+ *
+ * A derive counts as correlated only when its `qbd_correlation_id` resolves to
+ * a `corpus_query` row that actually appears earlier in the ledger, in the same
+ * session and from the same seat. Ways that check fails, all counted as
+ * anomalies and none as compliant: a schema-rejected ID (see
+ * `correlation-id.ts`), an ID with no matching query row (orphan — a truncated
+ * or tampered ledger), an ID whose query row belongs to a different session or
+ * a different seat, and a row whose timestamp regresses in an append-only file
+ * (a backdated append trying to seize the evaluation window).
+ *
+ * One query grounds exactly ONE derive — the pointer is consumed on use (see
+ * `record.ts`). Without that, a single query would credit every derive for the
+ * rest of the correlation window.
+ *
+ * ## What this metric CANNOT see (#2510 falsifier 4, ritual query)
+ *
+ * A query fired purely to satisfy the metric, whose results the following
+ * derive never reads, is indistinguishable here from a query that genuinely
+ * grounded the derive. Both produce a query row and a correlated derive row.
+ * v1 senses adjacency, not influence. This is named, not solved — the honest
+ * statement is that the number measures whether querying happened before
+ * deriving, NOT whether the derive used what the query returned. Any reading
+ * that treats it as the latter is over-claiming.
+ *
+ * ## Degraded reads (ADR-115 § 2)
+ *
+ * `readLedgerEvents` skips schema-invalid lines silently, which would let a torn
+ * or tampered ledger render as a confident 100% or a confident 0%. This scanner
+ * therefore parses the NDJSON itself and counts every rejected line by class. A
+ * scan with any integrity anomaly is `degraded`, and the render must announce
+ * that rather than print a bare number.
+ */
+/** Pre-registered floor. Below this at the checkpoint, the claim is falsified. */
+export declare const QBD_PRE_REGISTERED_THRESHOLD = 0.5;
+/** Pre-registered evaluation window, in sessions. */
+export declare const QBD_PRE_REGISTERED_WINDOW_SESSIONS = 20;
+/**
+ * The pre-registration, verbatim as pinned by the operator ruling 2026-07-28 on
+ * mmnto-ai/totem#2510. Rendered verbatim by the doctor section — the exact
+ * phrasing is load-bearing: an earlier "first 20 correlated sessions" wording
+ * was post-hoc-interpretable as excluding zero-query sessions, which would have
+ * enacted falsifier 1 at the window level. Do not paraphrase this string.
+ */
+export declare const QBD_PRE_REGISTRATION_STATEMENT = "compliance \u2265 0.50, evaluated over the first 20 instrumented sessions carrying \u22651 derive-class event, regardless of query count";
+export type QbdEventType = 'corpus_query' | 'derive_action';
+/** A QBD row lifted out of the ledger. */
+export interface QbdRow {
+    ms: number;
+    type: QbdEventType;
+    activityName?: string;
+    sessionId?: string;
+    correlationId?: string;
+    agentSource?: string;
+}
+/** Per-item anomaly accounting — every rejected or unjoinable item, by class. */
+export interface QbdAnomalies {
+    /** Lines that were not valid JSON (a torn append, a hand-edit). */
+    malformedJson: number;
+    /**
+     * Lines that parsed as JSON but were rejected by the ledger schema while
+     * looking like QBD rows — this is where a backfilled correlation ID lands.
+     */
+    correlationContractViolations: number;
+    /** Lines rejected by the schema whose event type could not be classified. */
+    unclassifiedInvalid: number;
+    /** Derive rows whose correlation ID matches no earlier query row. */
+    orphanCorrelations: number;
+    /** Derive rows whose correlated query row belongs to a different session. */
+    crossSessionCorrelations: number;
+    /**
+     * Derive rows citing a correlation ID an earlier derive already spent. One
+     * query grounds one derive; a re-citation means the write-side consume
+     * failed, raced, or was bypassed.
+     */
+    duplicateCorrelations: number;
+    /**
+     * Uncorrelated derives that had an in-window query from a DIFFERENT seat —
+     * the signature of one-sided seat plumbing. A diagnostic hint, never an
+     * integrity anomaly, so it does not degrade the read.
+     */
+    seatMismatchHints: number;
+    /**
+     * Rows whose timestamp regresses behind the newest already seen in this
+     * append-only file — the backdated-append attack on the evaluation window.
+     */
+    backdatedRows: number;
+    /**
+     * Rows carrying an event type this build does not know. An ADVISORY, not an
+     * integrity anomaly: the ordinary cause is version skew, and it deliberately
+     * does NOT flip `degraded`.
+     */
+    unknownTypeRows: number;
+    /** Human-readable detail lines, capped, for the render. */
+    details: string[];
+}
+export interface QbdScanResult {
+    rows: QbdRow[];
+    /** Non-empty lines examined. */
+    linesScanned: number;
+    anomalies: QbdAnomalies;
+    /**
+     * True when any integrity anomaly fired. A degraded scan must never render as
+     * a clean number (ADR-115 § 2) — the number it would print is not trustworthy
+     * because rows are known to be missing or rejected.
+     */
+    degraded: boolean;
+}
+export interface QbdRateStat {
+    /** Derive-class events counted (the denominator). */
+    derives: number;
+    /** Of `derives`, how many were correlated to a preceding query. */
+    correlated: number;
+}
+export type QbdVerdict = 'PENDING' | 'PASS' | 'FAIL';
+export interface QbdComplianceReport {
+    /** Sessions carrying ≥1 derive-class event, in first-seen order. */
+    instrumentedSessions: number;
+    /** Sessions actually evaluated (capped at the pre-registered window). */
+    evaluatedSessions: number;
+    /** The pre-registration window's rate. */
+    window: QbdRateStat;
+    /** The rate, or null when there is nothing to divide. */
+    compliance: number | null;
+    /**
+     * `PENDING` until the window fills — the pre-registered threshold is not
+     * evaluable before then, and calling it early in either direction would be
+     * exactly the post-hoc reinterpretation the registration forbids.
+     */
+    verdict: QbdVerdict;
+    /** Trend across all instrumented sessions, earlier half vs recent half. */
+    trend: {
+        earlier: QbdRateStat;
+        recent: QbdRateStat;
+    } | null;
+    anomalies: QbdAnomalies;
+    degraded: boolean;
+}
+/**
+ * Parse the raw `events.ndjson` contents, lifting out QBD rows and counting
+ * every line this metric could not trust.
+ *
+ * Deliberately does NOT use `readLedgerEvents`: that helper drops schema-invalid
+ * lines without telling anyone, which is precisely how a tampered ledger would
+ * render as a clean number.
+ */
+export declare function scanQbdLedger(content: string): QbdScanResult;
+/**
+ * One instrumented session: the unit the pre-registered evaluation window
+ * counts in. Exported because `groupQbdSessions` returns it through the package
+ * barrel — a consumer could call that function but not name its return type.
+ */
+export interface QbdSession {
+    /** Stable identity: `sid:<agent>:<session_id>` or `win:<agent>:<n>`. */
+    key: string;
+    /** Earliest row instant in the session; sessions are ordered by this. */
+    firstMs: number;
+    /** The session's rows, in time order. */
+    rows: QbdRow[];
+}
+/**
+ * Group rows into sessions.
+ *
+ * Rows carrying a `session_id` group by it. Rows without one (hookless agents,
+ * pre-hook runs) fall back to a rolling-window roll-up, applied among
+ * themselves and PARTITIONED BY `agent_source`. Both are "instrumented
+ * sessions"; neither is privileged.
+ *
+ * The agent partition matters concretely: cohort seats share one working tree
+ * per repo, so two seats writing to the same ledger inside the same two-hour
+ * span would otherwise be rolled into a single "session", letting one seat's
+ * query sit in the same session as another seat's derive. Sessions are
+ * per-agent, so the fallback is too.
+ *
+ * Note on provenance: preferring an explicit session id over a time heuristic
+ * follows the `.session-id` primitive's own documented contract
+ * (`session-id.ts`), not ADR-029 § 2 — that section defines a session-GROUPING
+ * heuristic for the recall metric, which is a different question.
+ */
+export declare function groupQbdSessions(rows: QbdRow[]): QbdSession[];
+/**
+ * Compute the compliance report from a scan.
+ *
+ * The verdict stays `PENDING` until the pre-registered window fills. That is
+ * deliberate: declaring PASS at n=3 would be as much a post-hoc reinterpretation
+ * of the registration as moving the threshold would be.
+ */
+export declare function computeQbdCompliance(scan: QbdScanResult): QbdComplianceReport;
+/** Format a rate as a fixed-2 fraction, or `n/a` when there is nothing to divide. */
+export declare function formatQbdRate(stat: QbdRateStat): string;
+//# sourceMappingURL=compliance.d.ts.map

package/dist/qbd/compliance.d.ts.map

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