hippo-memory 1.69.0 → 1.70.0

package/dist/{incidents.d.ts → objects/incidents.d.ts}

@@ -15,36 +15,22 @@
  *
  * 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/decisions.ts).
+ * v30 decisions pattern (src/objects/decisions.ts).
  *
- * Dual-write atomicity: `saveIncident` writes the memory + incidents row inside
- * writeEntry's SAVEPOINT 'write_entry' (store.ts) via the afterWrite hook, so a
- * failure in any step rolls all of them back. Pattern matches saveDecision.
+ * 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.
  */
-import { type KeysetPosition } from './keyset.js';
-export type IncidentStatus = 'open' | 'resolved' | 'closed';
+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 Incident {
-    id: number;
-    /** Nullable: ON DELETE SET NULL lets memory deletion (forget / consolidate /
-     *  archive) proceed without breaking the incident row. */
-    memoryId: string | null;
-    tenantId: string;
-    incidentText: string;
-    context: string | null;
-    status: IncidentStatus;
-    /** Set only when status === 'resolved'. */
-    resolutionText: string | null;
-    resolvedAt: string | null;
-    closedAt: string | null;
-    /** Linked receipts: memory ids that are this incident's evidence. */
-    linkedMemoryIds: string[];
-    createdAt: string;
-}
 export interface SaveIncidentOpts {
     incidentText: string;
     context?: string;
@@ -61,31 +47,18 @@ export interface ListIncidentsOpts {
     /** Resume after this row: the position the previous page ended on. */
     after?: KeysetPosition;
 }
-/**
- * Create an incident. Writes the memory mirror + the incidents row atomically
- * inside writeEntry's SAVEPOINT 'write_entry'.
- *
- * The memory mirror: tags ['incident', ...extraTags], source 'incident',
- * confidence 'verified', the half-life objectHalfLifeDays picks, content =
- * "<text>\n\nContext: <context>" when context is given.
- *
- * linked_memory_ids are validated BEFORE insert: each must exist in the SAME
- * tenant. A cross-tenant or nonexistent id throws and rolls back the whole
- * write. The validated ids are stored as JSON.stringify(validated).
- */
+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;
-/**
- * Resolve an open incident (open -> resolved). Records resolution_text +
- * resolved_at; the incident stays on record. CAS guard: WHERE status='open';
- * 0 changes distinguishes not-found from not-open so callers surface the right
- * error. Emits incident_resolve.
- */
+/** `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 (open|resolved -> closed).
- * Updates closed_at only; the memory mirror is not mutated. CAS guard: WHERE
- * status IN ('open','resolved'); 0 changes distinguishes not-found from
- * wrong-state. Emits incident_close.
+ * Updates 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;

package/dist/objects/incidents.js

@@ -0,0 +1,130 @@
+/**
+ * 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.
+ */
+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',
+    '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 (open|resolved -> closed).
+ * Updates 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 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).
+ */
+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/{policies.d.ts → objects/policies.d.ts}

