hippo-memory 1.70.0 → 1.71.0

package/dist/objects/customer-notes.d.ts

@@ -1,23 +1,5 @@
-/**
- * customer_note first-class object.
- *
- * A `customer_note` is a discrete note recorded against an account/customer entity:
- * a `note` body scoped to a `customer`, evolving via the supersede delta lifecycle.
- * Entity-scoping is a free-form `customer` column (the `entities` table is unbuilt,
- * so an FK is deferred). Unlike project_brief's one-summary-per-repo,
- * a customer accrues MANY discrete notes over time, each with its own supersede chain
- * (correct a note -> a new version preserving history; close retires it).
- *
- * Reuses the project_brief/skill supersede machinery verbatim (superseded_by self-FK
- * + CAS + INSERT-preflight + server-derived version + change_summary + supersede
- * tenant-match trigger). It has NO assembler/renderer (the simplest first-class object): the
- * contribution is purely the entity-scoping dimension.
- *
- * The `customer_notes` table is the source of truth (survives memory decay); the
- * memory mirror is for recall. memory_id is NULLABLE with ON DELETE SET NULL.
- *
- * Lifecycle: active -> superseded (a corrected version) or active -> closed (retired).
- */
+/** customer_note object: many discrete notes per free-form `customer` column (no entities FK yet), each with its own supersede chain.
+ *  The `customer_notes` table is the source of truth; the memory mirror (memory_id NULLABLE, ON DELETE SET NULL) is for recall. */
 import type { KeysetPosition } from '../util/keyset.js';
 import type { SavableDescriptor } from './descriptor.js';
 import type { CustomerNote, NoteStatus } from '../store/object-types.js';
@@ -47,32 +29,15 @@ export interface ListCustomerNotesOpts {
     after?: KeysetPosition;
 }
 export declare const CUSTOMER_NOTE: SavableDescriptor<'customer_note', SaveCustomerNoteOpts>;
-/**
- * Create a customer_note (or a new version that supersedes an existing one). Writes
- * the memory mirror + the customer_notes row in the `objects` store group's one transaction.
- * When supersedesNoteId is given, the referenced ACTIVE row is preflighted (status +
- * version) BEFORE the INSERT, then CAS-UPDATEd -> superseded in the same transaction;
- * the new version = predecessor.version + 1 (server-derived).
- *
- * The memory mirror carries a `customer:<lc>` tag (in addition to ['customer_note']
- * + caller extraTags) so scope-aware recall treats the note as entity-local. There is
- * no self-recursion path (customer_note has no receipt-query/refresh).
- */
+/** Create a customer_note, or a new version superseding an existing one, in the `objects` store group's one transaction.
+ *  The mirror carries a `customer:<lc>` tag so scope-aware recall treats the note as entity-local. */
 export declare function saveCustomerNote(hippoRoot: string, tenantId: string, opts: SaveCustomerNoteOpts, actor?: string): CustomerNote;
-/**
- * Close (retire) an active note. CAS guard WHERE status='active'; 0 changes
- * distinguishes not-found from not-active. A superseded row is terminal.
- */
+/** Close (retire) an active note; CAS on status='active', 0 changes means not-found or not-active. */
 export declare function closeCustomerNote(hippoRoot: string, tenantId: string, id: number, actor?: string): CustomerNote;
 export declare function loadCustomerNoteById(hippoRoot: string, tenantId: string, id: number): CustomerNote | null;
 export declare function loadCustomerNotes(hippoRoot: string, tenantId: string, opts?: ListCustomerNotesOpts): CustomerNote[];
-/**
- * All ACTIVE notes for a customer, newest first. Returns a LIST (a customer accrues
- * MANY notes) - this deliberately DIVERGES from project_brief's
- * loadActiveBriefForRepo, which returns a single brief-or-null because a repo has one
- * evolving summary. A future caller cloning the project_brief shape by analogy must
- * not assume a single-return here; the plural name signals the list contract.
- */
+/** All ACTIVE notes for a customer, newest first. Returns a LIST, unlike project_brief's single-or-null
+ *  loadActiveBriefForRepo: a customer accrues many notes. */
 export declare function loadActiveNotesForCustomer(hippoRoot: string, tenantId: string, customer: string, opts?: {
     limit?: number;
 }): CustomerNote[];

package/dist/objects/customer-notes.js

