hippo-memory 1.70.0 → 1.71.0

package/dist/objects/policies.js

@@ -1,64 +1,17 @@
-/**
- * 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 { 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.)
- */
+/** 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 function normalizePolicyDate(input, label = 'date') {
     const d = new Date(input);
     if (Number.isNaN(d.getTime())) {
@@ -66,10 +19,7 @@ export function normalizePolicyDate(input, label = 'date') {
     }
     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.
- */
+/** Normalise valid_from (default `nowIso`) and valid_to (default null), then enforce valid_to > valid_from. */
 export function validatePolicyDates(validFromRaw, validToRaw, nowIso) {
     const validFrom = validFromRaw !== undefined ? normalizePolicyDate(validFromRaw, 'valid_from') : nowIso;
     const validTo = validToRaw !== undefined && validToRaw !== null
@@ -113,25 +63,12 @@ export const POLICY = {
         };
     },
 };
-// ---------------------------------------------------------------------------
-// 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).
- */
+/** 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 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.
- */
+/** Close (retire) an active policy with no successor; CAS on status='active', a superseded row is terminal. */
 export function closePolicy(hippoRoot, tenantId, id, actor = 'cli') {
     return closeObjectAt(hippoRoot, POLICY, tenantId, id, actor);
 }
@@ -144,32 +81,8 @@ export function loadPolicies(hippoRoot, 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.
- */
+/** 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 function loadPoliciesAsOf(hippoRoot, tenantId, asOfDate, opts = {}) {
     return sqliteObjects(hippoRoot).policiesInForce(tenantId, inForceQuery(tenantId, asOfDate, opts));
 }

package/dist/objects/processes.d.ts

@@ -1,34 +1,6 @@
-/**
- * Process first-class object.
- *
- * A `process` is a "living process map": a named, ordered list of steps that
- * evolves over time. Unlike `incident` (open->resolved->closed, no supersede),
- * `process` REUSES the `decision` supersede path as its delta mechanism: a
- * process evolves by being superseded by a NEW VERSION that records what
- * changed (`change_summary`) and the full new state (`steps`), carrying a
- * server-derived `version` counter. The version chain (walk `superseded_by`)
- * is the changelog. Computed structural step-diffing is a deferred v2 read-side
- * feature; the row stores enough to reconstruct any delta
- * (predecessor.steps + successor.steps + change_summary).
- *
- * The `processes` table is the source of truth: a process stays `active`
- * regardless of memory decay. A memory row mirrors the process for recall but
- * is NOT canonical — memory_id is NULLABLE with ON DELETE SET NULL so
- * forget/consolidate/archive gracefully orphans the process row.
- *
- * Lifecycle: active -> superseded (a newer version replaces it; superseded_by
- * points to the successor) or active -> closed (retired with no successor;
- * only an active head closes).
- *
- * Tenant scoping: every helper requires tenantId. BEFORE INSERT/UPDATE triggers
- * enforce processes.tenant_id == the referenced memory's tenant_id, and a
- * superseded_by same-tenant trigger makes cross-tenant supersession
- * unrepresentable. Mirrors the v30 decisions pattern (src/objects/decisions.ts).
- *
- * Dual-write atomicity: `saveProcess` hands the memory and the process to the
- * `objects` store group, which commits them (and, when superseding, the
- * predecessor's UPDATE) together, so a failure in any step rolls all of them back.
- */
+/** Process object: a named, ordered list of `steps` that evolves by supersession, each version recording `change_summary` and a server-derived `version`.
+ *  The `processes` table is the source of truth; the memory mirror (memory_id NULLABLE, ON DELETE SET NULL) is for recall.
+ *  Structural step-diffing is a deferred read-side feature; the version chain is the changelog. */
 import type { KeysetPosition } from '../util/keyset.js';
 import { type JsonValue } from '../util/json.js';
 import type { SavableDescriptor } from './descriptor.js';
@@ -55,30 +27,13 @@ export interface ListProcessesOpts {
     /** Resume after this row: the position the previous page ended on. */
     after?: KeysetPosition;
 }
-/**
- * Validate + normalise the steps body. Returns the trimmed step strings
- * (trim-then-store, so ' x ' is stored as 'x'). Throws on a non-array, a
- * non-string / empty element, or a cap breach. Mirrors the incident DoS-cap
- * discipline.
- */
+/** Validate and trim the steps body; throws on a non-array, a non-string or empty element, or a cap breach. */
 export declare function validateProcessSteps(steps: JsonValue): string[];
 export declare const PROCESS: SavableDescriptor<'process', SaveProcessOpts>;
-/**
- * Create a process (or a new version that supersedes an existing one). Writes
- * the memory mirror + the processes row in the `objects` store group's one
- * transaction. When supersedesProcessId is given, the referenced ACTIVE row is
- * preflighted (status + version) BEFORE the INSERT, then UPDATEd -> superseded in
- * the SAME transaction (CAS: WHERE status='active' AND id != <new id>; throws on
- * changes===0 so a duplicate supersede aborts the whole write). The new row's
- * version = predecessor.version + 1 (server-derived); change_summary carries the
- * delta note. A fresh create has version 1 and change_summary NULL.
- */
+/** Create a process, or a new version superseding an existing one, in the `objects` store group's one transaction.
+ *  The supersede CAS (WHERE status='active' AND id != <new id>) throws on changes===0 so a duplicate supersede aborts the write. */
 export declare function saveProcess(hippoRoot: string, tenantId: string, opts: SaveProcessOpts, actor?: string): Process;
-/**
- * Close (retire) an active process with no successor. Updates the processes row
- * only; the memory mirror is not mutated. A superseded row is already
- * terminal in the chain and cannot be closed.
- */
+/** Close (retire) an active process with no successor; a superseded row cannot be closed. */
 export declare function closeProcess(hippoRoot: string, tenantId: string, id: number, actor?: string): Process;
 export declare function loadProcessById(hippoRoot: string, tenantId: string, id: number): Process | null;
 export declare function loadProcesses(hippoRoot: string, tenantId: string, opts?: ListProcessesOpts): Process[];

package/dist/objects/processes.js

@@ -1,40 +1,9 @@
-/**
- * Process first-class object.
- *
- * A `process` is a "living process map": a named, ordered list of steps that
- * evolves over time. Unlike `incident` (open->resolved->closed, no supersede),
- * `process` REUSES the `decision` supersede path as its delta mechanism: a
- * process evolves by being superseded by a NEW VERSION that records what
- * changed (`change_summary`) and the full new state (`steps`), carrying a
- * server-derived `version` counter. The version chain (walk `superseded_by`)
- * is the changelog. Computed structural step-diffing is a deferred v2 read-side
- * feature; the row stores enough to reconstruct any delta
- * (predecessor.steps + successor.steps + change_summary).
- *
- * The `processes` table is the source of truth: a process stays `active`
- * regardless of memory decay. A memory row mirrors the process for recall but
- * is NOT canonical — memory_id is NULLABLE with ON DELETE SET NULL so
- * forget/consolidate/archive gracefully orphans the process row.
- *
- * Lifecycle: active -> superseded (a newer version replaces it; superseded_by
- * points to the successor) or active -> closed (retired with no successor;
- * only an active head closes).
- *
- * Tenant scoping: every helper requires tenantId. BEFORE INSERT/UPDATE triggers
- * enforce processes.tenant_id == the referenced memory's tenant_id, and a
- * superseded_by same-tenant trigger makes cross-tenant supersession
- * unrepresentable. Mirrors the v30 decisions pattern (src/objects/decisions.ts).
- *
- * Dual-write atomicity: `saveProcess` hands the memory and the process to the
- * `objects` store group, which commits them (and, when superseding, the
- * predecessor's UPDATE) together, so a failure in any step rolls all of them back.
- */
+/** Process object: a named, ordered list of `steps` that evolves by supersession, each version recording `change_summary` and a server-derived `version`.
+ *  The `processes` table is the source of truth; the memory mirror (memory_id NULLABLE, ON DELETE SET NULL) is for recall.
+ *  Structural step-diffing is a deferred read-side feature; the version chain is the changelog. */
 import { BadRequestError } from '../core/api-errors.js';
 import { isJsonString } from '../util/json.js';
 import { closeObjectAt, listObjectsAt, objectByIdAt, saveObjectAt } from './lifecycle.js';
-// ---------------------------------------------------------------------------
-// Domain types
-// ---------------------------------------------------------------------------
 export const VALID_PROCESS_STATES = new Set([
     'active',
     'superseded',
@@ -43,15 +12,7 @@ export const VALID_PROCESS_STATES = new Set([
 /** DoS / abuse caps on the steps body (untrusted at the HTTP/SDK boundary). */
 export const MAX_PROCESS_STEPS = 200;
 export const MAX_PROCESS_STEP_LEN = 2000;
-// ---------------------------------------------------------------------------
-// steps validation (untrusted input)
-// ---------------------------------------------------------------------------
-/**
- * Validate + normalise the steps body. Returns the trimmed step strings
- * (trim-then-store, so ' x ' is stored as 'x'). Throws on a non-array, a
- * non-string / empty element, or a cap breach. Mirrors the incident DoS-cap
- * discipline.
- */
+/** Validate and trim the steps body; throws on a non-array, a non-string or empty element, or a cap breach. */
 export function validateProcessSteps(steps) {
     if (!Array.isArray(steps)) {
         throw new BadRequestError('saveProcess: steps must be an array of strings');
@@ -110,27 +71,12 @@ export const PROCESS = {
         };
     },
 };
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Create a process (or a new version that supersedes an existing one). Writes
- * the memory mirror + the processes row in the `objects` store group's one
- * transaction. When supersedesProcessId is given, the referenced ACTIVE row is
- * preflighted (status + version) BEFORE the INSERT, then UPDATEd -> superseded in
- * the SAME transaction (CAS: WHERE status='active' AND id != <new id>; throws on
- * changes===0 so a duplicate supersede aborts the whole write). The new row's
- * version = predecessor.version + 1 (server-derived); change_summary carries the
- * delta note. A fresh create has version 1 and change_summary NULL.
- */
+/** Create a process, or a new version superseding an existing one, in the `objects` store group's one transaction.
+ *  The supersede CAS (WHERE status='active' AND id != <new id>) throws on changes===0 so a duplicate supersede aborts the write. */
 export function saveProcess(hippoRoot, tenantId, opts, actor = 'cli') {
     return saveObjectAt(PROCESS, { hippoRoot, tenantId, actor }, opts);
 }
-/**
- * Close (retire) an active process with no successor. Updates the processes row
- * only; the memory mirror is not mutated. A superseded row is already
- * terminal in the chain and cannot be closed.
- */
+/** Close (retire) an active process with no successor; a superseded row cannot be closed. */
 export function closeProcess(hippoRoot, tenantId, id, actor = 'cli') {
     return closeObjectAt(hippoRoot, PROCESS, tenantId, id, actor);
 }

package/dist/objects/project-briefs.d.ts

@@ -1,25 +1,6 @@
-/**
- * Project_brief first-class object.
- *
- * A `project_brief` is the living, repo-scoped summary of a repository's state: a
- * `summary` body scoped to a `repo`, evolving via the supersede delta lifecycle.
- * "Auto-refreshes from receipts" is scoped to a DETERMINISTIC (no-LLM) assembler:
- * `refreshBrief` gathers the repo's recent receipts (memory rows tagged
- * `path:<repo>`) and assembles them into the brief body. The distinguishing
- * capability is therefore the refresh assembler (analog of skill's export
- * renderer), not an LLM/async pipeline (deferred).
- *
- * Reuses the skill/process supersede machinery verbatim (superseded_by self-FK +
- * CAS + INSERT-preflight + server-derived version + change_summary + supersede
- * tenant-match trigger). It DROPS skill's `skill_name`/`trigger_text` and ADDS
- * `repo` (the repo-scoping dimension) + `summary` (the brief body).
- *
- * The `project_briefs` 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 newer version replaces it) or active ->
- * closed (retired).
- */
+/** Project_brief object: the living, repo-scoped `summary` of a repository, evolving via supersession.
+ *  `refreshBrief` assembles recent `path:<repo>` receipts with a deterministic (no-LLM) assembler; an LLM pipeline is deferred.
+ *  The `project_briefs` 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 ObjectSaveSite } from './lifecycle.js';
@@ -46,9 +27,8 @@ export interface SaveProjectBriefOpts {
     supersedesBriefId?: number;
     /** Extra memory tags merged after ['project_brief']. */
     extraTags?: string[];
-    /** Internal: set by refreshBrief to the receipt count so the audit metadata can
-     *  mark the write as an auto-refresh (vs a manual supersede) WITHOUT a 4th audit
-     *  op. Not part of the public CLI/HTTP surface. */
+    /** Internal: set by refreshBrief to the receipt count so audit metadata marks the write as an auto-refresh
+     *  without a 4th audit op. Not part of the CLI/HTTP surface. */
     refreshReceiptCount?: number;
 }
 export interface ListProjectBriefsOpts {
@@ -60,39 +40,14 @@ export interface ListProjectBriefsOpts {
     after?: KeysetPosition;
 }
 export declare const PROJECT_BRIEF: SavableDescriptor<'project_brief', SaveProjectBriefOpts>;
-/**
- * Create a project_brief (or a new version that supersedes an existing one). Writes
- * the memory mirror + the project_briefs row in the `objects` store group's one
- * transaction. When supersedesBriefId 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 project_brief, or a new version superseding an existing one, in the `objects` store group's one transaction. */
 export declare function saveProjectBrief(hippoRoot: string, tenantId: string, opts: SaveProjectBriefOpts, actor?: string): ProjectBrief;
-/**
- * Close (retire) an active brief. A superseded row is terminal.
- */
+/** Close (retire) an active brief; a superseded row is terminal. */
 export declare function closeProjectBrief(hippoRoot: string, tenantId: string, id: number, actor?: string): ProjectBrief;
 export declare function loadProjectBriefById(hippoRoot: string, tenantId: string, id: number): ProjectBrief | null;
 export declare function loadProjectBriefs(hippoRoot: string, tenantId: string, opts?: ListProjectBriefsOpts): ProjectBrief[];
-/**
- * The repo's CURRENT active brief, or null. By convention there is one active brief
- * per (tenant, repo); if an operator created more than one (the DB does not prevent
- * it, consistent with every other first-class object), the MOST-RECENT active row wins.
- */
-export declare function loadActiveBriefForRepo(hippoRoot: string, tenantId: string, repo: string): ProjectBrief | null;
-/**
- * Assemble the repo's recent receipts into a deterministic markdown digest, and
- * return it WITH the receipt count (the count feeds refreshBrief's change_summary +
- * audit metadata). NO LLM. Always returns a non-empty, valid summary (a brief
- * `summary` is NOT NULL), including the zero-receipts case.
- *
- * A "receipt" = a tenant memory row carrying the repo's `path:<repo>` tag. The
- * brief's OWN memory mirror (source='project_brief') is excluded so a brief never
- * becomes its own receipt on the next refresh. The match is against the JSON-array
- * serialization (each element is a double-quoted string `"path:hippo"`); the
- * surrounding quotes are load-bearing — they stop `hip` matching `path:hippo`.
- * `repo` is LIKE-escaped + parameterized (operator-supplied; security.md).
- */
+/** Assemble the repo's recent receipts into a deterministic markdown digest and return it with the receipt count; never empty (summary is NOT NULL).
+ *  The brief's own mirror (source='project_brief') is excluded; the quotes in the JSON-array LIKE are load-bearing (`hip` must not match `path:hippo`). */
 export declare function assembleBriefFromReceipts(hippoRoot: string, tenantId: string, repo: string): BriefDigest;
 /** `assembleBriefFromReceipts` over a served store's group. */
 export declare function briefFromReceipts(objects: Objects, tenantId: string, repo: string): Promise<BriefDigest>;
@@ -100,7 +55,8 @@ export interface BriefDigest {
     markdown: string;
     receiptCount: number;
 }
-/** Saves a new version of the repo's brief from its receipts. The receipts are read before the save's transaction, so a receipt written in between shows in the next refresh. */
+/** Saves a new version of the repo's brief from its receipts. The receipts are read before
+ * the save's transaction, so a receipt written in between shows in the next refresh. */
 export declare function refreshBrief(hippoRoot: string, tenantId: string, repo: string, actor?: string): ProjectBrief;
 /** `refreshBrief` over a served store's group. */
 export declare function refreshedBrief(objects: Objects, site: ObjectSaveSite, repo: string): Promise<ProjectBrief>;

package/dist/objects/project-briefs.js

@@ -1,33 +1,11 @@
-/**
- * Project_brief first-class object.
- *
- * A `project_brief` is the living, repo-scoped summary of a repository's state: a
- * `summary` body scoped to a `repo`, evolving via the supersede delta lifecycle.
- * "Auto-refreshes from receipts" is scoped to a DETERMINISTIC (no-LLM) assembler:
- * `refreshBrief` gathers the repo's recent receipts (memory rows tagged
- * `path:<repo>`) and assembles them into the brief body. The distinguishing
- * capability is therefore the refresh assembler (analog of skill's export
- * renderer), not an LLM/async pipeline (deferred).
- *
- * Reuses the skill/process supersede machinery verbatim (superseded_by self-FK +
- * CAS + INSERT-preflight + server-derived version + change_summary + supersede
- * tenant-match trigger). It DROPS skill's `skill_name`/`trigger_text` and ADDS
- * `repo` (the repo-scoping dimension) + `summary` (the brief body).
- *
- * The `project_briefs` 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 newer version replaces it) or active ->
- * closed (retired).
- */
+/** Project_brief object: the living, repo-scoped `summary` of a repository, evolving via supersession.
+ *  `refreshBrief` assembles recent `path:<repo>` receipts with a deterministic (no-LLM) assembler; an LLM pipeline is deferred.
+ *  The `project_briefs` table is the source of truth; the memory mirror (memory_id NULLABLE, ON DELETE SET NULL) is for recall. */
 import { BadRequestError } from '../core/api-errors.js';
 import { assertTenantId } from '../store/tenant.js';
 import { checkText, requireLine } from './fields.js';
 import { closeObjectAt, listObjectsAt, objectByIdAt, saveObject, saveObjectAt } from './lifecycle.js';
 import { sqliteObjects } from '../store/sqlite/objects-group.js';
-// ---------------------------------------------------------------------------
-// Domain types
-// ---------------------------------------------------------------------------
 export const VALID_BRIEF_STATES = new Set([
     'active',
     'superseded',
@@ -79,22 +57,11 @@ export const PROJECT_BRIEF = {
 function buildBriefContent(repo, summary) {
     return `${repo}\n\n${summary}`;
 }
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Create a project_brief (or a new version that supersedes an existing one). Writes
- * the memory mirror + the project_briefs row in the `objects` store group's one
- * transaction. When supersedesBriefId 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 project_brief, or a new version superseding an existing one, in the `objects` store group's one transaction. */
 export function saveProjectBrief(hippoRoot, tenantId, opts, actor = 'cli') {
     return saveObjectAt(PROJECT_BRIEF, { hippoRoot, tenantId, actor }, opts);
 }
-/**
- * Close (retire) an active brief. A superseded row is terminal.
- */
+/** Close (retire) an active brief; a superseded row is terminal. */
 export function closeProjectBrief(hippoRoot, tenantId, id, actor = 'cli') {
     return closeObjectAt(hippoRoot, PROJECT_BRIEF, tenantId, id, actor);
 }
@@ -104,12 +71,8 @@ export function loadProjectBriefById(hippoRoot, tenantId, id) {
 export function loadProjectBriefs(hippoRoot, tenantId, opts = {}) {
     return listObjectsAt(hippoRoot, PROJECT_BRIEF, tenantId, { status: opts.status, filter: opts.repo, limit: opts.limit, after: opts.after });
 }
-/**
- * The repo's CURRENT active brief, or null. By convention there is one active brief
- * per (tenant, repo); if an operator created more than one (the DB does not prevent
- * it, consistent with every other first-class object), the MOST-RECENT active row wins.
- */
-export function loadActiveBriefForRepo(hippoRoot, tenantId, repo) {
+/** The repo's current active brief, or null. The DB allows several active rows per (tenant, repo); the most recent wins. */
+function loadActiveBriefForRepo(hippoRoot, tenantId, repo) {
     assertTenantId('loadActiveBriefForRepo', tenantId);
     if (repo === '')
         return null;
@@ -119,9 +82,6 @@ export function loadActiveBriefForRepo(hippoRoot, tenantId, repo) {
 function newestActive(repo) {
     return { status: 'active', filter: repo, limit: 1 };
 }
-// ---------------------------------------------------------------------------
-// Refresh assembler (the distinguishing deliverable)
-// ---------------------------------------------------------------------------
 /** Single-line headline for a receipt: first non-empty line, newline-stripped,
  *  truncated. Deterministic + safe for the markdown bullet list. */
 function receiptHeadline(content) {
@@ -135,17 +95,8 @@ function receiptHeadline(content) {
 function receiptTag(normalizedRepo) {
     return `path:${normalizedRepo.toLowerCase()}`;
 }
-// NOTE on ordering: the `id DESC` tiebreak is lexical on a random-ish memory id
-// (e.g. `sem_<hex>`), NOT chronological — within the same `created` timestamp the
-// order is stable-but-arbitrary, not insertion order. `created DESC` is the real
-// recency ordering.
-//
-// Budget-aware assembly: the digest is the
-// brief `summary`, which saveProjectBrief caps at MAX_BRIEF_SUMMARY_LEN. The
-// receipt/headline caps (50 x ~200) could otherwise build an ~11KB body that the
-// store then REJECTS, breaking refresh for inputs within the advertised caps. So
-// include receipt lines newest-first only while they fit under the cap (reserving
-// slack for the header + an omission footer), and note the omitted remainder.
+// `id DESC` is a lexical tiebreak on a random-ish id, so same-`created` order is stable but arbitrary; `created DESC` is the recency order.
+// Receipt lines go newest-first only while they fit MAX_BRIEF_SUMMARY_LEN (reserving slack for header and omission footer), else the store rejects the body.
 function fitReceiptLines(receipts) {
     const buildReceiptLine = (r) => `- ${(r.created ?? '').slice(0, 10)} [${r.source}] ${receiptHeadline(r.content)}`;
     const receiptLines = [];
@@ -185,28 +136,15 @@ function renderBriefDigest(normalizedRepo, receiptCount, receiptLines) {
             lines.push(`_... ${omitted} more receipt(s) omitted (summary cap)._`);
         }
     }
-    // Belt-and-suspenders: the budget loop keeps us under the cap, but hard-clamp the
-    // joined string so the store's NOT-NULL/<=cap contract can never be violated even
-    // for a pathological single oversized line.
+    // Belt-and-suspenders: hard-clamp so the store's NOT-NULL/<=cap contract holds even for a single oversized line.
     let markdown = lines.join('\n');
     if (markdown.length > MAX_BRIEF_SUMMARY_LEN) {
         markdown = markdown.slice(0, MAX_BRIEF_SUMMARY_LEN);
     }
     return markdown;
 }
-/**
- * Assemble the repo's recent receipts into a deterministic markdown digest, and
- * return it WITH the receipt count (the count feeds refreshBrief's change_summary +
- * audit metadata). NO LLM. Always returns a non-empty, valid summary (a brief
- * `summary` is NOT NULL), including the zero-receipts case.
- *
- * A "receipt" = a tenant memory row carrying the repo's `path:<repo>` tag. The
- * brief's OWN memory mirror (source='project_brief') is excluded so a brief never
- * becomes its own receipt on the next refresh. The match is against the JSON-array
- * serialization (each element is a double-quoted string `"path:hippo"`); the
- * surrounding quotes are load-bearing — they stop `hip` matching `path:hippo`.
- * `repo` is LIKE-escaped + parameterized (operator-supplied; security.md).
- */
+/** Assemble the repo's recent receipts into a deterministic markdown digest and return it with the receipt count; never empty (summary is NOT NULL).
+ *  The brief's own mirror (source='project_brief') is excluded; the quotes in the JSON-array LIKE are load-bearing (`hip` must not match `path:hippo`). */
 export function assembleBriefFromReceipts(hippoRoot, tenantId, repo) {
     const normalizedRepo = requiredRepo('assembleBriefFromReceipts', tenantId, repo);
     return briefDigest(normalizedRepo, sqliteObjects(hippoRoot).briefReceipts(tenantId, receiptTag(normalizedRepo), MAX_BRIEF_RECEIPTS));
@@ -238,7 +176,8 @@ function refreshWrite(normalizedRepo, digest, active) {
         extraTags: [receiptTag(normalizedRepo)],
     };
 }
-/** Saves a new version of the repo's brief from its receipts. The receipts are read before the save's transaction, so a receipt written in between shows in the next refresh. */
+/** Saves a new version of the repo's brief from its receipts. The receipts are read before
+ * the save's transaction, so a receipt written in between shows in the next refresh. */
 export function refreshBrief(hippoRoot, tenantId, repo, actor = 'cli') {
     const normalizedRepo = requiredRepo('refreshBrief', tenantId, repo);
     const digest = assembleBriefFromReceipts(hippoRoot, tenantId, normalizedRepo);

package/dist/objects/skills.d.ts

@@ -1,26 +1,6 @@
-/**
- * Skills as a first-class, versioned object.
- *
- * A `skill` is a reusable, agent-followable capability: an `instructions` body
- * plus an optional `trigger` ("when to apply"), evolving via the supersede delta
- * lifecycle. "Executable" is scoped to an agent-followable INSTRUCTION that, once
- * exported into the agent's in-force rules (AGENTS.md / CLAUDE.md) via
- * `exportSkills`, is executed by the agent reading it. Literal code/command
- * execution is deferred (security; a future sandbox). The distinguishing
- * capability is therefore the EXPORT renderer, not a runtime.
- *
- * 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 skill's content is a single
- * `instructions` body) and ADDS `trigger` (stored in the `trigger_text` column -
- * `trigger` is a SQLite reserved keyword).
- *
- * The `skills` 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 newer version replaces it) or active ->
- * closed (retired). Export renders ACTIVE skills only.
- */
+/** Skill object: an agent-followable `instructions` body plus an optional `trigger`, evolving via supersession.
+ *  `exportSkills` renders ACTIVE skills into AGENTS.md / CLAUDE.md rules; running code from a skill is deferred (security).
+ *  `trigger` is stored in `trigger_text` because it is a SQLite reserved keyword. */
 import type { KeysetPosition } from '../util/keyset.js';
 import type { SavableDescriptor } from './descriptor.js';
 import type { Skill, SkillStatus } from '../store/object-types.js';
@@ -54,32 +34,17 @@ export interface ListSkillsOpts {
     after?: KeysetPosition;
 }
 export declare const SKILL: SavableDescriptor<'skill', SaveSkillOpts>;
-/**
- * Create a skill (or a new version that supersedes an existing one). Writes the
- * memory mirror + the skills row in the `objects` store group's one transaction. When
- * supersedesSkillId 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 skill, or a new version superseding an existing one, in the `objects` store group's one transaction. */
 export declare function saveSkill(hippoRoot: string, tenantId: string, opts: SaveSkillOpts, actor?: string): Skill;
-/**
- * Close (retire) an active skill. A superseded row is terminal.
- */
+/** Close (retire) an active skill; a superseded row is terminal. */
 export declare function closeSkill(hippoRoot: string, tenantId: string, id: number, actor?: string): Skill;
 export declare function loadSkillById(hippoRoot: string, tenantId: string, id: number): Skill | null;
 export declare function loadSkills(hippoRoot: string, tenantId: string, opts?: ListSkillsOpts): Skill[];
 export declare function loadActiveSkills(hippoRoot: string, tenantId: string, opts?: {
     limit?: number;
 }): Skill[];
-/**
- * Render the tenant's ACTIVE skills into ONE AGENTS.md / CLAUDE.md-style markdown
- * block (one H2 per skill, ordered by skill_name ASC for determinism), and RETURN
- * the string. Does NOT write any file. Returns '' when there are no active skills.
- *
- * skill_name is single-line (validated on save) so it cannot break the H2 header;
- * instructions are emitted verbatim (operator content). Bounded by MAX_EXPORT_SKILLS
- * active rows; each field is capped on save, so the rendered string is bounded.
- */
+/** Render the tenant's ACTIVE skills into one AGENTS.md / CLAUDE.md-style markdown block (H2 per skill, ordered by skill_name) and return it; writes no file.
+ *  Bounded by MAX_EXPORT_SKILLS rows; instructions are emitted verbatim. */
 export declare function exportSkills(hippoRoot: string, tenantId: string): string;
 /** `exportSkills` over a served store's group. */
 export declare function skillsMarkdown(objects: Objects, tenantId: string): Promise<string>;