@@ -34,33 +34,14 @@
  * otherwise make a same-day policy invisible).
  *
  * Dual-write atomicity: `savePolicy` writes the memory + policies row (and, on
- * supersede, the predecessor's UPDATE) inside writeEntry's SAVEPOINT.
+ * supersede, the predecessor's UPDATE) in the `objects` store group's one transaction.
  */
-import { type KeysetPosition } from './keyset.js';
-export type PolicyStatus = 'active' | 'superseded' | 'closed';
+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 Policy {
-    id: number;
-    /** Nullable: ON DELETE SET NULL lets memory deletion proceed without breaking
-     *  the policy row. */
-    memoryId: string | null;
-    tenantId: string;
-    policyName: string;
-    policyText: string;
-    /** Canonical ISO-8601 datetime; when the policy takes effect. Always set. */
-    validFrom: string;
-    /** Canonical ISO-8601 datetime; when it expires. null = open-ended. */
-    validTo: string | null;
-    /** Server-derived: 1 on a fresh create, predecessor.version + 1 on supersede. */
-    version: number;
-    status: PolicyStatus;
-    supersededBy: number | null;
-    supersededAt: string | null;
-    /** The per-version delta note; set on a successor row only (NULL on a v1). */
-    changeSummary: string | null;
-    closedAt: string | null;
-    createdAt: string;
-}
 export interface SavePolicyOpts {
     policyName: string;
     policyText: string;
@@ -98,13 +79,14 @@ export declare function validatePolicyDates(validFromRaw: string | undefined, va
     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 atomically inside writeEntry's SAVEPOINT.
+ * 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
- * SAVEPOINT; the new version = predecessor.version + 1 (server-derived).
+ * transaction; the new version = predecessor.version + 1 (server-derived).
  */
 export declare function savePolicy(hippoRoot: string, tenantId: string, opts: SavePolicyOpts, actor?: string): Policy;
 /**
@@ -148,4 +130,9 @@ export declare function loadPoliciesAsOf(hippoRoot: string, tenantId: string, as
     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

package/dist/objects/policies.js

@@ -0,0 +1,189 @@
+/**
+ * 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.
+ */
+import { BadRequestError } from '../core/api-errors.js';
+import { assertTenantId } from '../store/tenant.js';
+import { closeObjectAt, listObjectsAt, objectByIdAt, saveObjectAt } from './lifecycle.js';
+import { sqliteObjects } from '../store/sqlite/objects-group.js';
+// ---------------------------------------------------------------------------
+// Domain types
+// ---------------------------------------------------------------------------
+export const VALID_POLICY_STATES = new Set([
+    'active',
+    'superseded',
+    'closed',
+]);
+// ---------------------------------------------------------------------------
+// Date normalization + validation (the bi-temporal correctness core)
+// ---------------------------------------------------------------------------
+/**
+ * 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.)
+ */
+export function normalizePolicyDate(input, label = 'date') {
+    const d = new Date(input);
+    if (Number.isNaN(d.getTime())) {
+        throw new BadRequestError(`policy: invalid ${label} "${input}" (expected an ISO-8601 date or datetime)`);
+    }
+    return d.toISOString();
+}
+/**
+ * Normalize valid_from (defaulting to `nowIso` when undefined) + valid_to (null
+ * when undefined), then enforce valid_to > valid_from. Returns the canonical pair.
+ */
+export function validatePolicyDates(validFromRaw, validToRaw, nowIso) {
+    const validFrom = validFromRaw !== undefined ? normalizePolicyDate(validFromRaw, 'valid_from') : nowIso;
+    const validTo = validToRaw !== undefined && validToRaw !== null
+        ? normalizePolicyDate(validToRaw, 'valid_to')
+        : null;
+    if (validTo !== null && validTo <= validFrom) {
+        throw new BadRequestError(`policy: valid_to (${validTo}) must be strictly after valid_from (${validFrom})`);
+    }
+    return { validFrom, validTo };
+}
+/** Recall-surface content for the memory mirror: name + rule + effective range. */
+function buildPolicyContent(policyName, policyText, validFrom, validTo) {
+    const range = validTo ? `${validFrom} to ${validTo}` : `${validFrom} onward`;
+    return `${policyName}\n\n${policyText}\n\nEffective: ${range}`;
+}
+export const POLICY = {
+    kind: 'policy',
+    label: 'policy',
+    plural: 'policies',
+    fn: { get: 'loadPolicyById', close: 'closePolicy', list: 'loadPolicies', save: 'savePolicy' },
+    states: VALID_POLICY_STATES,
+    closableFrom: ['active'],
+    draft(opts) {
+        if (!opts.policyName || opts.policyName.trim().length === 0) {
+            throw new BadRequestError('savePolicy: policyName is required');
+        }
+        if (!opts.policyText || opts.policyText.trim().length === 0) {
+            throw new BadRequestError('savePolicy: policyText is required');
+        }
+        const at = new Date().toISOString();
+        // valid_from defaults to the creation instant. A date-only as-of is widened to end-of-day on the read side,
+        // because backdating valid_from to midnight would report the policy in force earlier that day.
+        const { validFrom, validTo } = validatePolicyDates(opts.validFrom, opts.validTo, at);
+        return {
+            fields: { policyName: opts.policyName, policyText: opts.policyText, validFrom, validTo },
+            content: buildPolicyContent(opts.policyName, opts.policyText, validFrom, validTo),
+            tags: opts.extraTags ?? [],
+            supersedesId: opts.supersedesPolicyId,
+            changeSummary: opts.changeSummary,
+            at,
+        };
+    },
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * 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).
+ */
+export function savePolicy(hippoRoot, tenantId, opts, actor = 'cli') {
+    return saveObjectAt(POLICY, { hippoRoot, tenantId, actor }, opts);
+}
+/**
+ * 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.
+ */
+export function closePolicy(hippoRoot, tenantId, id, actor = 'cli') {
+    return closeObjectAt(hippoRoot, POLICY, tenantId, id, actor);
+}
+export function loadPolicyById(hippoRoot, tenantId, id) {
+    return objectByIdAt(hippoRoot, POLICY, tenantId, id);
+}
+export function loadPolicies(hippoRoot, tenantId, opts = {}) {
+    return listObjectsAt(hippoRoot, POLICY, tenantId, opts);
+}
+export function loadActivePolicies(hippoRoot, tenantId, opts = {}) {
+    return loadPolicies(hippoRoot, tenantId, { status: 'active', limit: opts.limit });
+}
+/**
+ * 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.
+ */
+export function loadPoliciesAsOf(hippoRoot, tenantId, asOfDate, opts = {}) {
+    return sqliteObjects(hippoRoot).policiesInForce(tenantId, inForceQuery(tenantId, asOfDate, opts));
+}
+/** `loadPoliciesAsOf` over a served store's group. */
+export async function policiesAsOf(objects, tenantId, asOfDate, opts = {}) {
+    return objects.policiesInForce(tenantId, inForceQuery(tenantId, asOfDate, opts));
+}
+/** The as-of read, checked before a store is asked. */
+function inForceQuery(tenantId, asOfDate, opts) {
+    assertTenantId('loadPoliciesAsOf', tenantId);
+    // A bare date means the whole of that day, so it reads as the day's last instant; a datetime is used as given.
+    const asOf = /^\d{4}-\d{2}-\d{2}$/.test(asOfDate.trim())
+        ? normalizePolicyDate(`${asOfDate.trim()}T23:59:59.999Z`, 'asOfDate')
+        : normalizePolicyDate(asOfDate, 'asOfDate');
+    return { asOf, name: opts.name, limit: opts.limit ?? 100 };
+}
+//# sourceMappingURL=policies.js.map