@mmnto/totem 1.105.0 → 1.107.0

package/dist/qbd/record.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Query-before-derive (QBD) event writers (mmnto-ai/totem#2510).
+ *
+ * Two row types, one contract:
+ *
+ *  - `recordCorpusQuery`  — a corpus query fired. Mints a fresh correlation ID
+ *    **from the same clock read that stamps the row's `timestamp`**, so the ID
+ *    and the row are born together. Then parks the ID in a pointer file for the
+ *    derives that follow.
+ *  - `recordDeriveAction` — a derive-class action ran. Reads the parked ID and
+ *    attaches it *only if* it is still inside the correlation window, from this
+ *    session, and from this seat. Otherwise the row is written with NO
+ *    correlation ID — an uncorrelated derive is the metric's most important
+ *    observation, so it is always recorded, never dropped (#2510 falsifier 1).
+ *
+ * ## Consumption semantics: one query grounds ONE derive
+ *
+ * The pointer is CONSUMED by the first derive that correlates to it. Without
+ * that, a single query would credit every derive for the rest of the
+ * correlation window — one query, ten derives, compliance 1.00 — which measures
+ * "queried at least once per two hours", not "queried before deriving". The
+ * strict 1:1 reading is the one that can actually be falsified, so it is the
+ * one implemented. A second derive after a single query is UNCORRELATED, and
+ * that is the correct reading, not a miss.
+ *
+ * ## Correlation is scoped to one seat AND one session, fail-closed
+ *
+ * Both sides must carry a session id and agree on it, and the seats must match.
+ * Cohort seats share one working tree per repo, so a pointer left by another
+ * seat is reachable; treating a missing id as a match would let it ground this
+ * seat's derive.
+ *
+ * **Seat comparison is equality including "both unknown".** When neither side
+ * is seated (`TOTEM_SELF_AGENT` unset), they compare equal and correlation
+ * proceeds. That is the deliberate default for the solo/unseated case, which is
+ * the common one — requiring a seat would make the metric unusable for anyone
+ * not running a cohort. The cost is disclosed rather than hidden: seat exactly
+ * ONE side and correlation stops entirely. That is a live configuration today —
+ * the CLI can be seated while the MCP server is not — and it produces a
+ * truthful-looking 0.00 whose pre-registered consequence is falsified adherence
+ * claims. The scanner therefore emits a seat-mismatch hint (see
+ * `compliance.ts`) so the config smell is visible instead of silent. Wiring the
+ * MCP server's seat is out of this slice's scope and tracked in
+ * mmnto-ai/totem#2530.
+ *
+ * ## Why minting lives here and nowhere else
+ *
+ * `mintQbdCorrelationId(now)` takes the instant as an argument, which would let
+ * a caller pass any instant it liked. Every production writer goes through this
+ * module, where `now` is read once and used for BOTH the ID and the timestamp.
+ * A caller that tried to route around it would have to hand-build a row, and the
+ * schema refinement in `ledger.ts` rejects any row whose ID could not have been
+ * minted when the row was written. Convention here, enforcement in the schema.
+ *
+ * ## Failure posture (Tenet 13 + ADR-115 § 2)
+ *
+ * A contract breach — a pointer file holding a forged, malformed, or
+ * out-of-window ID — makes the schema reject the row, and these functions THROW
+ * (the loud backstop; a backfilled ID is a schema violation, not a data point).
+ * An ordinary I/O failure does not throw; it is reported through the returned
+ * `warnings` array.
+ *
+ * Neither may break the instrumented command. That is what the `sense*`
+ * wrappers are for: they catch the backstop, convert it to a visible warning,
+ * and return. Command call sites use `sense*`; the throwing variants exist so
+ * the contract is testable and so a programming error is never silent.
+ */
+/** Which surface fired a `corpus_query`. Stamped as `activity_name`. */
+export type QbdQuerySurface = 'totem_search' | 'search_knowledge';
+/** Which derive-class action ran. Stamped as `activity_name`. */
+export type QbdDeriveSurface = 'spec' | 'orient' | 'review';
+export interface QbdRecordInput {
+    /** Absolute path to the resolved `.totem` directory. */
+    totemDir: string;
+    /** Emitting subsystem: `lint` for CLI commands, `bot` for the MCP server. */
+    source: 'lint' | 'bot';
+    /** Test seam — production callers omit and the writer reads the clock. */
+    nowMs?: number;
+    /** Test seam — production callers omit and the writer reads `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+export interface QbdRecordResult {
+    /** True when the ledger row reached disk. */
+    written: boolean;
+    /**
+     * True when nothing was recorded because this is not an instrumented project
+     * (no `.totem` directory). Distinguishes "nothing to instrument here" — a
+     * normal state — from "the write failed", which is a degradation.
+     */
+    skipped?: boolean;
+    /** The correlation ID on the row, when it carries one. */
+    correlationId?: string;
+    /**
+     * Per-item accounting. Every non-fatal degradation names itself here; the
+     * caller renders these so a sensor failure is visible, never silent
+     * (ADR-115 § 2 accounting contract).
+     */
+    warnings: string[];
+}
+/**
+ * Resolve the emitting seat from `TOTEM_SELF_AGENT`, reusing the comma-split
+ * precedent of `deriveSearchLogAttribution` / `resolveSelfAgents` — a process
+ * runs under one seat, so the first non-empty entry is that seat.
+ */
+export declare function resolveQbdAgentSource(env: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Record a corpus query and mint its correlation ID.
+ *
+ * `nowMs` is read ONCE and used for both the ID's embedded mint instant and the
+ * row's `timestamp` — the property the schema refinement checks.
+ */
+export declare function recordCorpusQuery(input: QbdRecordInput & {
+    surface: QbdQuerySurface;
+}): QbdRecordResult;
+/**
+ * Record a derive-class action, attaching the correlation ID of the query that
+ * grounded it when one is in scope.
+ *
+ * Throws on a correlation-contract breach — AFTER the derive row has been
+ * written uncorrelated. The ledger is left correct either way; the throw is the
+ * loud backstop that stops a tampered pointer from passing as a data point.
+ */
+export declare function recordDeriveAction(input: QbdRecordInput & {
+    surface: QbdDeriveSurface;
+}): QbdRecordResult;
+/** Sensor-safe `recordCorpusQuery`. Command call sites use this. */
+export declare function senseCorpusQuery(input: QbdRecordInput & {
+    surface: QbdQuerySurface;
+}, onWarn?: (msg: string) => void): QbdRecordResult;
+/**
+ * Sensor-safe `recordDeriveAction`. Command call sites use this.
+ *
+ * A correlation-contract breach is reported as a warning rather than thrown —
+ * and, critically, the derive row it refused to correlate has still been
+ * written, so `written` stays true and the denominator is intact.
+ */
+export declare function senseDeriveAction(input: QbdRecordInput & {
+    surface: QbdDeriveSurface;
+}, onWarn?: (msg: string) => void): QbdRecordResult;
+//# sourceMappingURL=record.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/qbd/record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AA8BH,wEAAwE;AACxE,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,kBAAkB,CAAC;AAElE,iEAAiE;AACjE,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAI5D,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;IACvB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAID;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,GAAG,SAAS,CAShF;AA6KD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,cAAc,GAAG;IAAE,OAAO,EAAE,eAAe,CAAA;CAAE,GACnD,eAAe,CAyCjB;AA6FD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,cAAc,GAAG;IAAE,OAAO,EAAE,gBAAgB,CAAA;CAAE,GACpD,eAAe,CAIjB;AA2BD,oEAAoE;AACpE,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,cAAc,GAAG;IAAE,OAAO,EAAE,eAAe,CAAA;CAAE,EACpD,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAC7B,eAAe,CAEjB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,cAAc,GAAG;IAAE,OAAO,EAAE,gBAAgB,CAAA;CAAE,EACrD,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAC7B,eAAe,CAMjB"}

package/dist/qbd/record.js

@@ -0,0 +1,419 @@
+/**
+ * Query-before-derive (QBD) event writers (mmnto-ai/totem#2510).
+ *
+ * Two row types, one contract:
+ *
+ *  - `recordCorpusQuery`  — a corpus query fired. Mints a fresh correlation ID
+ *    **from the same clock read that stamps the row's `timestamp`**, so the ID
+ *    and the row are born together. Then parks the ID in a pointer file for the
+ *    derives that follow.
+ *  - `recordDeriveAction` — a derive-class action ran. Reads the parked ID and
+ *    attaches it *only if* it is still inside the correlation window, from this
+ *    session, and from this seat. Otherwise the row is written with NO
+ *    correlation ID — an uncorrelated derive is the metric's most important
+ *    observation, so it is always recorded, never dropped (#2510 falsifier 1).
+ *
+ * ## Consumption semantics: one query grounds ONE derive
+ *
+ * The pointer is CONSUMED by the first derive that correlates to it. Without
+ * that, a single query would credit every derive for the rest of the
+ * correlation window — one query, ten derives, compliance 1.00 — which measures
+ * "queried at least once per two hours", not "queried before deriving". The
+ * strict 1:1 reading is the one that can actually be falsified, so it is the
+ * one implemented. A second derive after a single query is UNCORRELATED, and
+ * that is the correct reading, not a miss.
+ *
+ * ## Correlation is scoped to one seat AND one session, fail-closed
+ *
+ * Both sides must carry a session id and agree on it, and the seats must match.
+ * Cohort seats share one working tree per repo, so a pointer left by another
+ * seat is reachable; treating a missing id as a match would let it ground this
+ * seat's derive.
+ *
+ * **Seat comparison is equality including "both unknown".** When neither side
+ * is seated (`TOTEM_SELF_AGENT` unset), they compare equal and correlation
+ * proceeds. That is the deliberate default for the solo/unseated case, which is
+ * the common one — requiring a seat would make the metric unusable for anyone
+ * not running a cohort. The cost is disclosed rather than hidden: seat exactly
+ * ONE side and correlation stops entirely. That is a live configuration today —
+ * the CLI can be seated while the MCP server is not — and it produces a
+ * truthful-looking 0.00 whose pre-registered consequence is falsified adherence
+ * claims. The scanner therefore emits a seat-mismatch hint (see
+ * `compliance.ts`) so the config smell is visible instead of silent. Wiring the
+ * MCP server's seat is out of this slice's scope and tracked in
+ * mmnto-ai/totem#2530.
+ *
+ * ## Why minting lives here and nowhere else
+ *
+ * `mintQbdCorrelationId(now)` takes the instant as an argument, which would let
+ * a caller pass any instant it liked. Every production writer goes through this
+ * module, where `now` is read once and used for BOTH the ID and the timestamp.
+ * A caller that tried to route around it would have to hand-build a row, and the
+ * schema refinement in `ledger.ts` rejects any row whose ID could not have been
+ * minted when the row was written. Convention here, enforcement in the schema.
+ *
+ * ## Failure posture (Tenet 13 + ADR-115 § 2)
+ *
+ * A contract breach — a pointer file holding a forged, malformed, or
+ * out-of-window ID — makes the schema reject the row, and these functions THROW
+ * (the loud backstop; a backfilled ID is a schema violation, not a data point).
+ * An ordinary I/O failure does not throw; it is reported through the returned
+ * `warnings` array.
+ *
+ * Neither may break the instrumented command. That is what the `sense*`
+ * wrappers are for: they catch the backstop, convert it to a visible warning,
+ * and return. Command call sites use `sense*`; the throwing variants exist so
+ * the contract is testable and so a programming error is never silent.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { TotemError } from '../errors.js';
+import { appendLedgerEvent, LedgerEventSchema } from '../ledger.js';
+import { readSessionId } from '../session-id.js';
+import { checkQbdCorrelationId, mintQbdCorrelationId, QBD_CORRELATION_WINDOW_MS, } from './correlation-id.js';
+// ─── Constants ──────────────────────────────────────────
+const LEDGER_DIR = 'ledger';
+/**
+ * Where the most recently minted correlation ID is parked for the derives that
+ * follow it. Mirrors the `.session-id` pointer convention deliberately — same
+ * directory, same fire-and-forget posture, same "a missing pointer is a normal
+ * state" reading.
+ */
+const QBD_POINTER_FILE = '.qbd-correlation';
+/** UUID shape check — `session_id` is `z.string().uuid()` in the ledger schema. */
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// ─── Env attribution ────────────────────────────────────
+/**
+ * Resolve the emitting seat from `TOTEM_SELF_AGENT`, reusing the comma-split
+ * precedent of `deriveSearchLogAttribution` / `resolveSelfAgents` — a process
+ * runs under one seat, so the first non-empty entry is that seat.
+ */
+export function resolveQbdAgentSource(env) {
+    const raw = env.TOTEM_SELF_AGENT;
+    if (typeof raw !== 'string')
+        return undefined;
+    return (raw
+        .split(',')
+        .map((s) => s.trim())
+        .find((s) => s.length > 0) ?? undefined);
+}
+/**
+ * Resolve the session UUID: the `.session-id` pointer first (the established
+ * primitive), then `TOTEM_SESSION_ID`. A value that is not UUID-shaped is
+ * dropped rather than stamped — the ledger schema requires a UUID, and stamping
+ * a malformed one would make the whole row unparseable, losing the event.
+ */
+function resolveSessionId(totemDir, env) {
+    const fromPointer = readSessionId(totemDir);
+    if (fromPointer !== undefined)
+        return fromPointer;
+    const fromEnv = env.TOTEM_SESSION_ID;
+    if (typeof fromEnv === 'string' && UUID_PATTERN.test(fromEnv.trim()))
+        return fromEnv.trim();
+    return undefined;
+}
+function pointerPath(totemDir) {
+    return path.join(totemDir, LEDGER_DIR, QBD_POINTER_FILE);
+}
+function writePointer(totemDir, pointer, warnings) {
+    try {
+        fs.mkdirSync(path.join(totemDir, LEDGER_DIR), { recursive: true });
+        fs.writeFileSync(pointerPath(totemDir), JSON.stringify(pointer), 'utf-8');
+        // totem-context: intentional cleanup — the correlation pointer is telemetry; a sensor must never fail the command it instruments (Tenet 13). NOT swallowed: recorded on the `warnings` accounting channel and surfaced by the caller.
+    }
+    catch (err) {
+        // totem-context: intentional cleanup — the correlation pointer is telemetry; a sensor must never fail the command it instruments (Tenet 13). NOT swallowed: recorded on the `warnings` accounting channel and surfaced by the caller.
+        const msg = err instanceof Error ? err.message : String(err);
+        warnings.push(`query-before-derive: correlation pointer write failed: ${msg}`);
+    }
+}
+/**
+ * Consume the parked pointer, so one query grounds exactly one derive.
+ *
+ * Best-effort: if the pointer cannot be removed, the failure is reported on the
+ * accounting channel. A surviving pointer would over-credit, so this is a real
+ * degradation and is never silent.
+ */
+function clearPointer(totemDir, warnings) {
+    try {
+        fs.rmSync(pointerPath(totemDir), { force: true });
+        // totem-context: intentional cleanup — consuming the correlation pointer is telemetry bookkeeping; a failure is reported on the `warnings` accounting channel rather than thrown, because it must not fail the instrumented command (Tenet 13).
+    }
+    catch (err) {
+        // totem-context: intentional cleanup — consuming the correlation pointer is telemetry bookkeeping; a failure is reported on the `warnings` accounting channel rather than thrown, because it must not fail the instrumented command (Tenet 13).
+        const msg = err instanceof Error ? err.message : String(err);
+        warnings.push(`query-before-derive: could not consume the correlation pointer (${msg}) — it may over-credit until removed`);
+    }
+}
+/**
+ * Read the parked correlation pointer. A missing or unreadable pointer is a
+ * normal state (first query of a session, fresh repo) and reads as `undefined`.
+ *
+ * A pointer that is present but structurally wrong is NOT silently ignored — it
+ * is returned as-is so the schema check downstream rejects it loudly. Swallowing
+ * it here would be exactly the silent-degradation shape ADR-115 § 2 forbids.
+ */
+function readPointer(totemDir, warnings) {
+    let raw;
+    try {
+        raw = fs.readFileSync(pointerPath(totemDir), 'utf-8');
+        // totem-context: intentional cleanup — an absent pointer (ENOENT) is a normal state, not a failure; every OTHER errno is recorded on the `warnings` accounting channel rather than thrown, because telemetry must not fail the instrumented command (Tenet 13).
+    }
+    catch (err) {
+        // totem-context: intentional cleanup — an absent pointer (ENOENT) is a normal state, not a failure; every OTHER errno is recorded on the `warnings` accounting channel rather than thrown, because telemetry must not fail the instrumented command (Tenet 13).
+        const code = typeof err === 'object' && err !== null ? err.code : undefined;
+        // ENOTDIR alongside ENOENT: a path COMPONENT being a file means there is no
+        // pointer here, same as the file being absent. Same cross-platform
+        // divergence `session-id.ts` documents — POSIX says ENOTDIR where Windows
+        // says ENOENT for the identical on-disk state — so both must read as
+        // "absent", or the derive path warns on one platform and not the other.
+        if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+            const msg = err instanceof Error ? err.message : String(err);
+            warnings.push(`query-before-derive: correlation pointer unreadable: ${msg}`);
+        }
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null) {
+            warnings.push('query-before-derive: correlation pointer is not an object — ignoring');
+            return undefined;
+        }
+        const rec = parsed;
+        if (typeof rec.id !== 'string' || typeof rec.mintedAtMs !== 'number') {
+            warnings.push('query-before-derive: correlation pointer is missing id/mintedAtMs — ignoring');
+            return undefined;
+        }
+        return {
+            id: rec.id,
+            mintedAtMs: rec.mintedAtMs,
+            sessionId: typeof rec.sessionId === 'string' ? rec.sessionId : null,
+            agentSource: typeof rec.agentSource === 'string' ? rec.agentSource : null,
+        };
+        // totem-context: intentional cleanup — a corrupt pointer degrades to "no correlation in scope" and is reported on the `warnings` accounting channel; throwing would let a hand-edited telemetry file break `totem spec` / `orient` / `review`.
+    }
+    catch (err) {
+        // totem-context: intentional cleanup — a corrupt pointer degrades to "no correlation in scope" and is reported on the `warnings` accounting channel; throwing would let a hand-edited telemetry file break `totem spec` / `orient` / `review`.
+        const msg = err instanceof Error ? err.message : String(err);
+        warnings.push(`query-before-derive: correlation pointer is not valid JSON (${msg}) — ignoring`);
+        return undefined;
+    }
+}
+// ─── Shared write path ──────────────────────────────────
+/**
+ * Is this an instrumented project at all?
+ *
+ * The derive-class commands (`orient` especially) run from anywhere, including
+ * directories that are not Totem projects. `appendLedgerEvent` creates its
+ * directory tree on demand, so without this guard the sensor would materialise a
+ * stray `.totem/ledger/` in any directory a command happened to run in.
+ *
+ * An absent `.totem` is a NORMAL state, not a degradation — it means "nothing
+ * here to instrument" — so this path is silent rather than warned. A totemDir
+ * that EXISTS but cannot be written to is a different thing entirely, and that
+ * still reports through the accounting channel.
+ */
+function isInstrumentedProject(totemDir) {
+    try {
+        return fs.statSync(totemDir).isDirectory();
+        // totem-context: a missing `.totem` is the honest "not a Totem project" state for this sensor — skip silently rather than creating a stray directory in an unrelated cwd.
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate against the ledger schema, then append.
+ *
+ * The schema carries the minted-at-write-time refinement, so this is the single
+ * choke point where a backfilled or forged correlation ID becomes a thrown
+ * error instead of a persisted "data point".
+ */
+function validateAndAppend(totemDir, event, warnings) {
+    const parsed = LedgerEventSchema.safeParse(event);
+    if (!parsed.success) {
+        const detail = parsed.error.issues.map((i) => i.message).join('; ');
+        throw new TotemError('QBD_CORRELATION_CONTRACT', `Refusing to write a query-before-derive row that violates the correlation contract: ${detail}`, 'A correlation ID must be minted at event-write time. Delete the stale `.totem/ledger/.qbd-correlation` pointer if it was hand-edited.');
+    }
+    let written = true;
+    appendLedgerEvent(totemDir, parsed.data, (msg) => {
+        written = false;
+        warnings.push(`query-before-derive: ${msg}`);
+    });
+    return { written };
+}
+// ─── Writers ────────────────────────────────────────────
+/**
+ * Record a corpus query and mint its correlation ID.
+ *
+ * `nowMs` is read ONCE and used for both the ID's embedded mint instant and the
+ * row's `timestamp` — the property the schema refinement checks.
+ */
+export function recordCorpusQuery(input) {
+    const env = input.env ?? process.env;
+    const nowMs = input.nowMs ?? Date.now();
+    const warnings = [];
+    if (!isInstrumentedProject(input.totemDir))
+        return { written: false, skipped: true, warnings };
+    const correlationId = mintQbdCorrelationId(nowMs);
+    const sessionId = resolveSessionId(input.totemDir, env);
+    const agentSource = resolveQbdAgentSource(env);
+    const event = {
+        timestamp: new Date(nowMs).toISOString(),
+        type: 'corpus_query',
+        activity_name: input.surface,
+        source: input.source,
+        justification: '',
+        qbd_correlation_id: correlationId,
+        ...(sessionId !== undefined && { session_id: sessionId }),
+        ...(agentSource !== undefined && { agent_source: agentSource }),
+    };
+    const { written } = validateAndAppend(input.totemDir, event, warnings);
+    // Park the ID for following derives ONLY if the query row actually landed.
+    // Parking an ID whose query row failed to write would manufacture orphan
+    // correlations — derives pointing at a query that does not exist.
+    if (written) {
+        writePointer(input.totemDir, {
+            id: correlationId,
+            mintedAtMs: nowMs,
+            sessionId: sessionId ?? null,
+            agentSource: agentSource ?? null,
+        }, warnings);
+    }
+    return { written, correlationId, warnings };
+}
+/**
+ * Shared derive write path used by both the throwing and the sensor variants.
+ *
+ * The parked pointer grounds this derive only when it is (a) inside the
+ * correlation window, (b) from this session, and (c) contract-valid. Otherwise
+ * the row is written WITHOUT an ID — the honest reading being that nothing
+ * grounded this derive — and case (c) additionally reports a breach.
+ */
+function buildAndWriteDerive(input) {
+    const env = input.env ?? process.env;
+    const nowMs = input.nowMs ?? Date.now();
+    const warnings = [];
+    if (!isInstrumentedProject(input.totemDir)) {
+        return { result: { written: false, skipped: true, warnings } };
+    }
+    const sessionId = resolveSessionId(input.totemDir, env);
+    const agentSource = resolveQbdAgentSource(env);
+    const pointer = readPointer(input.totemDir, warnings);
+    let correlationId;
+    let breach;
+    if (pointer !== undefined) {
+        // Same session, fail-CLOSED. Correlation requires BOTH sides to carry a
+        // session id and for them to be equal. The previous "either side missing
+        // counts as a match" reading was a fail-open: a hookless run with no session
+        // id would inherit any pointer lying around, including another seat's.
+        const sameSession = pointer.sessionId !== null && sessionId !== undefined && pointer.sessionId === sessionId;
+        // Same seat. Cohort seats share ONE working tree per repo, so without this
+        // an agent-A query would ground an agent-B derive — a live scenario here,
+        // not a theoretical one. `agent_source` was recorded but never consulted.
+        const sameAgent = (pointer.agentSource ?? undefined) === agentSource;
+        const withinWindow = nowMs - pointer.mintedAtMs <= QBD_CORRELATION_WINDOW_MS;
+        // A stale or foreign pointer is not an error — it simply did not ground
+        // this derive. The row is still written, uncorrelated, into the denominator.
+        if (sameSession && sameAgent && withinWindow) {
+            const check = checkQbdCorrelationId(pointer.id, 'derive_action', nowMs);
+            if (check.ok) {
+                correlationId = pointer.id;
+            }
+            else {
+                // Contract breach: the parked ID could not have been minted at a moment
+                // that would let it ground THIS derive (forged, hand-edited, or from a
+                // clock that ran backwards). It is refused — but the derive row is still
+                // written, uncorrelated, so the denominator never shrinks because the
+                // sensor was tampered with (#2510 falsifier 1). The breach is then
+                // raised loudly by the caller.
+                breach = new TotemError('QBD_CORRELATION_CONTRACT', `Refusing a query-before-derive correlation ID that violates the minted-at-write-time contract (${check.violation ?? 'invalid'}): ${check.detail ?? 'invalid id'}`, 'Delete the `.totem/ledger/.qbd-correlation` pointer; it was hand-edited or written by a clock that disagrees with this one. The derive was recorded as uncorrelated.');
+            }
+        }
+    }
+    const event = {
+        timestamp: new Date(nowMs).toISOString(),
+        type: 'derive_action',
+        activity_name: input.surface,
+        source: input.source,
+        justification: '',
+        ...(correlationId !== undefined && { qbd_correlation_id: correlationId }),
+        ...(sessionId !== undefined && { session_id: sessionId }),
+        ...(agentSource !== undefined && { agent_source: agentSource }),
+    };
+    const { written } = validateAndAppend(input.totemDir, event, warnings);
+    // Consume-on-use: a query grounds exactly ONE derive. Without this the parked
+    // ID stays live for the whole correlation window, so a single query could
+    // credit an unbounded run of derives (measured: 1 query, 10 derives,
+    // compliance 1.00). That reading is not "query before derive", it is "query
+    // once per two hours", which is precisely the shape the metric exists to
+    // detect. Consuming only after a SUCCESSFUL correlated write means a failed
+    // append cannot silently burn the query's grounding.
+    if (written && correlationId !== undefined)
+        clearPointer(input.totemDir, warnings);
+    const result = {
+        written,
+        ...(correlationId !== undefined && { correlationId }),
+        warnings,
+    };
+    return breach === undefined ? { result } : { result, breach };
+}
+/**
+ * Record a derive-class action, attaching the correlation ID of the query that
+ * grounded it when one is in scope.
+ *
+ * Throws on a correlation-contract breach — AFTER the derive row has been
+ * written uncorrelated. The ledger is left correct either way; the throw is the
+ * loud backstop that stops a tampered pointer from passing as a data point.
+ */
+export function recordDeriveAction(input) {
+    const { result, breach } = buildAndWriteDerive(input);
+    if (breach !== undefined)
+        throw breach;
+    return result;
+}
+// ─── Sensor wrappers (never throw) ──────────────────────
+/**
+ * Run a QBD writer as a pure sensor: it may degrade, it may not break the
+ * command it instruments (Tenet 13 / #2510 "sensor failure is not command
+ * failure").
+ *
+ * Every degradation — including a thrown contract breach — is surfaced through
+ * `onWarn`. The accounting contract is "visible, not swallowed": there is no
+ * path here that discards a failure silently.
+ */
+function senseQbd(run, onWarn) {
+    try {
+        const result = run();
+        for (const warning of result.warnings)
+            onWarn?.(warning);
+        return result;
+        // totem-context: instrumentation is a sensor — a telemetry failure must never fail the instrumented command (Tenet 13); the failure is reported through onWarn, never discarded.
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const warning = `query-before-derive sensor failed: ${msg}`;
+        onWarn?.(warning);
+        return { written: false, warnings: [warning] };
+    }
+}
+/** Sensor-safe `recordCorpusQuery`. Command call sites use this. */
+export function senseCorpusQuery(input, onWarn) {
+    return senseQbd(() => recordCorpusQuery(input), onWarn);
+}
+/**
+ * Sensor-safe `recordDeriveAction`. Command call sites use this.
+ *
+ * A correlation-contract breach is reported as a warning rather than thrown —
+ * and, critically, the derive row it refused to correlate has still been
+ * written, so `written` stays true and the denominator is intact.
+ */
+export function senseDeriveAction(input, onWarn) {
+    return senseQbd(() => {
+        const { result, breach } = buildAndWriteDerive(input);
+        if (breach !== undefined)
+            result.warnings.push(`query-before-derive: ${breach.message}`);
+        return result;
+    }, onWarn);
+}
+//# sourceMappingURL=record.js.map

package/dist/qbd/record.js.map

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

package/dist/qbd/record.test.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Writer tests for the query-before-derive sensor (mmnto-ai/totem#2510).
+ *
+ * The induced-failure blocks follow the ADR-115 § 2 three-pack convention used
+ * by `mail-degraded-e4.test.ts`:
+ *   1. per-item accounting fires — the specific failing item is NAMED in the
+ *      warnings channel;
+ *   2. the loud backstop throws — for this MUTATING path that is a literal
+ *      throw from `recordDeriveAction`, and the ledger is left in prior-good
+ *      state (the derive row present, simply uncorrelated) rather than
+ *      "presenting as success while partial";
+ *   3. a recovery / control assertion — with the fault removed the same call
+ *      returns to green, and a healthy control never warns.
+ *
+ * **The two ADR-115 § 2 packs** induce their failures with real errnos (a file
+ * where a directory belongs) or real on-disk state (a hand-written pointer),
+ * never by mocking the module under test — that is what makes them evidence
+ * rather than assertion.
+ *
+ * Other tests in this file DO stamp errnos onto `fs` via `vi.spyOn` (EACCES,
+ * ENOSPC). That is deliberate and scoped: ENOSPC is not inducible on a real
+ * filesystem, and those tests cover accounting branches rather than the
+ * degraded-path contract. The blanket "never by mocking" claim used to sit at
+ * file level and overstated what four of these tests do.
+ */
+export {};
+//# sourceMappingURL=record.test.d.ts.map

package/dist/qbd/record.test.d.ts.map

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