@@ -1,28 +1,7 @@
-/**
- * customer_note first-class object.
- *
- * A `customer_note` is a discrete note recorded against an account/customer entity:
- * a `note` body scoped to a `customer`, evolving via the supersede delta lifecycle.
- * Entity-scoping is a free-form `customer` column (the `entities` table is unbuilt,
- * so an FK is deferred). Unlike project_brief's one-summary-per-repo,
- * a customer accrues MANY discrete notes over time, each with its own supersede chain
- * (correct a note -> a new version preserving history; close retires it).
- *
- * Reuses the project_brief/skill supersede machinery verbatim (superseded_by self-FK
- * + CAS + INSERT-preflight + server-derived version + change_summary + supersede
- * tenant-match trigger). It has NO assembler/renderer (the simplest first-class object): the
- * contribution is purely the entity-scoping dimension.
- *
- * The `customer_notes` table is the source of truth (survives memory decay); the
- * memory mirror is for recall. memory_id is NULLABLE with ON DELETE SET NULL.
- *
- * Lifecycle: active -> superseded (a corrected version) or active -> closed (retired).
- */
+/** customer_note object: many discrete notes per free-form `customer` column (no entities FK yet), each with its own supersede chain.
+ *  The `customer_notes` table is the source of truth; the memory mirror (memory_id NULLABLE, ON DELETE SET NULL) is for recall. */
 import { checkText, requireLine } from './fields.js';
 import { closeObjectAt, listObjectsAt, objectByIdAt, saveObjectAt } from './lifecycle.js';
-// ---------------------------------------------------------------------------
-// Domain types
-// ---------------------------------------------------------------------------
 export const VALID_NOTE_STATES = new Set([
     'active',
     'superseded',
@@ -69,27 +48,12 @@ export const CUSTOMER_NOTE = {
         };
     },
 };
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Create a customer_note (or a new version that supersedes an existing one). Writes
- * the memory mirror + the customer_notes row in the `objects` store group's one transaction.
- * When supersedesNoteId is given, the referenced ACTIVE row is preflighted (status +
- * version) BEFORE the INSERT, then CAS-UPDATEd -> superseded in the same transaction;
- * the new version = predecessor.version + 1 (server-derived).
- *
- * The memory mirror carries a `customer:<lc>` tag (in addition to ['customer_note']
- * + caller extraTags) so scope-aware recall treats the note as entity-local. There is
- * no self-recursion path (customer_note has no receipt-query/refresh).
- */
+/** Create a customer_note, or a new version superseding an existing one, in the `objects` store group's one transaction.
+ *  The mirror carries a `customer:<lc>` tag so scope-aware recall treats the note as entity-local. */
 export function saveCustomerNote(hippoRoot, tenantId, opts, actor = 'cli') {
     return saveObjectAt(CUSTOMER_NOTE, { hippoRoot, tenantId, actor }, opts);
 }
-/**
- * Close (retire) an active note. CAS guard WHERE status='active'; 0 changes
- * distinguishes not-found from not-active. A superseded row is terminal.
- */
+/** Close (retire) an active note; CAS on status='active', 0 changes means not-found or not-active. */
 export function closeCustomerNote(hippoRoot, tenantId, id, actor = 'cli') {
     return closeObjectAt(hippoRoot, CUSTOMER_NOTE, tenantId, id, actor);
 }
