Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
import { sha256Hex } from "../integrity/digest.ts";
import {
ANSWER_QUOTE_VERDICT,
isAnswerQuoteVerdict,
mergeAnswerQuoteVerdicts,
} from "./answer-quotes/check.ts";
import { isContextReceiptTrigger, type ContextReceiptTrigger } from "./context-receipt-trigger.ts";
import {
appendContinuityRecord,
isCanonicalUtcTimestamp,
listContinuityRecords,
} from "./continuity/store.ts";
import { CONTINUITY_SESSION_ID_KEY, type ContinuityRecord } from "./continuity/types.ts";
import type { RecallAdequacyVerdict } from "./recall-adequacy.ts";
import type { ReachView } from "./reach-view.ts";
// The trigger vocabulary lives in `context-receipt-trigger.ts`, a leaf
// module, and is re-exported here so this module's export surface is
// unchanged; defining it here too would close an import cycle through the
// verify kernel and the doctor registry.
export type { ContextReceiptTrigger } from "./context-receipt-trigger.ts";
export interface ContextReceiptOptions {
readonly host: string;
readonly trigger: ContextReceiptTrigger;
readonly createdAt?: string;
readonly sessionId?: string;
readonly turnId?: string;
}
export interface ContextReceiptItemInput {
readonly id: string;
readonly path?: string;
readonly text?: string;
readonly tokens?: number;
/**
* UTF-8 byte size of the item. Tokens are an estimate derived from
* bytes; recording both keeps the estimate auditable against the exact
* measurement it came from. Optional, so a caller that has no byte
* figure records exactly what it knows.
*/
readonly bytes?: number;
readonly tier?: string;
readonly trimmed?: boolean;
readonly safetyFiltered?: boolean;
/** Epistemic grounding of the item (ACM): observed | derived | ... */
readonly epistemic?: string;
/** `evidenced_by` wikilinks grounding the item. */
readonly evidenceRefs?: ReadonlyArray<string>;
/**
* The id of the first copy when the dedup transform replaced this
* item's delivered body with the shared omission sentence (additive,
* forward-compatible): the one fact the verify kernel needs to
* re-derive the delivered bytes, which are synthetic and not a
* projection of the page at all.
*/
readonly dedupedFrom?: string;
}
export interface EmitContextReceiptInput {
readonly options: ContextReceiptOptions;
readonly items: ReadonlyArray<ContextReceiptItemInput>;
readonly finalText: string;
readonly budget?: Readonly<Record<string, unknown>>;
readonly extra?: Readonly<Record<string, unknown>>;
/**
* Recall adequacy verdict (t_b8f66fec) for the recall that produced
* this context. When present it is persisted so the audit trail records
* whether the surfaced grounding was judged sufficient / weak /
* insufficient and what action the caller was told to take.
*/
readonly adequacy?: RecallAdequacyVerdict;
/**
* The advisory decision-model annotation of that verdict (issue #213,
* Part 8), stored next to it as `decision_answerable`. Numbers only.
*/
readonly decisionAnswerable?: { readonly probability: number; readonly disagrees: boolean };
}
/** Flatten a verdict into the snake_cased receipt payload shape. */
export function serializeAdequacy(verdict: RecallAdequacyVerdict): Record<string, unknown> {
return {
level: verdict.level,
action: verdict.action,
escalate: verdict.escalate,
result_count: verdict.resultCount,
top_score: verdict.topScore,
mean_score: verdict.meanScore,
reason: verdict.reason,
};
}
export interface ContextReceiptFilter {
readonly trigger?: ContextReceiptTrigger;
readonly host?: string;
readonly sessionId?: string;
/**
* Exact receipt id (answer-trust, task B3): the one-record lookup the
* claim-provenance join uses to resolve a claim's `sample_id` to the
* receipt it names. Matched BEFORE the limit, like every other filter
* field, so a receipt lookup answers the store's answer for that id
* and never whichever receipts happen to be newest.
*/
readonly receiptId?: string;
readonly limit?: number;
/**
* Receipts the caller may not see at all. They are left out before the
* limit is applied, so the answer is the one a store without them gives.
*/
readonly exclude?: (record: ContinuityRecord) => boolean;
}
export interface ContextReceiptSummary {
readonly id: string;
readonly created_at: string;
readonly trigger: ContextReceiptTrigger | null;
readonly host: string | null;
readonly session_id?: string;
readonly turn_id?: string;
readonly item_count: number | null;
readonly source_count: number;
readonly private: boolean;
readonly redacted: boolean;
/** Recall adequacy verdict summary, when the receipt recorded one. */
readonly adequacy?: {
readonly level: string;
readonly action: string;
readonly escalate: boolean;
};
/**
* The receipt's session reply-presence join (t_f8510c55), present ONLY
* when the caller handed a {@link lookupReceiptReplyPresence} result in.
* List summaries stay summaries and omit it; a show path passes the
* lookup in, and the member then names either the joined per-note
* verdicts or the unjoined outcome - never a silent absence.
*/
readonly reply_presence?: ReceiptReplyPresenceJoin;
}
export function emitContextReceipt(
vault: string,
input: EmitContextReceiptInput,
): ContinuityRecord {
const createdAt = input.options.createdAt ?? new Date().toISOString();
const itemPayloads = input.items.map((item, index) => ({
id: item.id,
original_rank: index + 1,
...(item.path ? { path: item.path } : {}),
...(item.tokens !== undefined ? { tokens: item.tokens } : {}),
...(item.bytes !== undefined ? { bytes: item.bytes } : {}),
...(item.tier ? { tier: item.tier } : {}),
...(item.trimmed !== undefined ? { trimmed: item.trimmed } : {}),
...(item.safetyFiltered !== undefined ? { safety_filtered: item.safetyFiltered } : {}),
...(item.epistemic !== undefined ? { epistemic: item.epistemic } : {}),
...(item.evidenceRefs && item.evidenceRefs.length > 0
? { evidence_refs: [...item.evidenceRefs] }
: {}),
...(item.text ? { text_hash: sha256Hex(item.text) } : {}),
...(item.dedupedFrom !== undefined ? { deduped_from: item.dedupedFrom } : {}),
}));
const payload: Record<string, unknown> = {
host: input.options.host,
trigger: input.options.trigger,
...(input.options.sessionId ? { session_id: input.options.sessionId } : {}),
...(input.options.turnId ? { turn_id: input.options.turnId } : {}),
item_count: input.items.length,
final_text_hash: sha256Hex(input.finalText),
final_text_chars: [...input.finalText].length,
items: itemPayloads,
...(input.budget ? { budget: input.budget } : {}),
...(input.adequacy ? { adequacy: serializeAdequacy(input.adequacy) } : {}),
...(input.adequacy && input.decisionAnswerable
? {
decision_answerable: {
probability: input.decisionAnswerable.probability,
disagrees: input.decisionAnswerable.disagrees,
},
}
: {}),
};
mergeReceiptExtra(payload, input.extra);
return appendContinuityRecord(vault, {
kind: "context_receipt",
createdAt,
sourceRefs: input.items.map((item) => ({
id: item.id,
...(item.path ? { path: item.path } : {}),
...(item.text ? { hash: sha256Hex(item.text) } : {}),
})),
payload,
});
}
function mergeReceiptExtra(
payload: Record<string, unknown>,
extra: Readonly<Record<string, unknown>> | undefined,
): void {
if (!extra) return;
for (const [key, value] of Object.entries(extra)) {
if (Object.hasOwn(payload, key)) {
throw new Error(`context receipt extra key collides with payload field: ${key}`);
}
payload[key] = value;
}
}
export function listContextReceipts(
vault: string,
filter: ContextReceiptFilter = {},
): ReadonlyArray<ContinuityRecord> {
let receipts = listContinuityRecords(vault, {
kind: "context_receipt",
}).filter((record) => matchesReceiptFilter(record, filter));
receipts = receipts.toReversed();
if (filter.limit !== undefined)
receipts = receipts.slice(0, Math.max(0, Math.floor(filter.limit)));
return Object.freeze(receipts);
}
// ----- session-scoped fold (context-integrity-gates, Unit I) --------------
/**
* Default ceiling on how many receipts one fold AGGREGATES.
*
* It is a fold bound, not a scan bound, and the docblock said otherwise
* for exactly as long as nobody measured it. Every receipt matching the
* window is read into memory first and the bound is applied afterwards,
* so the read cost is set by `since` / `until` (which do skip whole
* month shards) and by nothing else. Two consequences worth stating:
* lowering `maxReceipts` makes the REPORT smaller, never the read; and
* the observed-use join the MCP surface performs alongside this fold
* walks the same window again through `observedReuseRates`.
*
* A real scan bound was considered and rejected. It would mean reading
* shards newest-first with an early exit, which changes
* `listContinuityRecords` for every caller and changes what `truncated`
* asserts - from "more receipts matched than were folded" to "the read
* stopped early", which cannot report a total at all. The bound that
* exists is honest about what it does: exceeding it is REPORTED
* (`truncated`) rather than silently returning a prefix as if it were
* the complete answer.
*/
export const CONTEXT_RECEIPT_FOLD_MAX_RECEIPTS = 500;
export interface ContextReceiptFoldFilter {
readonly trigger?: ContextReceiptTrigger;
readonly host?: string;
readonly sessionId?: string;
/** Inclusive lower bound on `createdAt` (canonical UTC ISO-8601). */
readonly since?: string;
/** Inclusive upper bound on `createdAt` (canonical UTC ISO-8601). */
readonly until?: string;
/** Fold bound; defaults to {@link CONTEXT_RECEIPT_FOLD_MAX_RECEIPTS}. */
readonly maxReceipts?: number;
/**
* Receipts the caller may not see at all. They are left out before the
* fold bound is applied, so neither `receipt_count` nor `truncated`
* counts them.
*/
readonly exclude?: (record: ContinuityRecord) => boolean;
/**
* Receipt items the caller may not see. They leave the item figures,
* and a receipt they leave with no item counts in `empty_receipts`, as
* a receipt that never carried them would.
*/
readonly excludeItem?: (item: unknown) => boolean;
}
/**
* A window bound was not a canonical UTC timestamp.
*
* `since` and `until` are compared LEXICALLY against stored `createdAt`
* strings, which is correct for the canonical form and meaningless for
* anything else: `"yesterday"` sorts after every `2026-…` timestamp, so
* it filters the window down to nothing and the fold reports "no
* receipts recorded for this filter". Reporting "nothing happened" for
* malformed input is precisely the failure this wave exists to remove,
* so a bound that cannot mean what it says is refused instead.
*/
export class ContextReceiptWindowError extends Error {
/** `since` or `until`. */
readonly field: string;
constructor(field: string, value: string) {
super(
`context receipt window: ${field} must be a canonical UTC ISO-8601 timestamp ` +
`(YYYY-MM-DDTHH:MM:SS[.sss]Z with a real calendar date), got ${JSON.stringify(value)}`,
);
this.name = "ContextReceiptWindowError";
this.field = field;
}
}
/** Throw {@link ContextReceiptWindowError} unless `value` can be compared. */
export function assertContextReceiptWindowBound(field: string, value: string | undefined): void {
if (value === undefined) return;
if (!isCanonicalUtcTimestamp(value)) throw new ContextReceiptWindowError(field, value);
}
/** One artifact's injection history across the folded receipts. */
export interface ContextReceiptItemUsage {
readonly id: string;
/** Vault-relative path, when the receipts recorded one. */
readonly path?: string;
/** How many of the folded receipts injected this artifact. */
readonly injections: number;
/** Summed recorded token cost across those injections. */
readonly tokens: number;
}
/**
* The filtered window held no receipts at all.
*
* This is a DIFFERENT statement from "every counter is zero", and the
* difference is the point: receipt emission is opt-in, so a vault where
* nobody asked for receipts has recorded nothing, and reporting counts
* of zero would present the absence of a mechanism as a finding about
* retrieval. The shape carries no counters, so a consumer cannot read
* one without first branching on `recorded`.
*/
export interface ContextReceiptFoldEmpty {
readonly recorded: false;
readonly max_receipts: number;
}
/** The fold over a non-empty window. */
export interface ContextReceiptFoldResult {
readonly recorded: true;
/** Receipts folded, including any withheld from item aggregation. */
readonly receipt_count: number;
/** Total item occurrences across the aggregated receipts. */
readonly item_total: number;
/** Distinct artifacts behind those occurrences. */
readonly distinct_items: number;
/** Per-artifact frequency and token cost, most-injected first. */
readonly items: ReadonlyArray<ContextReceiptItemUsage>;
/**
* Receipts the redactor flagged private or redacted. They are counted
* but never unfolded, so redacted content cannot re-enter the vault
* through an aggregate. The three item figures above describe the
* remaining receipts only.
*/
readonly withheld_receipts: number;
/**
* Folded receipts that recorded an EMPTY item array.
*
* A real and expected shape, not a defect: the SessionStart meter
* writes `items: []` whenever the injection loader degraded to its
* last-good cache, because the sub-bodies it would have attributed
* were never emitted. They inflate `receipt_count` while contributing
* nothing to the item figures, so they are counted here rather than
* disappearing into the difference between two other numbers.
*/
readonly empty_receipts: number;
/**
* Folded receipts whose `items` field is absent or not an array. A
* receipt that cannot be unfolded at all - distinct from one that
* deliberately carried nothing.
*/
readonly malformed_receipts: number;
/** True when the fold bound cut the input; the figures are a prefix. */
readonly truncated: boolean;
readonly max_receipts: number;
}
export type ContextReceiptFold = ContextReceiptFoldEmpty | ContextReceiptFoldResult;
/**
* Join `context_receipt` records across a window into one retrieval
* picture: how many injections happened, how many distinct artifacts
* they carried, and how often and how expensively each one was injected.
*
* Read-only. Every field folded here was already durable on the record;
* what did not exist was the join - `listContextReceipts` has only ever
* mapped one summary per record, so nothing could answer "what did this
* session actually keep re-injecting?".
*/
export function summarizeContextReceiptSession(
vault: string,
filter: ContextReceiptFoldFilter = {},
): ContextReceiptFold {
assertContextReceiptWindowBound("since", filter.since);
assertContextReceiptWindowBound("until", filter.until);
const maxReceipts = Math.max(
1,
Math.floor(filter.maxReceipts ?? CONTEXT_RECEIPT_FOLD_MAX_RECEIPTS),
);
const matched = listContinuityRecords(vault, {
kind: "context_receipt",
...(filter.since !== undefined ? { since: filter.since } : {}),
...(filter.until !== undefined ? { until: filter.until } : {}),
})
.filter((record) =>
matchesReceiptFilter(record, {
...(filter.trigger !== undefined ? { trigger: filter.trigger } : {}),
...(filter.host !== undefined ? { host: filter.host } : {}),
...(filter.sessionId !== undefined ? { sessionId: filter.sessionId } : {}),
...(filter.exclude !== undefined ? { exclude: filter.exclude } : {}),
}),
)
.toReversed();
if (matched.length === 0) {
return Object.freeze({ recorded: false as const, max_receipts: maxReceipts });
}
const folded = matched.slice(0, maxReceipts);
const usage = new Map<string, { path?: string; injections: number; tokens: number }>();
let itemTotal = 0;
let withheld = 0;
let emptyReceipts = 0;
let malformedReceipts = 0;
for (const record of folded) {
if (record.private || record.redacted) {
withheld += 1;
continue;
}
const stored = record.payload["items"];
if (!Array.isArray(stored)) {
malformedReceipts += 1;
continue;
}
const excludeItem = filter.excludeItem;
const items = excludeItem === undefined ? stored : stored.filter((item) => !excludeItem(item));
if (items.length === 0) emptyReceipts += 1;
for (const raw of items) {
if (raw === null || typeof raw !== "object") continue;
const item = raw as Record<string, unknown>;
const id = item["id"];
if (typeof id !== "string" || id.length === 0) continue;
itemTotal += 1;
const path = typeof item["path"] === "string" ? item["path"] : undefined;
const tokens = typeof item["tokens"] === "number" ? item["tokens"] : 0;
const current = usage.get(id) ?? { injections: 0, tokens: 0 };
current.injections += 1;
current.tokens += tokens;
if (current.path === undefined && path !== undefined) current.path = path;
usage.set(id, current);
}
}
const items = [...usage.entries()]
.map(([id, entry]) =>
Object.freeze({
id,
...(entry.path !== undefined ? { path: entry.path } : {}),
injections: entry.injections,
tokens: entry.tokens,
}),
)
// Codepoint order for the id tiebreak, not `localeCompare`: the
// comparison must be reproducible across hosts, and ICU collation
// varies with the runtime locale, so the same receipts could fold to a
// different item order on two machines. Matches `stamp.ts` and
// `link-ratchet.ts`, which take the same decision for the same reason.
.toSorted(
(a, b) =>
b.injections - a.injections ||
b.tokens - a.tokens ||
(a.id < b.id ? -1 : a.id > b.id ? 1 : 0),
);
return Object.freeze({
recorded: true as const,
receipt_count: folded.length,
item_total: itemTotal,
distinct_items: usage.size,
items: Object.freeze(items),
withheld_receipts: withheld,
empty_receipts: emptyReceipts,
malformed_receipts: malformedReceipts,
truncated: matched.length > folded.length,
max_receipts: maxReceipts,
});
}
export function getContextReceipt(vault: string, id: string): ContinuityRecord | null {
return (
listContinuityRecords(vault, { kind: "context_receipt" }).find((record) => record.id === id) ??
null
);
}
// ----- reply-presence join (t_f8510c55) ------------------------------------
/**
* One injected note's presence verdict, as the answer-quote-check hook
* wrote it. The verdict string is the quote-check vocabulary (`verified`,
* `not-in-note`, `source-truncated`, `note-unavailable`, `not-text`,
* plus the per-note-only `absent`); the reader passes it through
* verbatim, so a verdict member a newer hook writes still reads here
* without a reader release.
*/
export interface ReceiptReplyPresenceNote {
readonly path: string;
readonly start_line?: number;
readonly end_line?: number;
readonly verdict: string;
}
/**
* The per-note presence verdicts one receipt's session produced, joined
* from the session's `reply_presence` records. Identifiers and verdicts
* only - the records never carried answer text, and none is invented
* here.
*/
export interface ReceiptReplyPresence {
/**
* Continuity id of the NEWEST `reply_presence` record the join folded.
* The verdicts are the fold's, not that record's alone: every readable
* session record written at or after the receipt contributed.
*/
readonly record_id: string;
/** When that record was written - the last turn the fold drew from. */
readonly created_at: string;
/**
* How many reply spans the folded records measured in sum; `null` when
* none of them carried a readable count.
*/
readonly checked: number | null;
/**
* One row per note THIS receipt injected, first-seen order across the
* folded turns kept. The hook's record covers the session's whole
* injection ledger; the join covers the receipt, so a row for a note
* the receipt never injected is not this receipt's history to report.
* A note the receipt injected that no folded record carried has no row:
* the join reports what was measured, never an inferred verdict.
*/
readonly per_note: ReadonlyArray<ReceiptReplyPresenceNote>;
/**
* How many folded note rows for THIS receipt's own notes were WITHHELD
* below the caller's reach, by the same {@link isPathReadableAtReach}
* verdict every surface resolves a path with - summed across the folded
* records. Present only when rows were dropped, so a join that
* withheld nothing stays byte-identical - and a truncated join can
* never read as a session that checked fewer notes.
*/
readonly withheld?: number;
/**
* Hash binding the verdicts to the exact answer text checked - carried
* only when the fold drew from ONE record. A fold over several records
* answers across several answers, and no single answer hash binds it.
*/
readonly source_hash?: string;
}
/**
* The outcome of joining a receipt to its session's `reply_presence`
* record. `joined` carries the verdicts; `unjoined` is the HONEST
* absence: the receipt names a session no presence record answers, or
* names no session at all. A missing join is never rendered as an
* inferred one - there is no time-window fallback - and the unjoined
* outcome names the key that did not match so a reader can tell a
* keyless receipt from an unchecked session.
*/
export type ReceiptReplyPresenceJoin =
| { readonly joined: true; readonly presence: ReceiptReplyPresence }
| { readonly joined: false; readonly reason: "unjoined"; readonly session_id?: string };
/**
* Join a context receipt to its session's reply-presence records by exact
* {@link CONTINUITY_SESSION_ID_KEY} match (t_f8510c55).
*
* The receipt's own creation draws the fold window: EVERY readable
* `reply_presence` record of the session written at or after
* `createdAt` folds into the join, chronologically, with `verified`
* winning across turns. The window is the honesty guarantee on both
* sides. The Stop hook writes a record on every checked turn - including
* turns that quote nothing, where every note reads `absent` - so joining
* only the session's newest record would answer a receipt whose note was
* verified in the next turn with a later turn's absence; and a record
* written before the receipt describes turns this receipt's injections
* did not exist for, so no earlier record may answer it either. A
* receipt with no readable record at or after its own creation reads
* `unjoined` - the HONEST absence, never an inferred join - whether no
* record exists, none matches the window, or every in-window record's
* payload is unreadable. A record whose payload cannot be read is
* skipped per record (never reported as the join, never a reason to
* orphan readable records behind it); a record whose written time cannot
* be read claims no place in the window. The join names itself
* (`record_id`, `created_at` - the newest record folded), and earlier
* turns remain in the ledger for the continuity reader.
*
* `per_note` is restricted to the receipt's own injected notes: the
* hook's record covers the session's whole ledger, and a row for a note
* the receipt never carried is not this receipt's history to report.
*
* A receipt without a session key is unjoined before the ledger is read:
* there is nothing to match on, and inventing a window would answer a
* question the receipt never asked.
*
* `view` is the caller's reach view ({@link reachView}); every folded
* note row whose path it hides is DROPPED from `per_note` and counted in
* `withheld`, so a caller below local reach reads neither the path, the
* line range nor the verdict of a page reserved against it - the same
* shaping the receipt record itself undergoes. Absent (the CLI, which
* runs at local reach by construction) withholds nothing.
*/
export function lookupReceiptReplyPresence(
vault: string,
record: ContinuityRecord,
view?: ReachView,
): ReceiptReplyPresenceJoin {
const sessionId = record.payload[CONTINUITY_SESSION_ID_KEY];
if (typeof sessionId !== "string" || sessionId.length === 0) {
return Object.freeze({ joined: false as const, reason: "unjoined" });
}
// A receipt whose creation cannot be read can establish no window at
// all: no record can prove it was written at or after the receipt, so
// nothing may claim to answer it.
const createdAtMs = Date.parse(record.createdAt);
if (Number.isNaN(createdAtMs)) {
return Object.freeze({
joined: false as const,
reason: "unjoined" as const,
session_id: sessionId,
});
}
const injectedPaths = receiptInjectedPaths(record);
// Exact session match, as before; then the window - at or after the
// receipt, readable, chronological. Append order breaks same-instant
// ties, matching the store's read order.
const store = listContinuityRecords(vault, { kind: "reply_presence" });
const turns: PresenceTurn[] = [];
for (let i = 0; i < store.length; i++) {
const sibling = store[i]!;
if (sibling.payload[CONTINUITY_SESSION_ID_KEY] !== sessionId) continue;
const writtenMs = Date.parse(sibling.createdAt);
if (Number.isNaN(writtenMs) || writtenMs < createdAtMs) continue;
const turn = readablePresenceTurn(sibling, writtenMs, i, injectedPaths, view);
if (turn !== null) turns.push(turn);
}
if (turns.length === 0) {
// No sibling at all, none at or after the receipt, or none in the
// window whose payload reads: either way the honest answer is the
// named absence, keyed on the session that did not produce a
// readable record for this receipt.
return Object.freeze({
joined: false as const,
reason: "unjoined" as const,
session_id: sessionId,
});
}
const folded = turns.toSorted(
(a, b) => a.writtenMs - b.writtenMs || a.appendIndex - b.appendIndex,
);
const newest = folded[folded.length - 1]!;
const rowsByPath = new Map<string, ReceiptReplyPresenceNote[]>();
let withheld = 0;
let checked: number | null = null;
for (const turn of folded) {
if (typeof turn.checked === "number") checked = (checked ?? 0) + turn.checked;
withheld += turn.withheld;
for (const row of turn.rows) {
const rows = rowsByPath.get(row.path);
if (rows === undefined) rowsByPath.set(row.path, [row]);
else rows.push(row);
}
}
const perNote = [...rowsByPath.values()].map((rows) => foldNoteRows(rows));
return Object.freeze({
joined: true as const,
presence: Object.freeze({
record_id: newest.record.id,
created_at: newest.record.createdAt,
checked,
per_note: Object.freeze(perNote),
...(withheld > 0 ? { withheld } : {}),
...(folded.length === 1 && folded[0]!.sourceHash !== undefined
? { source_hash: folded[0]!.sourceHash }
: {}),
}),
});
}
/**
* The vault-relative note paths THIS receipt injected: the `path` members
* of its recorded items. Items without a path (the operator-rule blocks,
* the bodies keyed by id alone) offer nothing the presence rows could
* match, and a receipt whose items cannot be read injects nothing this
* join can report on.
*/
function receiptInjectedPaths(record: ContinuityRecord): ReadonlySet<string> {
const paths = new Set<string>();
const stored = record.payload["items"];
if (!Array.isArray(stored)) return paths;
for (const raw of stored) {
if (raw === null || typeof raw !== "object") continue;
const path = (raw as Record<string, unknown>)["path"];
if (typeof path === "string" && path.length > 0) paths.add(path);
}
return paths;
}
/**
* One readable in-window `reply_presence` record, shaped for the fold:
* its rows restricted to the receipt's own injected notes, each visible
* row kept and each reach-hidden row counted. `null` when the payload
* cannot be read at all (no `per_note` array) - the per-record
* unreadable skip the walk-back named, here meaning the record simply
* contributes no turn.
*/
function readablePresenceTurn(
record: ContinuityRecord,
writtenMs: number,
appendIndex: number,
injectedPaths: ReadonlySet<string>,
view?: ReachView,
): PresenceTurn | null {
const stored = record.payload["per_note"];
if (!Array.isArray(stored)) return null;
const visible = view?.visible ?? (() => true);
const rows: ReceiptReplyPresenceNote[] = [];
let withheld = 0;
for (const raw of stored) {
if (raw === null || typeof raw !== "object") continue;
const note = raw as Record<string, unknown>;
const path = note["path"];
const verdict = note["verdict"];
if (typeof path !== "string" || path.length === 0) continue;
if (typeof verdict !== "string" || verdict.length === 0) continue;
// The receipt scopes the join: a row for a note this receipt never
// injected is dropped before the reach verdict runs, so the join
// resolves no visibility it will not use.
if (!injectedPaths.has(path)) continue;
// The reach verdict runs on the row's path BEFORE anything from it is
// kept, and a hidden row counts: reporting the drop is what keeps a
// filtered join honest instead of reading as a smaller check.
if (!visible(path)) {
withheld += 1;
continue;
}
rows.push({
path,
verdict,
...(typeof note["start_line"] === "number" ? { start_line: note["start_line"] } : {}),
...(typeof note["end_line"] === "number" ? { end_line: note["end_line"] } : {}),
});
}
const checked = record.payload["checked"];
const sourceHash = record.payload["source_hash"];
return {
record,
writtenMs,
appendIndex,
checked: typeof checked === "number" ? checked : null,
rows,
withheld,
...(typeof sourceHash === "string" && sourceHash.length > 0 ? { sourceHash } : {}),
};
}
/** Sort and fold input: one readable in-window record's contribution. */
interface PresenceTurn {
readonly record: ContinuityRecord;
/** The record's written time, the fold's primary sort key. */
readonly writtenMs: number;
/** Store append position, the same-instant tiebreak. */
readonly appendIndex: number;
readonly checked: number | null;
readonly rows: ReadonlyArray<ReceiptReplyPresenceNote>;
readonly withheld: number;
readonly sourceHash?: string;
}
/**
* Fold one injected note's rows across the folded turns, oldest first. A
* hit anywhere in the receipt's lifetime wins - a later turn's absence
* never erases an earlier verification, and the newest verifying row
* carries the line range the hit was found against. Otherwise the check
* module's own merge ladder runs over the MEASURED misses: `absent` is
* no turn's measurement, and it neither upgrades nor downgrades a miss
* another turn recorded. A note whose every row is `absent` - or whose
* verdicts a newer hook wrote and this reader cannot place - reads its
* newest row verbatim: the join passes verdict strings through, it does
* not interpret what it does not know.
*/
function foldNoteRows(rows: ReadonlyArray<ReceiptReplyPresenceNote>): ReceiptReplyPresenceNote {
if (rows.length === 1) return rows[0]!;
const verified = rows.filter((row) => row.verdict === ANSWER_QUOTE_VERDICT.verified);
if (verified.length > 0) return verified[verified.length - 1]!;
const measured = rows.flatMap((row) =>
row.verdict !== ANSWER_QUOTE_VERDICT.absent && isAnswerQuoteVerdict(row.verdict)
? [row.verdict]
: [],
);
if (measured.length > 0) {
const merged = mergeAnswerQuoteVerdicts(measured);
const carrier = [...rows].reverse().find((row) => row.verdict === merged);
return carrier ?? rows[rows.length - 1]!;
}
return rows[rows.length - 1]!;
}
export function summarizeContextReceipt(
record: ContinuityRecord,
replyPresence?: ReceiptReplyPresenceJoin,
): ContextReceiptSummary {
const payload = record.payload;
return {
id: record.id,
created_at: record.createdAt,
trigger: isContextReceiptTrigger(payload["trigger"]) ? payload["trigger"] : null,
host: typeof payload["host"] === "string" ? payload["host"] : null,
...(typeof payload["session_id"] === "string" ? { session_id: payload["session_id"] } : {}),
...(typeof payload["turn_id"] === "string" ? { turn_id: payload["turn_id"] } : {}),
item_count: typeof payload["item_count"] === "number" ? payload["item_count"] : null,
source_count: record.sourceRefs.length,
private: record.private,
redacted: record.redacted,
...adequacySummary(payload["adequacy"]),
...(replyPresence !== undefined ? { reply_presence: replyPresence } : {}),
};
}
function adequacySummary(
raw: unknown,
): { adequacy: { level: string; action: string; escalate: boolean } } | Record<string, never> {
if (typeof raw !== "object" || raw === null) return {};
const record = raw as Record<string, unknown>;
const level = record["level"];
const action = record["action"];
if (typeof level !== "string" || typeof action !== "string") return {};
return { adequacy: { level, action, escalate: record["escalate"] === true } };
}
/**
* Receipt item ids of the operator-rule blocks the SessionStart hook
* injects: the constitution and the scoped rules. Structural ids, never
* derived from content; a reader below local reach withholds them.
*/
export const RECEIPT_ITEM_STANDING_RULES = "standing-rules";
export const RECEIPT_ITEM_SCOPED_RULES = "scoped-rules";
/**
* Receipt item ids of the memory bodies the SessionStart hook charges
* against `inject_budget_chars` besides the scoped rules: the active and
* the lessons body. A receipt's budget block exists because one of them,
* or the scoped rules, was measured.
*/
export const RECEIPT_ITEM_ACTIVE_BODY = "active-body";
export const RECEIPT_ITEM_LESSONS_BODY = "lessons-body";
export { CONTEXT_RECEIPT_TRIGGERS, isContextReceiptTrigger } from "./context-receipt-trigger.ts";
function matchesReceiptFilter(record: ContinuityRecord, filter: ContextReceiptFilter): boolean {
const payload = record.payload;
if (filter.receiptId !== undefined && record.id !== filter.receiptId) return false;
if (filter.trigger !== undefined && payload["trigger"] !== filter.trigger) return false;
if (filter.host !== undefined && payload["host"] !== filter.host) return false;
if (filter.sessionId !== undefined && payload["session_id"] !== filter.sessionId) return false;
if (filter.exclude !== undefined && filter.exclude(record)) return false;
return true;
}