hippo-memory 1.69.0 → 1.71.0

package/dist/objects/customer-notes.js

@@ -0,0 +1,71 @@
+/** 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';
+export const VALID_NOTE_STATES = new Set([
+    'active',
+    'superseded',
+    'closed',
+]);
+/** Field caps (untrusted at the HTTP/SDK boundary). note is a body, so a larger cap
+ *  than the 4096 short-field convention. */
+export const MAX_CUSTOMER_LEN = 256;
+export const MAX_NOTE_LEN = 8192;
+export const MAX_CHANGE_SUMMARY_LEN = 4096;
+/** Recall-surface content for the memory mirror: customer + note. Named (mirrors
+ *  buildBriefContent) so the recall surface is deterministic + unit-testable. */
+function buildNoteContent(customer, note) {
+    return `${customer}\n\n${note}`;
+}
+export const CUSTOMER_NOTE = {
+    kind: 'customer_note',
+    label: 'note',
+    plural: 'notes',
+    fn: { get: 'loadCustomerNoteById', close: 'closeCustomerNote', list: 'loadCustomerNotes', save: 'saveCustomerNote' },
+    states: VALID_NOTE_STATES,
+    closableFrom: ['active'],
+    draft(opts) {
+        // The customer becomes a `customer:<lc>` recall tag and an identifier, so it must be one line.
+        const customer = requireLine(opts.customer, MAX_CUSTOMER_LEN, {
+            required: 'saveCustomerNote: customer is required',
+            singleLine: 'saveCustomerNote: customer must be a single line (no newlines)',
+            tooLong: `saveCustomerNote: customer exceeds the ${MAX_CUSTOMER_LEN}-char cap`,
+        });
+        checkText(opts.note, MAX_NOTE_LEN, {
+            required: 'saveCustomerNote: note is required',
+            tooLong: `saveCustomerNote: note exceeds the ${MAX_NOTE_LEN}-char cap`,
+        });
+        checkText(opts.changeSummary, MAX_CHANGE_SUMMARY_LEN, {
+            tooLong: `saveCustomerNote: changeSummary exceeds the ${MAX_CHANGE_SUMMARY_LEN}-char cap`,
+        });
+        return {
+            fields: { customer, note: opts.note },
+            content: buildNoteContent(customer, opts.note),
+            tags: [`customer:${customer.toLowerCase()}`, ...(opts.extraTags ?? [])],
+            supersedesId: opts.supersedesNoteId,
+            changeSummary: opts.changeSummary,
+            at: new Date().toISOString(),
+        };
+    },
+};
+/** 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 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);
+}
+export function loadCustomerNoteById(hippoRoot, tenantId, id) {
+    return objectByIdAt(hippoRoot, CUSTOMER_NOTE, 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, 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 });
+}
+//# sourceMappingURL=customer-notes.js.map

package/dist/objects/decisions.d.ts

@@ -0,0 +1,41 @@
+/** 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';
+export type { Decision, DecisionStatus } from '../store/object-types.js';
+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 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). */
+    extraTags?: string[];
+}
+export interface ListDecisionsOpts {
+    status?: DecisionStatus;
+    limit?: number;
+    /** Resume after this row: the position the previous page ended on. */
+    after?: KeysetPosition;
+}
+export declare const DECISION: SavableDescriptor<'decision', SaveDecisionOpts>;
+/** 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;
+/** 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>` 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

@@ -0,0 +1,63 @@
+/** 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';
+const SUPERSEDED_TAG = 'superseded';
+export const VALID_DECISION_STATES = new Set([
+    'active',
+    'superseded',
+    'closed',
+]);
+export const DECISION = {
+    kind: 'decision',
+    label: 'decision',
+    plural: 'decisions',
+    fn: { get: 'loadDecisionById', close: 'closeDecision', list: 'loadDecisions', save: 'saveDecision' },
+    states: VALID_DECISION_STATES,
+    closableFrom: ['active'],
+    draft(opts) {
+        if (!opts.decisionText)
+            throw new BadRequestError('saveDecision: decisionText is required');
+        return {
+            fields: { decisionText: opts.decisionText, context: opts.context },
+            content: opts.context ? `${opts.decisionText}\n\nContext: ${opts.context}` : opts.decisionText,
+            tags: opts.extraTags ?? [],
+            supersedesId: opts.supersedesDecisionId,
+            at: new Date().toISOString(),
+        };
+    },
+};
+/** 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);
+}
+/** 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);
+}
+export function loadDecisionById(hippoRoot, tenantId, id) {
+    return objectByIdAt(hippoRoot, DECISION, tenantId, id);
+}
+export function loadDecisions(hippoRoot, tenantId, opts = {}) {
+    return listObjectsAt(hippoRoot, DECISION, tenantId, opts);
+}
+export function loadActiveDecisions(hippoRoot, tenantId, opts = {}) {
+    return loadDecisions(hippoRoot, tenantId, { status: 'active', limit: opts.limit });
+}
+/** 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);
+}
+//# sourceMappingURL=decisions.js.map

package/dist/objects/descriptor.d.ts

@@ -0,0 +1,52 @@
+import type { KeysetPosition } from '../util/keyset.js';
+import type { ObjectByKind, ObjectFields, ObjectKind, SavableKind } from '../store/object-types.js';
+export interface ObjectDescriptor<K extends ObjectKind> {
+    readonly kind: K;
+    /** The nouns error text uses: "brief 3 not found", "only active briefs". */
+    readonly label: string;
+    readonly plural: string;
+    /** The exported function names; each one prefixes the errors of its own call. */
+    readonly fn: {
+        readonly get: string;
+        readonly close: string;
+        readonly list: string;
+    };
+    readonly states: ReadonlySet<ObjectByKind[K]['status']>;
+    /** The statuses a close may start from. */
+    readonly closableFrom: readonly ObjectByKind[K]['status'][];
+    /** Said in place of "not <closable statuses>" when a close is refused; incidents say "already closed". */
+    readonly closeRefusal?: string;
+}
+/** One save, checked and resolved before a store is asked. */
+export interface ObjectDraft<K extends SavableKind> {
+    readonly fields: ObjectFields[K];
+    /** The mirror memory's text, and its tags after the kind's own. */
+    readonly content: string;
+    readonly tags: readonly string[];
+    /** The active object this one replaces. */
+    readonly supersedesId: number | undefined;
+    /** What changed; stored only on a versioned successor. */
+    readonly changeSummary?: string;
+    /** Read once the checks pass, so one instant stamps everything the save writes. */
+    readonly at: string;
+}
+/** A kind the shared save writes: active rows, replaced by supersede. `W` is the options its module's save takes. */
+export interface SavableDescriptor<K extends SavableKind, W> extends ObjectDescriptor<K> {
+    readonly fn: {
+        readonly get: string;
+        readonly close: string;
+        readonly list: string;
+        readonly save: string;
+    };
+    /** Throws BadRequestError for options the kind refuses. */
+    readonly draft: (opts: W) => ObjectDraft<K>;
+}
+export interface ObjectListOpts<K extends ObjectKind> {
+    status?: ObjectByKind[K]['status'];
+    /** The value the kind's one filter column must equal: a customer note's customer, a project brief's repo. */
+    filter?: string;
+    limit?: number;
+    /** Resume after this row: the position the previous page ended on. */
+    after?: KeysetPosition;
+}
+//# sourceMappingURL=descriptor.d.ts.map