@@ -99,13 +63,8 @@ export function loadCustomerNoteById(hippoRoot, tenantId, id) {
 export function loadCustomerNotes(hippoRoot, tenantId, opts = {}) {
     return listObjectsAt(hippoRoot, CUSTOMER_NOTE, tenantId, { status: opts.status, filter: opts.customer, limit: opts.limit, after: opts.after });
 }
-/**
- * All ACTIVE notes for a customer, newest first. Returns a LIST (a customer accrues
- * MANY notes) - this deliberately DIVERGES from project_brief's
- * loadActiveBriefForRepo, which returns a single brief-or-null because a repo has one
- * evolving summary. A future caller cloning the project_brief shape by analogy must
- * not assume a single-return here; the plural name signals the list contract.
- */
+/** All ACTIVE notes for a customer, newest first. Returns a LIST, unlike project_brief's single-or-null
+ *  loadActiveBriefForRepo: a customer accrues many notes. */
 export function loadActiveNotesForCustomer(hippoRoot, tenantId, customer, opts = {}) {
     return loadCustomerNotes(hippoRoot, tenantId, { customer, status: 'active', limit: opts.limit });
 }

package/dist/objects/decisions.d.ts

@@ -1,27 +1,6 @@
-/**
- * Decision first-class object.
- *
- * `hippo decide` used to write only a tagged memory (tags ['decision'], source
- * 'decision') with a 90-day half-life, so an in-force decision decayed out of
- * recall even though it was never reversed. The `decisions` table is now the
- * source of truth: a decision stays `active` regardless of memory decay, and
- * `hippo decide list --status active` is authoritative. A memory row still
- * mirrors the decision for recall surfaces but is NOT canonical — memory_id is
- * NULLABLE with ON DELETE SET NULL so forget/consolidate/archive gracefully
- * orphans the decision row.
- *
- * Lifecycle: active -> superseded (a newer decision replaces it; superseded_by
- * points to the successor) or active -> closed (retired with no successor).
- *
- * Tenant scoping: every helper requires tenantId. BEFORE INSERT/UPDATE triggers
- * enforce decisions.tenant_id == the referenced memory's tenant_id, and a
- * superseded_by same-tenant trigger makes cross-tenant supersession
- * unrepresentable. Mirrors the predictions pattern (src/predictions.ts).
- *
- * Dual-write atomicity: `saveDecision` hands the memory and the decision to the
- * `objects` store group, which commits them (and, when superseding, the old
- * row's UPDATE) together, so a failure in any step rolls all of them back.
- */
+/** Decision object: the `decisions` table is the source of truth, so an in-force decision stays `active` despite memory decay.
+ *  The memory mirror (memory_id NULLABLE, ON DELETE SET NULL) is for recall only; saveDecision commits both in one `objects` transaction. */
+import type { MemoryEntry } from '../core/memory.js';
 import type { KeysetPosition } from '../util/keyset.js';
 import type { SavableDescriptor } from './descriptor.js';
 import type { Decision, DecisionStatus } from '../store/object-types.js';
@@ -30,9 +9,8 @@ export declare const VALID_DECISION_STATES: ReadonlySet<DecisionStatus>;
 export interface SaveDecisionOpts {
     decisionText: string;
     context?: string;
-    /** Table id of an ACTIVE decision this one supersedes. The CLI resolves it
-     *  from a `--supersedes <memory-id>` via resolveActiveDecisionIdByMemory;
-     *  HTTP/SDK pass the table id directly. */
+    /** Table id of an ACTIVE decision this one supersedes; the CLI resolves a `--supersedes <memory-id>`
+     *  via resolveActiveDecisionIdByMemory, HTTP/SDK pass the table id. */
     supersedesDecisionId?: number;
     /** Extra memory tags merged after ['decision'] (the CLI passes path-context
      *  tags; HTTP/SDK pass none). */
@@ -45,35 +23,19 @@ export interface ListDecisionsOpts {
     after?: KeysetPosition;
 }
 export declare const DECISION: SavableDescriptor<'decision', SaveDecisionOpts>;
-/**
- * Create a decision. The memory mirror and the decisions row are written in
- * one transaction by the `objects` store group. When supersedesDecisionId is
- * given, the referenced ACTIVE row is UPDATEd -> superseded in the SAME
- * transaction (CAS: WHERE status='active'; zero rows changed means a duplicate
- * supersede aborts the whole write rather than orphaning a successor).
- *
- * The memory mirror preserves the legacy `hippo decide` shape: tags
- * ['decision', ...extraTags], source 'decision', confidence 'verified',
- * the configured default half-life, content = "<text>\n\nContext: <context>"
- * when context is given (so existing recall output is unchanged).
- */
+/** Create a decision; the memory mirror and the row commit in one transaction.
+ *  Superseding CASes the old row (WHERE status='active'), so a duplicate supersede aborts the whole write. */
 export declare function saveDecision(hippoRoot: string, tenantId: string, opts: SaveDecisionOpts, actor?: string): Decision;
-/**
- * Close (retire) an active decision with no successor. Updates the decisions
- * row only; the memory mirror is not mutated.
- */
+/** Weaken the memory a new decision replaces, once the save has committed: half-life halved to a day at least, marked stale, tagged `superseded`. */
+export declare function weakenSupersededMemory(hippoRoot: string, entry: MemoryEntry, actor?: string): void;
+/** Close (retire) an active decision with no successor; the memory mirror is not mutated. */
 export declare function closeDecision(hippoRoot: string, tenantId: string, id: number, actor?: string): Decision;
 export declare function loadDecisionById(hippoRoot: string, tenantId: string, id: number): Decision | null;
 export declare function loadDecisions(hippoRoot: string, tenantId: string, opts?: ListDecisionsOpts): Decision[];
 export declare function loadActiveDecisions(hippoRoot: string, tenantId: string, opts?: {
     limit?: number;
 }): Decision[];
-/**
- * Resolve a `--supersedes <memory-id>` (the legacy CLI contract) to the table id
- * of the ACTIVE decision backed by that memory, or null when the memory has no
- * active decision row (a legacy pre-episode decision-tagged memory). Extracted
- * so the CLI's backward-compat path is unit-testable at the store layer without
- * exporting cmdDecide.
- */
+/** Resolve a `--supersedes <memory-id>` to the table id of the ACTIVE decision backed by that memory, or null.
+ *  Exported so the CLI's backward-compat path is testable at the store layer. */
 export declare function resolveActiveDecisionIdByMemory(hippoRoot: string, tenantId: string, memoryId: string): number | null;
 //# sourceMappingURL=decisions.d.ts.map

package/dist/objects/decisions.js

@@ -1,34 +1,11 @@
-/**
- * Decision first-class object.
- *
- * `hippo decide` used to write only a tagged memory (tags ['decision'], source
- * 'decision') with a 90-day half-life, so an in-force decision decayed out of
- * recall even though it was never reversed. The `decisions` table is now the
- * source of truth: a decision stays `active` regardless of memory decay, and
- * `hippo decide list --status active` is authoritative. A memory row still
- * mirrors the decision for recall surfaces but is NOT canonical — memory_id is
- * NULLABLE with ON DELETE SET NULL so forget/consolidate/archive gracefully
- * orphans the decision row.
- *
- * Lifecycle: active -> superseded (a newer decision replaces it; superseded_by
- * points to the successor) or active -> closed (retired with no successor).
- *
- * Tenant scoping: every helper requires tenantId. BEFORE INSERT/UPDATE triggers
- * enforce decisions.tenant_id == the referenced memory's tenant_id, and a
- * superseded_by same-tenant trigger makes cross-tenant supersession
- * unrepresentable. Mirrors the predictions pattern (src/predictions.ts).
- *
- * Dual-write atomicity: `saveDecision` hands the memory and the decision to the
- * `objects` store group, which commits them (and, when superseding, the old
- * row's UPDATE) together, so a failure in any step rolls all of them back.
- */
+/** Decision object: the `decisions` table is the source of truth, so an in-force decision stays `active` despite memory decay.
+ *  The memory mirror (memory_id NULLABLE, ON DELETE SET NULL) is for recall only; saveDecision commits both in one `objects` transaction. */
 import { BadRequestError } from '../core/api-errors.js';
+import { writeEntry } from '../store/entry-writes.js';
 import { assertTenantId } from '../store/tenant.js';
 import { closeObjectAt, listObjectsAt, objectByIdAt, saveObjectAt } from './lifecycle.js';
 import { objectIdByMemory } from '../store/sqlite/objects-group.js';
-// ---------------------------------------------------------------------------
-// Domain types
-// ---------------------------------------------------------------------------
+const SUPERSEDED_TAG = 'superseded';
 export const VALID_DECISION_STATES = new Set([
     'active',
     'superseded',
@@ -53,28 +30,18 @@ export const DECISION = {
         };
     },
 };
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Create a decision. The memory mirror and the decisions row are written in
- * one transaction by the `objects` store group. When supersedesDecisionId is
- * given, the referenced ACTIVE row is UPDATEd -> superseded in the SAME
- * transaction (CAS: WHERE status='active'; zero rows changed means a duplicate
- * supersede aborts the whole write rather than orphaning a successor).
- *
- * The memory mirror preserves the legacy `hippo decide` shape: tags
- * ['decision', ...extraTags], source 'decision', confidence 'verified',
- * the configured default half-life, content = "<text>\n\nContext: <context>"
- * when context is given (so existing recall output is unchanged).
- */
+/** Create a decision; the memory mirror and the row commit in one transaction.
+ *  Superseding CASes the old row (WHERE status='active'), so a duplicate supersede aborts the whole write. */
 export function saveDecision(hippoRoot, tenantId, opts, actor = 'cli') {
     return saveObjectAt(DECISION, { hippoRoot, tenantId, actor }, opts);
 }
-/**
- * Close (retire) an active decision with no successor. Updates the decisions
- * row only; the memory mirror is not mutated.
- */
+/** Weaken the memory a new decision replaces, once the save has committed: half-life halved to a day at least, marked stale, tagged `superseded`. */
+export function weakenSupersededMemory(hippoRoot, entry, actor = 'cli') {
+    const tags = entry.tags.includes(SUPERSEDED_TAG) ? entry.tags : [...entry.tags, SUPERSEDED_TAG];
+    const halved = Math.max(1, Math.floor(entry.half_life_days / 2));
+    writeEntry(hippoRoot, { ...entry, half_life_days: halved, confidence: 'stale', tags }, { actor });
+}
+/** Close (retire) an active decision with no successor; the memory mirror is not mutated. */
 export function closeDecision(hippoRoot, tenantId, id, actor = 'cli') {
     return closeObjectAt(hippoRoot, DECISION, tenantId, id, actor);
 }
@@ -87,13 +54,8 @@ export function loadDecisions(hippoRoot, tenantId, opts = {}) {
 export function loadActiveDecisions(hippoRoot, tenantId, opts = {}) {
     return loadDecisions(hippoRoot, tenantId, { status: 'active', limit: opts.limit });
 }
-/**
- * Resolve a `--supersedes <memory-id>` (the legacy CLI contract) to the table id
- * of the ACTIVE decision backed by that memory, or null when the memory has no
- * active decision row (a legacy pre-episode decision-tagged memory). Extracted
- * so the CLI's backward-compat path is unit-testable at the store layer without
- * exporting cmdDecide.
- */
+/** Resolve a `--supersedes <memory-id>` to the table id of the ACTIVE decision backed by that memory, or null.
+ *  Exported so the CLI's backward-compat path is testable at the store layer. */
 export function resolveActiveDecisionIdByMemory(hippoRoot, tenantId, memoryId) {
     assertTenantId('resolveActiveDecisionIdByMemory', tenantId);
     return objectIdByMemory(hippoRoot, tenantId, 'decision', 'active', memoryId);

package/dist/objects/incidents.d.ts

@@ -1,30 +1,6 @@
-/**
- * Incident first-class object.
- *
- * An incident is a postmortem capsule: a recorded operational event with a
- * lifecycle and optional linked receipts (the memories that are its evidence).
- * The `incidents` table is the source of truth: an incident stays `open`
- * regardless of memory decay. A memory row still mirrors the incident for
- * recall surfaces but is NOT canonical — memory_id is NULLABLE with ON DELETE
- * SET NULL so forget/consolidate/archive gracefully orphans the incident row.
- *
- * Lifecycle: open -> resolved (a resolution was recorded; the incident stays on
- * record with resolution_text + resolved_at) or open|resolved -> closed
- * (retired with closed_at). This is NOT decision's supersede: there is no
- * superseded_by self-FK, no supersede CAS, and no supersede trigger.
- *
- * Tenant scoping: every helper requires tenantId. BEFORE INSERT/UPDATE triggers
- * enforce incidents.tenant_id == the referenced memory's tenant_id. Mirrors the
- * v30 decisions pattern (src/objects/decisions.ts).
- *
- * Dual-write atomicity: `saveIncident` writes the memory + incidents row in the
- * `objects` store group's one transaction, so a failure in any step rolls all of
- * them back.
- *
- * linked_memory_ids ("linked receipts"): a JSON-encoded array of memory ids on
- * the row, default `[]`. On save, every id must exist in the SAME tenant; a
- * cross-tenant or nonexistent id is rejected (throw) before the insert.
- */
+/** Incident object: a postmortem capsule with lifecycle open -> resolved -> closed (no supersede chain) and optional linked receipts.
+ *  The `incidents` table is the source of truth; the memory mirror (memory_id NULLABLE, ON DELETE SET NULL) is for recall.
+ *  linked_memory_ids must all exist in the SAME tenant or save throws before the insert. */
 import type { KeysetPosition } from '../util/keyset.js';
 import type { ObjectDescriptor } from './descriptor.js';
 import type { Incident, IncidentStatus } from '../store/object-types.js';
@@ -48,7 +24,8 @@ export interface ListIncidentsOpts {
     after?: KeysetPosition;
 }
 export declare const INCIDENT: ObjectDescriptor<'incident'>;
-/** Opens an incident with its mirror memory (content "<text>\n\nContext: <context>" when context is given) in one write; a linked memory outside the tenant refuses the whole write. */
+/** Opens an incident with its mirror memory (content "<text>\n\nContext: <context>" when
+ * context is given) in one write; a linked memory outside the tenant refuses the whole write. */
 export declare function saveIncident(hippoRoot: string, tenantId: string, opts: SaveIncidentOpts, actor?: string): Incident;
 /** `saveIncident` over a served store's group. */
 export declare function openIncident(objects: Objects, hippoRoot: string, tenantId: string, opts: SaveIncidentOpts, actor: string): Promise<Incident>;
@@ -56,21 +33,13 @@ export declare function openIncident(objects: Objects, hippoRoot: string, tenant
 export declare function resolveIncident(hippoRoot: string, tenantId: string, id: number, resolutionText: string, actor?: string): Incident;
 /** `resolveIncident` over a served store's group. */
 export declare function resolveOpenIncident(objects: Objects, tenantId: string, id: number, resolutionText: string, actor: string): Promise<Incident>;
-/**
- * Close (retire) an incident from open or resolved (open|resolved -> closed).
- * Updates closed_at only; the memory mirror is not mutated.
- */
+/** Close (retire) an incident from open or resolved; sets closed_at only, the memory mirror is not mutated. */
 export declare function closeIncident(hippoRoot: string, tenantId: string, id: number, actor?: string): Incident;
 export declare function loadIncidentById(hippoRoot: string, tenantId: string, id: number): Incident | null;
 export declare function loadIncidents(hippoRoot: string, tenantId: string, opts?: ListIncidentsOpts): Incident[];
 export declare function loadOpenIncidents(hippoRoot: string, tenantId: string, opts?: {
     limit?: number;
 }): Incident[];
-/**
- * Resolve a memory id to the table id of the OPEN incident backed by that
- * memory, or null when the memory has no open incident row. Extracted so a
- * memory-id-based lookup is unit-testable at the store layer (mirror of
- * resolveActiveDecisionIdByMemory).
- */
+/** Resolve a memory id to the table id of the OPEN incident backed by it, or null; exported for store-layer tests. */
 export declare function resolveActiveIncidentIdByMemory(hippoRoot: string, tenantId: string, memoryId: string): number | null;
 //# sourceMappingURL=incidents.d.ts.map

package/dist/objects/incidents.js

@@ -1,38 +1,11 @@
-/**
- * Incident first-class object.
- *
- * An incident is a postmortem capsule: a recorded operational event with a
- * lifecycle and optional linked receipts (the memories that are its evidence).
- * The `incidents` table is the source of truth: an incident stays `open`
- * regardless of memory decay. A memory row still mirrors the incident for
- * recall surfaces but is NOT canonical — memory_id is NULLABLE with ON DELETE
- * SET NULL so forget/consolidate/archive gracefully orphans the incident row.
- *
- * Lifecycle: open -> resolved (a resolution was recorded; the incident stays on
- * record with resolution_text + resolved_at) or open|resolved -> closed
- * (retired with closed_at). This is NOT decision's supersede: there is no
- * superseded_by self-FK, no supersede CAS, and no supersede trigger.
- *
- * Tenant scoping: every helper requires tenantId. BEFORE INSERT/UPDATE triggers
- * enforce incidents.tenant_id == the referenced memory's tenant_id. Mirrors the
- * v30 decisions pattern (src/objects/decisions.ts).
- *
- * Dual-write atomicity: `saveIncident` writes the memory + incidents row in the
- * `objects` store group's one transaction, so a failure in any step rolls all of
- * them back.
- *
- * linked_memory_ids ("linked receipts"): a JSON-encoded array of memory ids on
- * the row, default `[]`. On save, every id must exist in the SAME tenant; a
- * cross-tenant or nonexistent id is rejected (throw) before the insert.
- */
+/** Incident object: a postmortem capsule with lifecycle open -> resolved -> closed (no supersede chain) and optional linked receipts.
+ *  The `incidents` table is the source of truth; the memory mirror (memory_id NULLABLE, ON DELETE SET NULL) is for recall.
+ *  linked_memory_ids must all exist in the SAME tenant or save throws before the insert. */
 import { BadRequestError, ConflictError, NotFoundError } from '../core/api-errors.js';
 import { assertTenantId } from '../store/tenant.js';
 import { closeObjectAt, listObjectsAt, objectByIdAt, objectMirror } from './lifecycle.js';
 import { isObjectRefusal } from '../store/port.js';
 import { objectIdByMemory, sqliteObjects } from '../store/sqlite/objects-group.js';
-// ---------------------------------------------------------------------------
-// Domain types
-// ---------------------------------------------------------------------------
 export const VALID_INCIDENT_STATES = new Set([
     'open',
     'resolved',
@@ -69,7 +42,8 @@ function opened(tenantId, written) {
         throw new NotFoundError(`saveIncident: linked memory ${written.memoryId} not found for tenant ${tenantId}`);
     throw new Error('saveIncident: failed to reload saved incident row');
 }
-/** Opens an incident with its mirror memory (content "<text>\n\nContext: <context>" when context is given) in one write; a linked memory outside the tenant refuses the whole write. */
+/** Opens an incident with its mirror memory (content "<text>\n\nContext: <context>" when
+ * context is given) in one write; a linked memory outside the tenant refuses the whole write. */
 export function saveIncident(hippoRoot, tenantId, opts, actor = 'cli') {
     return opened(tenantId, sqliteObjects(hippoRoot).openIncident(tenantId, incidentOpen(hippoRoot, tenantId, opts, actor)));
 }
@@ -101,10 +75,7 @@ export function resolveIncident(hippoRoot, tenantId, id, resolutionText, actor =
 export async function resolveOpenIncident(objects, tenantId, id, resolutionText, actor) {
     return resolved(tenantId, id, await objects.resolveIncident(tenantId, id, resolving(tenantId, resolutionText, actor)));
 }
-/**
- * Close (retire) an incident from open or resolved (open|resolved -> closed).
- * Updates closed_at only; the memory mirror is not mutated.
- */
+/** Close (retire) an incident from open or resolved; sets closed_at only, the memory mirror is not mutated. */
 export function closeIncident(hippoRoot, tenantId, id, actor = 'cli') {
     return closeObjectAt(hippoRoot, INCIDENT, tenantId, id, actor);
 }
@@ -117,12 +88,7 @@ export function loadIncidents(hippoRoot, tenantId, opts = {}) {
 export function loadOpenIncidents(hippoRoot, tenantId, opts = {}) {
     return loadIncidents(hippoRoot, tenantId, { status: 'open', limit: opts.limit });
 }
-/**
- * Resolve a memory id to the table id of the OPEN incident backed by that
- * memory, or null when the memory has no open incident row. Extracted so a
- * memory-id-based lookup is unit-testable at the store layer (mirror of
- * resolveActiveDecisionIdByMemory).
- */
+/** Resolve a memory id to the table id of the OPEN incident backed by it, or null; exported for store-layer tests. */
 export function resolveActiveIncidentIdByMemory(hippoRoot, tenantId, memoryId) {
     assertTenantId('resolveActiveIncidentIdByMemory', tenantId);
     return objectIdByMemory(hippoRoot, tenantId, 'incident', 'open', memoryId);

package/dist/objects/policies.d.ts

@@ -1,41 +1,6 @@
-/**
- * Policy first-class object.
- *
- * The "bi-temporal-first" object type: a named rule/statement that is in force
- * over an EFFECTIVE-TIME range and evolves via supersession. Two time axes:
- *
- *  - Valid time (effective time): when the policy is in force in the real world,
- *    as first-class columns `valid_from` (required; defaults to creation time)
- *    and `valid_to` (nullable = open-ended). This is the queryable axis: see
- *    `loadPoliciesAsOf` (the active policies in force at a given valid-time).
- *  - Transaction time (system time): when the row was recorded / retired, via
- *    `created_at` + the supersede chain's `superseded_at`. Present, but
- *    time-travel ("what did we BELIEVE was in force at past system time T") is
- *    deferred to a future version.
- *
- * The delta lifecycle reuses the process/decision supersede machinery verbatim
- * (superseded_by self-FK + CAS + INSERT-preflight + server-derived version +
- * change_summary + supersede tenant-match trigger). It DROPS process's `steps`
- * (a policy has `policy_text`) and ADDS `valid_from`/`valid_to`.
- *
- * The `policies` table is the source of truth (survives memory decay); the
- * memory mirror is for recall only. memory_id is NULLABLE with ON DELETE SET
- * NULL so forget/consolidate/archive gracefully orphans the policy row.
- *
- * Lifecycle: active -> superseded (a newer version replaces it) or active ->
- * closed (retired with no successor). Superseding leaves the predecessor's
- * valid-time range intact (it WAS effective then); only the status flips.
- *
- * Date handling: every date input (savePolicy's valid_from/valid_to,
- * loadPoliciesAsOf's asOfDate) is normalized to canonical ISO-8601 datetime
- * (`toISOString`) at the store boundary BEFORE any persist or compare, so the
- * fixed-width values sort lexically and the half-open [valid_from, valid_to)
- * comparison is correct (a date-only asOf vs a datetime valid_from would
- * otherwise make a same-day policy invisible).
- *
- * Dual-write atomicity: `savePolicy` writes the memory + policies row (and, on
- * supersede, the predecessor's UPDATE) in the `objects` store group's one transaction.
- */
+/** Policy object: a rule in force over a valid-time range [valid_from, valid_to), evolving via supersession; `loadPoliciesAsOf` queries it.
+ *  Transaction-time travel (what we believed at past system time T) is deferred. Superseding keeps the predecessor's valid-time range.
+ *  All dates are normalised to ISO-8601 (`toISOString`) at the store boundary so the lexical half-open comparison is sound. */
 import type { KeysetPosition } from '../util/keyset.js';
 import type { SavableDescriptor } from './descriptor.js';
 import type { Policy, PolicyStatus } from '../store/object-types.js';
@@ -62,70 +27,27 @@ export interface ListPoliciesOpts {
     /** Resume after this row: the position the previous page ended on. */
     after?: KeysetPosition;
 }
-/**
- * Parse + canonicalize a date input to ISO-8601 datetime (`toISOString`). Throws
- * on an unparseable value. Whatever `new Date()` accepts is re-emitted in the
- * single fixed-width canonical form, so date-only and datetime inputs collapse to
- * comparable values and lexical ordering is sound. (Overflow inputs like
- * '2026-02-30' roll forward per JS Date semantics rather than throwing; the
- * stored value is still canonical.)
- */
+/** Parse a date input to a fixed-width ISO-8601 datetime so lexical ordering is sound; throws on an unparseable value.
+ *  Overflow inputs like '2026-02-30' roll forward per JS Date semantics. */
 export declare function normalizePolicyDate(input: string, label?: string): string;
-/**
- * Normalize valid_from (defaulting to `nowIso` when undefined) + valid_to (null
- * when undefined), then enforce valid_to > valid_from. Returns the canonical pair.
- */
+/** Normalise valid_from (default `nowIso`) and valid_to (default null), then enforce valid_to > valid_from. */
 export declare function validatePolicyDates(validFromRaw: string | undefined, validToRaw: string | undefined, nowIso: string): {
     validFrom: string;
     validTo: string | null;
 };
 export declare const POLICY: SavableDescriptor<'policy', SavePolicyOpts>;
-/**
- * Create a policy (or a new version that supersedes an existing one). Writes the
- * memory mirror + the policies row in the `objects` store group's one transaction.
- * valid_from defaults to now; valid_to must be > valid_from (validatePolicyDates).
- * When supersedesPolicyId is given, the referenced ACTIVE row is preflighted
- * (status + version) BEFORE the INSERT, then CAS-UPDATEd -> superseded in the same
- * transaction; the new version = predecessor.version + 1 (server-derived).
- */
+/** Create a policy, or a new version superseding an existing one, in the `objects` store group's one transaction.
+ *  valid_from defaults to now; valid_to must be > valid_from (validatePolicyDates). */
 export declare function savePolicy(hippoRoot: string, tenantId: string, opts: SavePolicyOpts, actor?: string): Policy;
-/**
- * Close (retire) an active policy with no successor. CAS guard WHERE
- * status='active'; 0 changes distinguishes not-found from not-active. A
- * superseded row is terminal and cannot be closed.
- */
+/** Close (retire) an active policy with no successor; CAS on status='active', a superseded row is terminal. */
 export declare function closePolicy(hippoRoot: string, tenantId: string, id: number, actor?: string): Policy;
 export declare function loadPolicyById(hippoRoot: string, tenantId: string, id: number): Policy | null;
 export declare function loadPolicies(hippoRoot: string, tenantId: string, opts?: ListPoliciesOpts): Policy[];
 export declare function loadActivePolicies(hippoRoot: string, tenantId: string, opts?: {
     limit?: number;
 }): Policy[];
-/**
- * The bi-temporal as-of query: the policies in force at `asOfDate` (a valid-time)
- * per current knowledge. Half-open interval [valid_from, valid_to): a row covers
- * T when valid_from <= asOf AND (valid_to IS NULL OR asOf < valid_to). asOfDate is
- * normalized to canonical datetime first so the lexical comparison is sound.
- *
- * A row is returned when it covers T AND it is the live answer for T:
- *  - `active` rows that cover T, OR
- *  - `superseded` rows that cover T BUT whose successor was not yet effective at T
- *    (successor.valid_from > asOf) - i.e. an earlier version that was genuinely in
- *    force then. This is the core valid-time correctness: a Jan-Jun policy
- *    superseded in May is still the answer for `asof March`. Filtering on
- *    status='active' alone would conflate transaction-time with valid-time; the
- *    successor-aware filter mirrors the existing recall-history.ts asOf pattern.
- *
- * `closed` rows are EXCLUDED: closing is a deliberate transaction-time retirement,
- * and resurrecting closed policies for a historical valid-time is full
- * transaction-time-travel (deferred). Returns an ARRAY (overlapping same-name
- * ranges are allowed in v1). Optionally filtered to one policy_name.
- *
- * Date-only `asOfDate` (YYYY-MM-DD, no time component) resolves to the END
- * of that UTC day (23:59:59.999Z), so "as of [day D]" includes a policy that
- * became effective at any instant during D - this is the read-side fix for the
- * common create-then-asof-today workflow, keeping the stored valid_from honest.
- * A full datetime asOf is used as the precise instant.
- */
+/** The policies in force at `asOfDate` (valid-time, half-open [valid_from, valid_to)); superseded rows still answer while the successor is not yet effective.
+ *  `closed` rows are excluded; a date-only asOfDate means the END of that UTC day (23:59:59.999Z), so a policy created today shows up in "as of today". */
 export declare function loadPoliciesAsOf(hippoRoot: string, tenantId: string, asOfDate: string, opts?: {
     name?: string;
     limit?: number;