hippo-memory 1.69.0 → 1.71.0

package/dist/consolidate/trace.d.ts

@@ -0,0 +1,19 @@
+/** Trace-layer helpers. A trace is a `MemoryEntry` with `layer === 'trace'`: ordered agent actions and their outcome, stored as markdown in `content`
+ * (`renderTraceContent` formats it). */
+export interface TraceStep {
+    action: string;
+    observation: string;
+    timestamp?: string;
+}
+export interface TraceRecord {
+    task: string;
+    steps: TraceStep[];
+    outcome: 'success' | 'failure' | 'partial';
+}
+/** Render a trace record as agent-readable markdown: `Task:`, `Outcome:`, then numbered `Steps:` with each observation on an arrow line (omitted if empty). */
+export declare function renderTraceContent(rec: TraceRecord): string;
+/**
+ * Parse a JSON string into an array of TraceStep. Throws on invalid shape.
+ */
+export declare function parseSteps(json: string): TraceStep[];
+//# sourceMappingURL=trace.d.ts.map

package/dist/{trace.js → consolidate/trace.js}

@@ -1,22 +1,8 @@
-/**
- * Trace-layer helpers.
- *
- * A trace is a `MemoryEntry` with `layer === 'trace'` that captures an ordered
- * sequence of agent actions and their final outcome. v1 stores steps as
- * markdown in `content`; `renderTraceContent` is the canonical formatter.
- */
-import { isJsonString } from './json.js';
-/**
- * Render a trace record as agent-readable markdown.
- *
- * Format:
- *   Task: <task>
- *   Outcome: <outcome>
- *   Steps:
- *     1. <action>
- *        → <observation>   (omitted if observation is empty)
- *     2. ...
- */
+/** Trace-layer helpers. A trace is a `MemoryEntry` with `layer === 'trace'`: ordered agent actions and their outcome, stored as markdown in `content`
+ * (`renderTraceContent` formats it). */
+import { isJsonString, isJsonObject } from '../util/json.js';
+import { errorMessage } from '../util/log.js';
+/** Render a trace record as agent-readable markdown: `Task:`, `Outcome:`, then numbered `Steps:` with each observation on an arrow line (omitted if empty). */
 export function renderTraceContent(rec) {
     const lines = [];
     lines.push(`Task: ${rec.task}`);
@@ -30,9 +16,6 @@ export function renderTraceContent(rec) {
     });
     return lines.join('\n');
 }
-function isJsonRecord(value) {
-    return value !== null && !Array.isArray(value) && typeof value === 'object';
-}
 /**
  * Parse a JSON string into an array of TraceStep. Throws on invalid shape.
  */