package/dist/objects/descriptor.js

@@ -0,0 +1,4 @@
+// The words and rules that differ between the typed objects (decision, project brief and the rest), held as data so one lifecycle serves every kind.
+// A kind's table, columns and audit keys sit behind the `objects` store group.
+export {};
+//# sourceMappingURL=descriptor.js.map

package/dist/objects/fields.d.ts

@@ -0,0 +1,15 @@
+export interface LineMessages {
+    readonly required: string;
+    readonly singleLine: string;
+    readonly tooLong: string;
+}
+/** A one-line name such as a repo or a customer: trimmed first, because the trimmed value is what gets stored and matched. */
+export declare function requireLine(value: string, max: number, m: LineMessages): string;
+export interface TextMessages {
+    /** Leave out for an optional field. */
+    readonly required?: string;
+    readonly tooLong: string;
+}
+/** A body stored as written: blank fails a required one, and the cap counts the untrimmed length. */
+export declare function checkText(value: string | undefined, max: number, m: TextMessages): void;
+//# sourceMappingURL=fields.d.ts.map

package/dist/objects/fields.js

@@ -0,0 +1,21 @@
+// Field checks the typed objects share. The module passes each error text in full, because the wording differs per type.
+import { BadRequestError } from '../core/api-errors.js';
+/** A one-line name such as a repo or a customer: trimmed first, because the trimmed value is what gets stored and matched. */
+export function requireLine(value, max, m) {
+    const line = (value ?? '').trim();
+    if (line.length === 0)
+        throw new BadRequestError(m.required);
+    if (/[\r\n]/.test(line))
+        throw new BadRequestError(m.singleLine);
+    if (line.length > max)
+        throw new BadRequestError(m.tooLong);
+    return line;
+}
+/** A body stored as written: blank fails a required one, and the cap counts the untrimmed length. */
+export function checkText(value, max, m) {
+    if (m.required !== undefined && (!value || value.trim().length === 0))
+        throw new BadRequestError(m.required);
+    if (value !== undefined && value.length > max)
+        throw new BadRequestError(m.tooLong);
+}
+//# sourceMappingURL=fields.js.map

package/dist/objects/incidents.d.ts

@@ -0,0 +1,45 @@
+/** 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';
+import { type Objects } from '../store/port.js';
+export type { Incident, IncidentStatus } from '../store/object-types.js';
+export declare const VALID_INCIDENT_STATES: ReadonlySet<IncidentStatus>;
+export interface SaveIncidentOpts {
+    incidentText: string;
+    context?: string;
+    /** Memory ids (linked receipts) that are this incident's evidence. Each must
+     *  exist in the same tenant; cross-tenant/nonexistent ids are rejected. */
+    linkedMemoryIds?: string[];
+    /** Extra memory tags merged after ['incident'] (the CLI passes path-context
+     *  tags; HTTP/SDK pass none). */
+    extraTags?: string[];
+}
+export interface ListIncidentsOpts {
+    status?: IncidentStatus;
+    limit?: number;
+    /** Resume after this row: the position the previous page ended on. */
+    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. */
+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>;
+/** Moves an open incident to resolved and keeps it on record; a missing incident and one that is not open are told apart. */
+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; 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 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

@@ -0,0 +1,96 @@
+/** 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';
+export const VALID_INCIDENT_STATES = new Set([
+    'open',
+    'resolved',
+    'closed',
+]);
+// No draft: an incident is opened with linked memories and is never superseded, so it keeps its own save.
+export const INCIDENT = {
+    kind: 'incident',
+    label: 'incident',
+    plural: 'incidents',
+    fn: { get: 'loadIncidentById', close: 'closeIncident', list: 'loadIncidents' },
+    states: VALID_INCIDENT_STATES,
+    closableFrom: ['open', 'resolved'],
+    closeRefusal: 'already closed',
+};
+/** One open, checked before a store is asked; `hippoRoot` is read only for the configured half-life. */
+function incidentOpen(hippoRoot, tenantId, opts, actor) {
+    assertTenantId('saveIncident', tenantId);
+    if (!opts.incidentText)
+        throw new BadRequestError('saveIncident: incidentText is required');
+    const at = new Date().toISOString();
+    const content = opts.context
+        ? `${opts.incidentText}\n\nContext: ${opts.context}`
+        : opts.incidentText;
+    const mirror = objectMirror(hippoRoot, tenantId, 'incident', { content, tags: opts.extraTags ?? [] });
+    const fields = { incidentText: opts.incidentText, context: opts.context ?? undefined, linkedMemoryIds: opts.linkedMemoryIds ?? [] };
+    return { mirror, fields, actor, at };
+}
+function opened(tenantId, written) {
+    if (!('refused' in written))
+        return written;
+    // A linked id of another tenant reads as missing, so an unverifiable receipt is never recorded.
+    if (written.refused === 'unlinked')
+        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. */
+export function saveIncident(hippoRoot, tenantId, opts, actor = 'cli') {
+    return opened(tenantId, sqliteObjects(hippoRoot).openIncident(tenantId, incidentOpen(hippoRoot, tenantId, opts, actor)));
+}
+/** `saveIncident` over a served store's group. */
+export async function openIncident(objects, hippoRoot, tenantId, opts, actor) {
+    return opened(tenantId, await objects.openIncident(tenantId, incidentOpen(hippoRoot, tenantId, opts, actor)));
+}
+function resolving(tenantId, resolutionText, actor) {
+    assertTenantId('resolveIncident', tenantId);
+    if (!resolutionText || !resolutionText.trim()) {
+        throw new BadRequestError('resolveIncident: resolutionText is required (non-empty)');
+    }
+    return { text: resolutionText, actor, at: new Date().toISOString() };
+}
+function resolved(tenantId, id, written) {
+    if (!isObjectRefusal(written))
+        return written;
+    if (written.refused === 'missing')
+        throw new NotFoundError(`resolveIncident: incident ${id} not found for tenant ${tenantId}`);
+    if (written.refused !== 'status')
+        throw new NotFoundError(`resolveIncident: incident ${id} not found after UPDATE`);
+    throw new ConflictError(`resolveIncident: incident ${id} is not open (status='${written.status}'); only open incidents can be resolved.`);
+}
+/** Moves an open incident to resolved and keeps it on record; a missing incident and one that is not open are told apart. */
+export function resolveIncident(hippoRoot, tenantId, id, resolutionText, actor = 'cli') {
+    return resolved(tenantId, id, sqliteObjects(hippoRoot).resolveIncident(tenantId, id, resolving(tenantId, resolutionText, actor)));
+}
+/** `resolveIncident` over a served store's group. */
+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; 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);
+}
+export function loadIncidentById(hippoRoot, tenantId, id) {
+    return objectByIdAt(hippoRoot, INCIDENT, tenantId, id);
+}
+export function loadIncidents(hippoRoot, tenantId, opts = {}) {
+    return listObjectsAt(hippoRoot, INCIDENT, 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 it, or null; exported for store-layer tests. */
+export function resolveActiveIncidentIdByMemory(hippoRoot, tenantId, memoryId) {
+    assertTenantId('resolveActiveIncidentIdByMemory', tenantId);
+    return objectIdByMemory(hippoRoot, tenantId, 'incident', 'open', memoryId);
+}
+//# sourceMappingURL=incidents.js.map

package/dist/objects/lifecycle.d.ts

@@ -0,0 +1,27 @@
+import { type MemoryEntry } from '../core/memory.js';
+import type { ObjectByKind, ObjectKind, SavableKind } from '../store/object-types.js';
+import { type Objects } from '../store/port.js';
+import type { ObjectDescriptor, ObjectListOpts, SavableDescriptor } from './descriptor.js';
+/** Newest first. */
+export declare function listObjectsAt<K extends ObjectKind>(hippoRoot: string, d: ObjectDescriptor<K>, tenantId: string, opts: ObjectListOpts<K>): ObjectByKind[K][];
+export declare function listObjects<K extends ObjectKind>(objects: Objects, d: ObjectDescriptor<K>, tenantId: string, opts: ObjectListOpts<K>): Promise<ObjectByKind[K][]>;
+export declare function objectByIdAt<K extends ObjectKind>(hippoRoot: string, d: ObjectDescriptor<K>, tenantId: string, id: number): ObjectByKind[K] | null;
+export declare function objectById<K extends ObjectKind>(objects: Objects, d: ObjectDescriptor<K>, tenantId: string, id: number): Promise<ObjectByKind[K] | null>;
+/** Retires one object; its mirror memory stays as saved. */
+export declare function closeObjectAt<K extends ObjectKind>(hippoRoot: string, d: ObjectDescriptor<K>, tenantId: string, id: number, actor: string): ObjectByKind[K];
+export declare function closeObject<K extends ObjectKind>(objects: Objects, d: ObjectDescriptor<K>, tenantId: string, id: number, actor: string): Promise<ObjectByKind[K]>;
+/** The memory a typed object writes beside its row, so recall finds the object. */
+export declare function objectMirror(hippoRoot: string, tenantId: string, source: ObjectKind, text: {
+    readonly content: string;
+    readonly tags: readonly string[];
+}): MemoryEntry;
+/** Where a save lands and who makes it; `hippoRoot` is read only for the configured half-life. */
+export interface ObjectSaveSite {
+    readonly hippoRoot: string;
+    readonly tenantId: string;
+    readonly actor: string;
+}
+/** Creates an object, or the version that replaces the one its options name, with its mirror memory in one write. */
+export declare function saveObjectAt<K extends SavableKind, W>(d: SavableDescriptor<K, W>, site: ObjectSaveSite, opts: W): ObjectByKind[K];
+export declare function saveObject<K extends SavableKind, W>(objects: Objects, d: SavableDescriptor<K, W>, site: ObjectSaveSite, opts: W): Promise<ObjectByKind[K]>;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/objects/lifecycle.js

@@ -0,0 +1,96 @@
+// Save, close, load-by-id and list for every typed object: the checks, the mirror memory and the error text, over the `objects` store group.
+// Each flow is written twice over the same steps: `...At` answers at once on hippo.db for the CLI, and the other awaits a served store's group for the routes.
+// The tenant, the fields and the list status are checked first, so a bad request fails before a store is asked.
+import { BadRequestError, ConflictError, NotFoundError } from '../core/api-errors.js';
+import { loadConfig } from '../core/config.js';
+import { createMemory, Layer } from '../core/memory.js';
+import { isObjectRefusal } from '../store/port.js';
+import { sqliteObjects } from '../store/sqlite/objects-group.js';
+import { assertTenantId } from '../store/tenant.js';
+/** An empty status or filter lists every row, as an absent one does. */
+function listQuery(d, tenantId, opts) {
+    assertTenantId(d.fn.list, tenantId);
+    if (opts.status && !d.states.has(opts.status)) {
+        throw new BadRequestError(`${d.fn.list}: status must be one of ${Array.from(d.states).join('|')}; got ${opts.status}`);
+    }
+    return { status: opts.status || undefined, filter: opts.filter || undefined, limit: opts.limit ?? 100, after: opts.after };
+}
+/** Newest first. */
+export function listObjectsAt(hippoRoot, d, tenantId, opts) {
+    return sqliteObjects(hippoRoot).listObjects(tenantId, d.kind, listQuery(d, tenantId, opts));
+}
+export async function listObjects(objects, d, tenantId, opts) {
+    return objects.listObjects(tenantId, d.kind, listQuery(d, tenantId, opts));
+}
+export function objectByIdAt(hippoRoot, d, tenantId, id) {
+    assertTenantId(d.fn.get, tenantId);
+    return sqliteObjects(hippoRoot).objectById(tenantId, d.kind, id);
+}
+export async function objectById(objects, d, tenantId, id) {
+    assertTenantId(d.fn.get, tenantId);
+    return objects.objectById(tenantId, d.kind, id);
+}
+function closing(d, tenantId, actor) {
+    assertTenantId(d.fn.close, tenantId);
+    return { from: d.closableFrom, actor, at: new Date().toISOString() };
+}
+function closed(d, tenantId, id, written) {
+    if (!isObjectRefusal(written))
+        return written;
+    if (written.refused === 'missing')
+        throw new NotFoundError(`${d.fn.close}: ${d.label} ${id} not found for tenant ${tenantId}`);
+    if (written.refused !== 'status')
+        throw new NotFoundError(`${d.fn.close}: ${d.label} ${id} not found after UPDATE`);
+    const closable = d.closableFrom.join(' or ');
+    throw new ConflictError(`${d.fn.close}: ${d.label} ${id} is ${d.closeRefusal ?? `not ${closable}`} (status='${written.status}'); only ${closable} ${d.plural} can be closed.`);
+}
+/** Retires one object; its mirror memory stays as saved. */
+export function closeObjectAt(hippoRoot, d, tenantId, id, actor) {
+    const close = closing(d, tenantId, actor);
+    return closed(d, tenantId, id, sqliteObjects(hippoRoot).closeObject(tenantId, d.kind, id, close));
+}
+export async function closeObject(objects, d, tenantId, id, actor) {
+    const close = closing(d, tenantId, actor);
+    return closed(d, tenantId, id, await objects.closeObject(tenantId, d.kind, id, close));
+}
+/** The memory a typed object writes beside its row, so recall finds the object. */
+export function objectMirror(hippoRoot, tenantId, source, text) {
+    return createMemory(text.content, {
+        tags: [source, ...text.tags],
+        layer: Layer.Semantic,
+        confidence: 'verified',
+        source,
+        baseHalfLifeDays: loadConfig(hippoRoot).defaultHalfLifeDays,
+        tenantId,
+    });
+}
+function objectSave(site, kind, draft) {
+    const mirror = objectMirror(site.hippoRoot, site.tenantId, kind, draft);
+    return { mirror, fields: draft.fields, supersedesId: draft.supersedesId, changeSummary: draft.changeSummary, actor: site.actor, at: draft.at };
+}
+function saved(d, tenantId, replaced, written) {
+    if (!isObjectRefusal(written))
+        return written;
+    switch (written.refused) {
+        case 'missing':
+            throw new NotFoundError(`${d.fn.save}: ${d.label} ${replaced} to supersede not found for tenant ${tenantId}`);
+        case 'status':
+            throw new ConflictError(`${d.fn.save}: ${d.label} ${replaced} is not active (status='${written.status}'); only active ${d.plural} can be superseded.`);
+        case 'raced':
+            throw new ConflictError(`${d.fn.save}: ${d.label} ${replaced} could not be superseded (no longer active or self-reference).`);
+        case 'vanished':
+            throw new Error(`${d.fn.save}: failed to reload saved ${d.label} row`);
+    }
+}
+/** Creates an object, or the version that replaces the one its options name, with its mirror memory in one write. */
+export function saveObjectAt(d, site, opts) {
+    assertTenantId(d.fn.save, site.tenantId);
+    const draft = d.draft(opts);
+    return saved(d, site.tenantId, draft.supersedesId, sqliteObjects(site.hippoRoot).saveObject(site.tenantId, d.kind, objectSave(site, d.kind, draft)));
+}
+export async function saveObject(objects, d, site, opts) {
+    assertTenantId(d.fn.save, site.tenantId);
+    const draft = d.draft(opts);
+    return saved(d, site.tenantId, draft.supersedesId, await objects.saveObject(site.tenantId, d.kind, objectSave(site, d.kind, draft)));
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/objects/policies.d.ts

@@ -0,0 +1,60 @@
+/** 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';
+import type { Objects } from '../store/port.js';
+export type { Policy, PolicyStatus } from '../store/object-types.js';
+export declare const VALID_POLICY_STATES: ReadonlySet<PolicyStatus>;
+export interface SavePolicyOpts {
+    policyName: string;
+    policyText: string;
+    /** ISO-8601; normalized to canonical datetime. Defaults to now when omitted. */
+    validFrom?: string;
+    /** ISO-8601; normalized; must be > validFrom. null/undefined = open-ended. */
+    validTo?: string;
+    /** The delta note for a supersession; ignored (stored NULL) on a fresh create. */
+    changeSummary?: string;
+    /** Table id of an ACTIVE policy this new version supersedes. */
+    supersedesPolicyId?: number;
+    /** Extra memory tags merged after ['policy']. */
+    extraTags?: string[];
+}
+export interface ListPoliciesOpts {
+    status?: PolicyStatus;
+    limit?: number;
+    /** Resume after this row: the position the previous page ended on. */
+    after?: KeysetPosition;
+}
+/** 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;
+/** 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 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 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 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;
+}): Policy[];
+/** `loadPoliciesAsOf` over a served store's group. */
+export declare function policiesAsOf(objects: Objects, tenantId: string, asOfDate: string, opts?: {
+    name?: string;
+    limit?: number;
+}): Promise<Policy[]>;
+//# sourceMappingURL=policies.d.ts.map