@@ -42,13 +25,13 @@ export function parseSteps(json) {
         parsed = JSON.parse(json);
     }
     catch (err) {
-        throw new Error(`Invalid trace steps JSON: ${err instanceof Error ? err.message : String(err)}`);
+        throw new Error(`Invalid trace steps JSON: ${errorMessage(err)}`, { cause: err });
     }
     if (!Array.isArray(parsed)) {
         throw new Error('trace steps must be an array');
     }
     return parsed.map((s, i) => {
-        if (!isJsonRecord(s)) {
+        if (!isJsonObject(s)) {
             throw new Error(`trace step ${i}: not an object`);
         }
         const action = s.action;

package/dist/consolidate/traces.js

@@ -1,30 +1,25 @@
-import { isRecallBoostAblated } from '../ablation.js';
-import { Layer, createMemory, markRetrieved } from '../memory.js';
+import { isRecallBoostAblated } from '../core/ablation.js';
+import { Layer, createMemory, markRetrieved } from '../core/memory.js';
 import { findPromotableSessions, traceExistsForSession, listSessionEvents } from '../store/sessions.js';
-import { rejectionDigest, findRejectedValue } from '../rejection.js';
-import { sampleForReplay } from '../replay.js';
-import { renderTraceContent } from '../trace.js';
-import { resolveTenantId } from '../tenant.js';
-import { appendAuditEvent, reportAuditWriteFailure } from '../audit.js';
-import { commonDerivationScope } from '../recall-scope.js';
-import { log } from '../log.js';
+import { rejectionDigest } from '../store/rejection.js';
+import { sampleForReplay } from './replay.js';
+import { renderTraceContent } from './trace.js';
+import { resolveTenantId } from '../store/tenant.js';
+import { reportAuditWriteFailure } from '../store/audit.js';
+import { commonDerivationScope } from '../store/recall-scope.js';
+import { log } from '../util/log.js';
 import { REPLAY_COUNT_DEFAULT } from './run.js';
-import { isJsonString } from '../json.js';
-// -------------------------------------------------------------------------
-// 1.4. Auto-promote complete sessions to traces
-// -------------------------------------------------------------------------
-//
-// For each session within the configured window that has a `session_complete`
-// event and no existing trace (idempotency via the source_session_id column),
-// render the action sequence as markdown and persist a Layer.Trace memory.
-// Traces inherit decay, search, replay, and physics from the base MemoryEntry.
+import { isJsonString } from '../util/json.js';
+import { DAY_MS } from '../util/time.js';
+// 1.4. Auto-promote complete sessions to traces: each session in the window with a `session_complete` event and no trace (idempotent via source_session_id)
+// is rendered as markdown and persisted as a Layer.Trace memory, which inherits decay, search, replay and physics.
 export function promoteSessionTraces(run) {
     const { result } = run;
     if (run.dryRun || run.config.autoTraceCapture === false)
         return;
     let tracesSkippedRejected = 0;
     const windowDays = run.config.autoTraceWindowDays ?? 7;
-    const sinceMs = run.now.getTime() - windowDays * 24 * 60 * 60 * 1000;
+    const sinceMs = run.now.getTime() - windowDays * DAY_MS;
     // Auto-trace runs single-tenant (the env-resolved tenant); consolidating
     // every tenant needs a per-tenant loop layered on top of this.
     const consolidationTenant = resolveTenantId({});
@@ -66,23 +61,13 @@ function sessionTrace(run, consolidationTenant, sessionId) {
         run.result.details.push(`  ⏭  skipped session ${sessionId}: events span mixed scopes`);
         return null;
     }
-    const completeEvent = events.find((e) => e.event_type === 'session_complete');
-    if (!completeEvent)
-        return null; // defence-in-depth; findPromotableSessions filters already.
-    const outcomeRaw = completeEvent.content;
-    if (outcomeRaw !== 'success' && outcomeRaw !== 'failure' && outcomeRaw !== 'partial') {
-        // Malformed terminal event — skip rather than crash the whole sleep.
+    const ending = sessionEnding(events);
+    if (!ending)
         return null;
-    }
-    const outcome = outcomeRaw;
+    const { outcome, summary } = ending;
     const steps = events
         .filter((e) => e.event_type !== 'session_complete')
         .map((e) => ({ action: e.content, observation: '' }));
-    // SAFETY: session event metadata is a free-form Record<string, unknown>
-    // bag; summary is optional and is only trusted once isJsonString below
-    // confirms it is actually a string.
-    const summaryValue = completeEvent.metadata.summary;
-    const summary = isJsonString(summaryValue) ? summaryValue : '(untitled)';
     const trace = createMemory(renderTraceContent({ task: summary, steps, outcome }), {
         layer: Layer.Trace,
         trace_outcome: outcome,
@@ -97,18 +82,32 @@ function sessionTrace(run, consolidationTenant, sessionId) {
     });
     return { trace, outcome };
 }
+/** The outcome and title a session's terminal event carries, or null when it has none or the event is malformed. */
+function sessionEnding(events) {
+    const completeEvent = events.find((e) => e.event_type === 'session_complete');
+    if (!completeEvent)
+        return null; // defence-in-depth; findPromotableSessions filters already.
+    const outcomeRaw = completeEvent.content;
+    if (outcomeRaw !== 'success' && outcomeRaw !== 'failure' && outcomeRaw !== 'partial') {
+        // Malformed terminal event — skip rather than crash the whole sleep.
+        return null;
+    }
+    // SAFETY: session event metadata is a free-form Record<string, unknown>
+    // bag; summary is optional and is only trusted once isJsonString below
+    // confirms it is actually a string.
+    const summaryValue = completeEvent.metadata.summary;
+    const summary = isJsonString(summaryValue) ? summaryValue : '(untitled)';
+    return { outcome: outcomeRaw, summary };
+}
 // traceExistsForSession only sees live rows, so a removed rejected trace would regenerate every
 // sleep; check the tombstone under the entry's own stamped tenantId, never a guessed one.
 function traceRejected(run, trace, sessionId) {
-    const consolidateDb = run.getConsolidateDb();
-    if (!consolidateDb)
-        return false;
     const traceDigest = rejectionDigest(trace.content);
-    const tombstone = findRejectedValue(consolidateDb, trace.tenantId, traceDigest);
+    const tombstone = run.tombstones.find(trace.tenantId, traceDigest);
     if (!tombstone)
         return false;
     try {
-        appendAuditEvent(consolidateDb, {
+        run.tombstones.audit({
             tenantId: trace.tenantId,
             actor: 'sleep',
             op: 'reject_refusal',
@@ -124,23 +123,13 @@ function traceRejected(run, trace, sessionId) {
     }
     return true;
 }
-// -------------------------------------------------------------------------
-// 1.5. Replay pass — rehearse high-value survivors
-// -------------------------------------------------------------------------
-//
-// Biologically-inspired counterpart to hippocampal replay during slow-wave
-// sleep: sample N memories weighted by outcome + valence + under-rehearsal
-// + idle time, then apply the same retrieval-strengthening `markRetrieved`
-// applies to real queries. Distinct from decay (removal), physics (motion),
-// and merge (compression) — this is the "rehearse the important stuff so
-// it doesn't fade" pass.
+// 1.5. Replay pass: rehearse high-value survivors by sampling N memories weighted by outcome, valence, under-rehearsal and idle time,
+// then applying the `markRetrieved` strengthening, so important memories don't fade.
 export function replayPass(run) {
     const { survivors, now } = run;
     const replayCount = run.config.replay?.count ?? REPLAY_COUNT_DEFAULT;
-    // EVAL-ONLY ablation (see ablation.ts): replay rehearsal IS recall
-    // strengthening (same markRetrieved dynamics), so the strengthen-off arm
-    // silences the whole pass - markRetrieved would return unmutated entries
-    // and persisting them anyway would still refresh updated_at / mirrors.
+    // EVAL-ONLY ablation (see ablation.ts): replay rehearsal is recall strengthening, so the strengthen-off arm silences the whole pass;
+    // persisting unmutated entries anyway would still refresh updated_at and mirrors.
     if (!(replayCount > 0 && survivors.length > 0 && !isRecallBoostAblated()))
         return;
     const seed = Math.floor(now.getTime() / 1000) & 0xffffffff;

package/dist/core/ablation.d.ts

@@ -0,0 +1,15 @@
+/** EVAL-ONLY ablation switches (HIPPO_ABLATE_*, HIPPO_EVAL_RECENCY_DAYS, HIPPO_FAKE_NOW): each cuts ONE mechanism (outcome also replayPriority bias).
+ * Not a production surface. Env is read once per process; tests that mutate these vars MUST call _resetAblationCacheForTests() in beforeEach AND afterEach. See
+ * docs/ARCHITECTURE.md#srccoreablationts. */
+export declare function isDecayAblated(): boolean;
+export declare function isRecallBoostAblated(): boolean;
+export declare function isOutcomeSlowAblated(): boolean;
+export declare function isOutcomeFastAblated(): boolean;
+export declare function isRecencyAblated(): boolean;
+/** HIPPO_EVAL_RECENCY_DAYS when it is a positive number, else null (callers keep their default). */
+export declare function evalRecencyScaleDays(): number | null;
+/** The default `now` for lifecycle computations: HIPPO_FAKE_NOW when set and parseable, else the real clock; an explicit `now` parameter always wins. */
+export declare function evalNow(): Date;
+/** Test-only. See module JSDoc: call in BOTH beforeEach AND afterEach. */
+export declare function _resetAblationCacheForTests(): void;
+//# sourceMappingURL=ablation.d.ts.map

package/dist/core/ablation.js

@@ -0,0 +1,49 @@
+/** EVAL-ONLY ablation switches (HIPPO_ABLATE_*, HIPPO_EVAL_RECENCY_DAYS, HIPPO_FAKE_NOW): each cuts ONE mechanism (outcome also replayPriority bias).
+ * Not a production surface. Env is read once per process; tests that mutate these vars MUST call _resetAblationCacheForTests() in beforeEach AND afterEach. See
+ * docs/ARCHITECTURE.md#srccoreablationts. */
+import { envAblateDecay, envAblateOutcome, envAblateOutcomeFast, envAblateOutcomeSlow, envAblateRecallBoost, envAblateRecency, envEvalRecencyDays, envFakeNowMs, } from '../util/env.js';
+let _cache;
+function readFlags() {
+    if (_cache !== undefined)
+        return _cache;
+    const outcomeBoth = envAblateOutcome();
+    _cache = {
+        decay: envAblateDecay(),
+        recallBoost: envAblateRecallBoost(),
+        outcomeSlow: outcomeBoth || envAblateOutcomeSlow(),
+        outcomeFast: outcomeBoth || envAblateOutcomeFast(),
+        recency: envAblateRecency(),
+        recencyDays: envEvalRecencyDays(),
+        fakeNowMs: envFakeNowMs(),
+    };
+    return _cache;
+}
+export function isDecayAblated() {
+    return readFlags().decay;
+}
+export function isRecallBoostAblated() {
+    return readFlags().recallBoost;
+}
+export function isOutcomeSlowAblated() {
+    return readFlags().outcomeSlow;
+}
+export function isOutcomeFastAblated() {
+    return readFlags().outcomeFast;
+}
+export function isRecencyAblated() {
+    return readFlags().recency;
+}
+/** HIPPO_EVAL_RECENCY_DAYS when it is a positive number, else null (callers keep their default). */
+export function evalRecencyScaleDays() {
+    return readFlags().recencyDays;
+}
+/** The default `now` for lifecycle computations: HIPPO_FAKE_NOW when set and parseable, else the real clock; an explicit `now` parameter always wins. */
+export function evalNow() {
+    const ms = readFlags().fakeNowMs;
+    return ms === null ? new Date() : new Date(ms);
+}
+/** Test-only. See module JSDoc: call in BOTH beforeEach AND afterEach. */
+export function _resetAblationCacheForTests() {
+    _cache = undefined;
+}
+//# sourceMappingURL=ablation.js.map

package/dist/{agent-memories/tools.d.ts → core/agent-memory-tools.d.ts}

@@ -30,4 +30,4 @@ export declare const AGENT_MEMORY_SOURCE_PREFIX = "agent-memory:";
 export declare function toolSourcePrefix(id: ToolId): string;
 export declare const AGENT_MEMORY_TAGS: readonly string[];
 export declare function isToolId(value: string): value is ToolId;
-//# sourceMappingURL=tools.d.ts.map
+//# sourceMappingURL=agent-memory-tools.d.ts.map

package/dist/{agent-memories/tools.js → core/agent-memory-tools.js}

@@ -16,4 +16,4 @@ export const AGENT_MEMORY_TAGS = AGENT_MEMORY_TOOLS.map((t) => t.tag);
 export function isToolId(value) {
     return AGENT_MEMORY_TOOLS.some((t) => t.id === value);
 }
-//# sourceMappingURL=tools.js.map
+//# sourceMappingURL=agent-memory-tools.js.map

package/dist/{ambient.d.ts → core/ambient.d.ts}

@@ -1,11 +1,4 @@
-/**
- * Ambient state vector — a compact representation of the agent's memory
- * landscape, computed in O(N) from the current corpus.
- *
- * Inspired by the biological ambient neural state: a continuous background
- * representation that tells the agent "where it is" in knowledge-space
- * without retrieving specific memories.
- */
+/** Ambient state vector: a compact O(N) summary of the corpus telling the agent "where it is" in knowledge-space without retrieving specific memories. */
 import type { MemoryEntry } from './memory.js';
 export interface AmbientState {
     tagEntropy: number;

package/dist/{ambient.js → core/ambient.js}

@@ -1,14 +1,9 @@
-/**
- * Ambient state vector — a compact representation of the agent's memory
- * landscape, computed in O(N) from the current corpus.
- *
- * Inspired by the biological ambient neural state: a continuous background
- * representation that tells the agent "where it is" in knowledge-space
- * without retrieving specific memories.
- */
+/** Ambient state vector: a compact O(N) summary of the corpus telling the agent "where it is" in knowledge-space without retrieving specific memories. */
 import { evalNow } from './ablation.js';
 import { Layer } from './memory.js';
 import { calculateStrength } from './memory.js';
+import { DAY_MS } from '../util/time.js';
+const STATE_DECIMALS = 3;
 /** The tallies of two disjoint row sets taken together. */
 export function addAmbientTallies(a, b) {
     const tagCounts = new Map(a.tagCounts);
@@ -36,7 +31,7 @@ export function isErrorTagged(tags) {
 /** Tallies over loaded entries; superseded rows count toward the total only, as they always have here. */
 export function tallyAmbientEntries(entries, now) {
     const currentTime = now ?? evalNow(); // honors HIPPO_FAKE_NOW (eval-only)
-    const sevenDaysAgo = currentTime.getTime() - 7 * 86400000;
+    const sevenDaysAgo = currentTime.getTime() - 7 * DAY_MS;
     const t = {
         total: entries.length, strengthSum: 0, fresh: 0, negative: 0, highSchemaFit: 0, errors: 0,
         semantic: 0, episodic: 0, conflicts: 0, extracted: 0, maxDagLevel: 0, tagCounts: new Map(),
@@ -154,15 +149,15 @@ export function renderAmbientSummary(state) {
 export function formatAmbientVector(state) {
     const lines = [];
     lines.push('Ambient State Vector:');
-    lines.push(`  tag_entropy:          ${state.tagEntropy.toFixed(3)}`);
-    lines.push(`  avg_strength:         ${state.avgStrength.toFixed(3)}`);
-    lines.push(`  recency_freshness:    ${state.recencyFreshness.toFixed(3)}`);
-    lines.push(`  emotional_skew:       ${state.emotionalSkew.toFixed(3)}`);
-    lines.push(`  schema_fit_ratio:     ${state.schemaFitRatio.toFixed(3)}`);
-    lines.push(`  error_density:        ${state.errorDensity.toFixed(3)}`);
-    lines.push(`  consolidation_ratio:  ${state.consolidationRatio.toFixed(3)}`);
-    lines.push(`  conflict_intensity:   ${state.conflictIntensity.toFixed(3)}`);
-    lines.push(`  extraction_coverage:  ${state.extractionCoverage.toFixed(3)}`);
+    lines.push(`  tag_entropy:          ${state.tagEntropy.toFixed(STATE_DECIMALS)}`);
+    lines.push(`  avg_strength:         ${state.avgStrength.toFixed(STATE_DECIMALS)}`);
+    lines.push(`  recency_freshness:    ${state.recencyFreshness.toFixed(STATE_DECIMALS)}`);
+    lines.push(`  emotional_skew:       ${state.emotionalSkew.toFixed(STATE_DECIMALS)}`);
+    lines.push(`  schema_fit_ratio:     ${state.schemaFitRatio.toFixed(STATE_DECIMALS)}`);
+    lines.push(`  error_density:        ${state.errorDensity.toFixed(STATE_DECIMALS)}`);
+    lines.push(`  consolidation_ratio:  ${state.consolidationRatio.toFixed(STATE_DECIMALS)}`);
+    lines.push(`  conflict_intensity:   ${state.conflictIntensity.toFixed(STATE_DECIMALS)}`);
+    lines.push(`  extraction_coverage:  ${state.extractionCoverage.toFixed(STATE_DECIMALS)}`);
     lines.push(`  dag_depth:            ${state.dagDepth}`);
     lines.push(`  total_memories:       ${state.totalMemories}`);
     return lines.join('\n');

package/dist/{capture-contract.d.ts → core/capture-contract.d.ts}

@@ -13,13 +13,20 @@ export interface CaptureInput {
     readonly trigger: string | null;
 }
 /** The outcome of reading a payload: usable input, a payload hippo refuses, or no payload at all. */
-export type CaptureReceipt = {
+export type CaptureReceipt<I extends CaptureInput = CaptureInput> = {
     readonly status: 'received';
-    readonly input: CaptureInput;
+    readonly input: I;
 } | {
     readonly status: 'skipped' | 'unavailable';
     readonly reason: string;
 };
+/** What a PostCompact payload adds: it always names a session, and carries the summary Claude Code wrote. */
+export interface PostCompactInput extends CaptureInput {
+    readonly event: 'post-compact';
+    readonly sessionId: string;
+    /** null when Claude Code sent none; the transcript fills the record later. */
+    readonly compactSummary: string | null;
+}
 /** Working state saved before the host drops context, so the session can resume; it is not a lesson. */
 export interface Checkpoint {
     readonly runtime: string;
@@ -44,8 +51,14 @@ export declare function isStringValue<T>(value: T): value is T & string;
 export declare function isObjectLike<T>(value: T): value is T & object;
 /** The hook runtimes a `--runtime` flag names; absent means Claude Code. */
 export type HookRuntime = 'claude-code' | 'copilot';
-/** Reads a Claude Code PreCompact payload, or a Copilot one after stdin.ts mapped it to the same snake_case keys; only an empty stdin counts as a manual run. */
+/** Reads a Claude Code PreCompact payload, or a Copilot one after stdin.ts mapped
+ * it to the same snake_case keys; only an empty stdin counts as a manual run. */
 export declare function readClaudeCodePreCompact(stdinText: string | undefined, timedOut: boolean, runtime?: HookRuntime): CaptureReceipt;
 /** Reads VS Code's per-reply Stop payload. Pass the raw stdin: stdin.ts would give a Copilot CLI agentStop the same snake_case keys. */
 export declare function readVscodeStop(stdinText: string | undefined, timedOut: boolean): CaptureReceipt;
+/** Reads a Claude Code PostCompact payload; it must name a session, but needs no transcript_path. */
+export declare function readClaudeCodePostCompact(stdinText: string | undefined, timedOut: boolean): CaptureReceipt<PostCompactInput>;
+/** Reads a Claude Code SessionEnd payload, or a Copilot one after stdin.ts mapped
+ * it to the same snake_case keys; only an empty stdin counts as a manual run. */
+export declare function readSessionEnd(stdinText: string | undefined, timedOut: boolean, runtime?: HookRuntime): CaptureReceipt;
 //# sourceMappingURL=capture-contract.d.ts.map

package/dist/{capture-contract.js → core/capture-contract.js}

@@ -8,7 +8,8 @@ export function isStringValue(value) {
 export function isObjectLike(value) {
     return value !== null && value instanceof Object;
 }
-/** Reads a Claude Code PreCompact payload, or a Copilot one after stdin.ts mapped it to the same snake_case keys; only an empty stdin counts as a manual run. */
+/** Reads a Claude Code PreCompact payload, or a Copilot one after stdin.ts mapped
+ * it to the same snake_case keys; only an empty stdin counts as a manual run. */
 export function readClaudeCodePreCompact(stdinText, timedOut, runtime = 'claude-code') {
     const empty = !stdinText || stdinText.trim() === '';
     if (timedOut && empty) {
@@ -82,4 +83,69 @@ export function readVscodeStop(stdinText, timedOut) {
         },
     };
 }
+/** Reads a Claude Code PostCompact payload; it must name a session, but needs no transcript_path. */
+export function readClaudeCodePostCompact(stdinText, timedOut) {
+    const empty = !stdinText || stdinText.trim() === '';
+    if (timedOut && empty) {
+        return { status: 'unavailable', reason: 'no PostCompact payload arrived before the stdin wait window closed' };
+    }
+    let payload;
+    try {
+        payload = empty ? undefined : JSON.parse(stdinText.trim());
+    }
+    catch {
+        // Non-JSON stdin leaves payload undefined, which the shape check rejects.
+    }
+    if (!isObjectLike(payload) || !('session_id' in payload) || !isStringValue(payload.session_id) || payload.session_id === '') {
+        return { status: 'skipped', reason: 'no PostCompact payload naming a session' };
+    }
+    return {
+        status: 'received',
+        input: {
+            runtime: 'claude-code',
+            event: 'post-compact',
+            manual: false,
+            sessionId: payload.session_id,
+            cwd: 'cwd' in payload && isStringValue(payload.cwd) ? payload.cwd : null,
+            transcriptPath: 'transcript_path' in payload && isStringValue(payload.transcript_path) ? payload.transcript_path : null,
+            trigger: 'trigger' in payload && isStringValue(payload.trigger) ? payload.trigger : null,
+            compactSummary: 'compact_summary' in payload && isStringValue(payload.compact_summary) ? payload.compact_summary : null,
+        },
+    };
+}
+/** Reads a Claude Code SessionEnd payload, or a Copilot one after stdin.ts mapped
+ * it to the same snake_case keys; only an empty stdin counts as a manual run. */
+export function readSessionEnd(stdinText, timedOut, runtime = 'claude-code') {
+    const empty = !stdinText || stdinText.trim() === '';
+    if (timedOut && empty) {
+        return { status: 'unavailable', reason: 'no SessionEnd payload arrived before the stdin wait window closed' };
+    }
+    const base = { runtime, event: 'session-end' };
+    if (empty) {
+        return { status: 'received', input: { ...base, manual: true, sessionId: null, cwd: null, transcriptPath: null, trigger: null } };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(stdinText.trim());
+    }
+    catch {
+        // Non-JSON stdin leaves payload undefined, which the shape check rejects.
+    }
+    // Explicit array check: this reader has no required key to reject an array for it.
+    if (!isObjectLike(payload) || Array.isArray(payload)) {
+        return { status: 'skipped', reason: 'malformed SessionEnd payload (not a JSON object)' };
+    }
+    return {
+        status: 'received',
+        input: {
+            ...base,
+            manual: false,
+            sessionId: 'session_id' in payload && isStringValue(payload.session_id) && payload.session_id !== '' ? payload.session_id : null,
+            cwd: 'cwd' in payload && isStringValue(payload.cwd) ? payload.cwd : null,
+            transcriptPath: 'transcript_path' in payload && isStringValue(payload.transcript_path) && payload.transcript_path !== '' ? payload.transcript_path : null,
+            // Both hosts name a session end's trigger `reason`.
+            trigger: 'reason' in payload && isStringValue(payload.reason) ? payload.reason : null,
+        },
+    };
+}
 //# sourceMappingURL=capture-contract.js.map

package/dist/{card.d.ts → core/card.d.ts}

@@ -2,7 +2,8 @@
 export type CardStatus = 'backlog' | 'ready' | 'running' | 'blocked' | 'review' | 'done' | 'shelved';
 /** Narrows a raw string, such as a CLI flag value, to a CardStatus. */
 export declare function isCardStatus(v: string): v is CardStatus;
-/** A card row; leaseUntil and heartbeatAt are null unless the card is running, and a card claimed under 1.40.0 runs with both null until a heartbeat sets them. */
+/** A card row; leaseUntil and heartbeatAt are null unless the card is running, and
+ * a card claimed under 1.40.0 runs with both null until a heartbeat sets them. */
 export interface Card {
     id: string;
     title: string;
@@ -44,4 +45,6 @@ export type CardTransitions = {
 export declare const CARD_TRANSITIONS: CardTransitions;
 /** How long a claim or a heartbeat keeps a running card's lease before reclaimExpiredCards may return it to ready. */
 export declare const CARD_LEASE_MS: number;
+/** Throws on any move CARD_TRANSITIONS does not allow, before a status write touches the row. */
+export declare function assertCardTransition(from: readonly CardStatus[], to: CardStatus): void;
 //# sourceMappingURL=card.d.ts.map

package/dist/{card.js → core/card.js}

@@ -16,4 +16,12 @@ export const CARD_TRANSITIONS = {
 // SHORTCUT: one fixed lease for every claim; add a per-claim lease when the W3 dispatcher heartbeats on a timer.
 /** How long a claim or a heartbeat keeps a running card's lease before reclaimExpiredCards may return it to ready. */
 export const CARD_LEASE_MS = 4 * 60 * 60 * 1000;
+/** Throws on any move CARD_TRANSITIONS does not allow, before a status write touches the row. */
+export function assertCardTransition(from, to) {
+    for (const status of from) {
+        if (!CARD_TRANSITIONS[status].includes(to)) {
+            throw new Error(`illegal card transition: ${status} -> ${to}`);
+        }
+    }
+}
 //# sourceMappingURL=card.js.map

package/dist/core/compare.d.ts

@@ -0,0 +1,32 @@
+/** Deterministic tie-break comparators for recall ranking. A true LEAF module: it imports from no sort-site module (search, physics, api, cli, goals,
+ * graph-recall, multihop, rerankers), taking structural param types instead, because even a type-only import back would recreate the search <-> physics ESM
+ * cycle this module exists to avoid. */
+/** Minimal shape for a deterministic tie-break across fresh ingests into different stores;
+ *  the metadata keys are optional so `{ content, id }` callers still fit. */
+export interface EntryIdentity {
+    content: string;
+    id: string;
+    layer?: string;
+    tags?: readonly string[];
+    source?: string;
+}
+/** Order: content, layer rank (semantic first, keeping the promotion), tag count desc, sorted tags, source, id; plain `<`/`>`, never `localeCompare`.
+ * `content` is the cross-ingest-stable key; `id` is random per instance, so it is only the terminal key. Metadata keys are computed only on a content tie. */
+export declare function compareEntryIdentity(a: EntryIdentity, b: EntryIdentity): number;
+/** Minimal shape for score-primary sort sites (SearchResult and friends
+ *  that carry `{ score, entry: { content, id } }`). */
+export interface ScoredEntryLike {
+    score: number;
+    entry: EntryIdentity;
+}
+/** score descending, then `compareEntryIdentity`: the shared ordering for every score-primary recall sort site, which delegate here (via an arrow when the
+ * score field is not named `score`) so the tiebreak cannot drift between call sites. */
+export declare function compareScoredResults(a: ScoredEntryLike, b: ScoredEntryLike): number;
+/** Larger first, NaN after every number, 0 for equal scores. Not a subtraction: two infinities, or any NaN, subtract to NaN, which a sort reads as a tie. */
+export declare function compareScoresDesc(a: number, b: number): number;
+/** Score-desc then tie-key comparator for the physics layer (no `entry`/`content` in scope): the default memoryId key is per-instance determinism only.
+ * Cross-ingest stability needs `tieKeyOf` (content), since the baseScore tie order picks the cluster_top_k set. A factory, as two fields sort in turn. */
+export declare function comparePhysicsResultsBy<T extends {
+    memoryId: string;
+}>(scoreOf: (r: T) => number, tieKeyOf?: (r: T) => string): (a: T, b: T) => number;
+//# sourceMappingURL=compare.d.ts.map

package/dist/core/compare.js

@@ -0,0 +1,70 @@
+/** Deterministic tie-break comparators for recall ranking. A true LEAF module: it imports from no sort-site module (search, physics, api, cli, goals,
+ * graph-recall, multihop, rerankers), taking structural param types instead, because even a type-only import back would recreate the search <-> physics ESM
+ * cycle this module exists to avoid. */
+/** Order: content, layer rank (semantic first, keeping the promotion), tag count desc, sorted tags, source, id; plain `<`/`>`, never `localeCompare`.
+ * `content` is the cross-ingest-stable key; `id` is random per instance, so it is only the terminal key. Metadata keys are computed only on a content tie. */
+export function compareEntryIdentity(a, b) {
+    return (compareStrings(a.content, b.content) ||
+        layerRank(a.layer) - layerRank(b.layer) ||
+        compareStrings(a.layer ?? '', b.layer ?? '') ||
+        compareTags(a.tags, b.tags) ||
+        compareStrings(a.source ?? '', b.source ?? '') ||
+        compareStrings(a.id, b.id));
+}
+const LAYER_RANK = new Map([
+    ['semantic', 0],
+    ['episodic', 1],
+    ['trace', 2],
+    ['buffer', 3],
+]);
+function layerRank(layer) {
+    return LAYER_RANK.get(layer ?? '') ?? LAYER_RANK.size;
+}
+function compareStrings(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function compareTags(a, b) {
+    const ua = [...new Set(a ?? [])].sort();
+    const ub = [...new Set(b ?? [])].sort();
+    if (ua.length !== ub.length)
+        return ub.length - ua.length;
+    // element-wise, not a joined string: a separator inside a tag would collide
+    for (let i = 0; i < ua.length; i++) {
+        const c = compareStrings(ua[i], ub[i]);
+        if (c !== 0)
+            return c;
+    }
+    return 0;
+}
+/** score descending, then `compareEntryIdentity`: the shared ordering for every score-primary recall sort site, which delegate here (via an arrow when the
+ * score field is not named `score`) so the tiebreak cannot drift between call sites. */
+export function compareScoredResults(a, b) {
+    return compareScoresDesc(a.score, b.score) || compareEntryIdentity(a.entry, b.entry);
+}
+/** Larger first, NaN after every number, 0 for equal scores. Not a subtraction: two infinities, or any NaN, subtract to NaN, which a sort reads as a tie. */
+export function compareScoresDesc(a, b) {
+    if (a > b)
+        return -1;
+    if (a < b)
+        return 1;
+    return Number(Number.isNaN(a)) - Number(Number.isNaN(b));
+}
+/** Score-desc then tie-key comparator for the physics layer (no `entry`/`content` in scope): the default memoryId key is per-instance determinism only.
+ * Cross-ingest stability needs `tieKeyOf` (content), since the baseScore tie order picks the cluster_top_k set. A factory, as two fields sort in turn. */
+export function comparePhysicsResultsBy(scoreOf, tieKeyOf) {
+    return (a, b) => {
+        const d = compareScoresDesc(scoreOf(a), scoreOf(b));
+        if (d !== 0)
+            return d;
+        const ai = tieKeyOf ? tieKeyOf(a) : a.memoryId;
+        const bi = tieKeyOf ? tieKeyOf(b) : b.memoryId;
+        if (ai < bi)
+            return -1;
+        if (ai > bi)
+            return 1;
+        // Tie-key collision (e.g. duplicate content): fall through to memoryId
+        // so the comparator still yields a total order within one store.
+        return a.memoryId < b.memoryId ? -1 : a.memoryId > b.memoryId ? 1 : 0;
+    };
+}
+//# sourceMappingURL=compare.js.map