hippo-memory 1.70.0 → 1.72.0

package/dist/objects/processes.d.ts

@@ -1,39 +1,11 @@
-/**
- * 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';
-import type { Process, ProcessStatus } from '../store/object-types.js';
-export type { Process, ProcessStatus } from '../store/object-types.js';
+import type { Process, ProcessStatus } from '../core/object-types.js';
+export type { Process, ProcessStatus } from '../core/object-types.js';
 export declare const VALID_PROCESS_STATES: ReadonlySet<ProcessStatus>;
 /** DoS / abuse caps on the steps body (untrusted at the HTTP/SDK boundary). */
 export declare const MAX_PROCESS_STEPS = 200;
@@ -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,31 +1,12 @@
-/**
- * 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';
-import type { BriefStatus, ProjectBrief } from '../store/object-types.js';
+import type { BriefStatus, ProjectBrief } from '../core/object-types.js';
 import type { Objects } from '../store/port.js';
-export type { BriefStatus, ProjectBrief } from '../store/object-types.js';
+export type { BriefStatus, ProjectBrief } from '../core/object-types.js';
 export declare const VALID_BRIEF_STATES: ReadonlySet<BriefStatus>;
 /** Field caps (untrusted at the HTTP/SDK boundary). summary is a body, so a larger
  *  cap than the 4096 short-field convention. */
@@ -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,12 @@
-/**
- * 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 { truncateWithEllipsis } from '../util/ellipsize.js';
 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 +58,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 +72,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,33 +83,19 @@ 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) {
     const firstLine = (content ?? '').split(/\r?\n/).find((l) => l.trim().length > 0) ?? '';
     const trimmed = firstLine.trim();
-    return trimmed.length > MAX_RECEIPT_HEADLINE_LEN
-        ? `${trimmed.slice(0, MAX_RECEIPT_HEADLINE_LEN)}...`
-        : trimmed;
+    return truncateWithEllipsis(trimmed, MAX_RECEIPT_HEADLINE_LEN);
 }
 /** The tag a memory of the repo carries; the store matches it whole, so `path:hip` never matches `path:hippo`. */
 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 +135,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 +175,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,31 +1,11 @@
-/**
- * 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';
+import type { Skill, SkillStatus } from '../core/object-types.js';
 import type { Objects } from '../store/port.js';
-export type { Skill, SkillStatus } from '../store/object-types.js';
+export type { Skill, SkillStatus } from '../core/object-types.js';
 export declare const VALID_SKILL_STATES: ReadonlySet<SkillStatus>;
 /** Field caps (untrusted at the HTTP/SDK boundary). instructions is a body, so a
  *  larger cap than the 4096 short-field convention. */
@@ -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>;

package/dist/objects/skills.js

@@ -1,34 +1,11 @@
-/**
- * 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 { BadRequestError } from '../core/api-errors.js';
 import { assertTenantId } from '../store/tenant.js';
 import { checkText, requireLine } from './fields.js';
 import { closeObjectAt, listObjectsAt, objectByIdAt, saveObjectAt } from './lifecycle.js';
 import { sqliteObjects } from '../store/sqlite/objects-group.js';
-// ---------------------------------------------------------------------------
-// Domain types
-// ---------------------------------------------------------------------------
 export const VALID_SKILL_STATES = new Set([
     'active',
     'superseded',
@@ -42,9 +19,6 @@ export const MAX_SKILL_TRIGGER_LEN = 1024;
 /** Aggregate bound on a single export render so the export body is never unbounded.
  *  Realistic active-skill counts are tens; 1000 is a generous bound. */
 export const MAX_EXPORT_SKILLS = 1000;
-// ---------------------------------------------------------------------------
-// Validation
-// ---------------------------------------------------------------------------
 /** The trigger as stored, or null for none. One line, because a newline would forge a heading inside the exported **When:** line. */
 function checkTrigger(trigger) {
     if (trigger === undefined || trigger === null || trigger.trim().length === 0)
@@ -57,9 +31,7 @@ function checkTrigger(trigger) {
     }
     return trigger;
 }
-/** Recall-surface content for the memory mirror: name + optional trigger +
- *  instructions. Named (mirrors buildProcessContent) so the recall surface is
- *  deterministic + unit-testable. */
+/** Recall-surface content for the memory mirror: name, optional trigger, instructions. */
 function buildSkillContent(skillName, instructions, trigger) {
     let content = skillName;
     if (trigger)
@@ -96,22 +68,11 @@ export const SKILL = {
         };
     },
 };
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * 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 function saveSkill(hippoRoot, tenantId, opts, actor = 'cli') {
     return saveObjectAt(SKILL, { hippoRoot, tenantId, actor }, opts);
 }
-/**
- * Close (retire) an active skill. A superseded row is terminal.
- */
+/** Close (retire) an active skill; a superseded row is terminal. */
 export function closeSkill(hippoRoot, tenantId, id, actor = 'cli') {
     return closeObjectAt(hippoRoot, SKILL, tenantId, id, actor);
 }
@@ -124,15 +85,8 @@ export function loadSkills(hippoRoot, tenantId, opts = {}) {
 export function loadActiveSkills(hippoRoot, tenantId, opts = {}) {
     return loadSkills(hippoRoot, tenantId, { status: 'active', limit: opts.limit });
 }
-/**
- * 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 function exportSkills(hippoRoot, tenantId) {
     assertTenantId('exportSkills', tenantId);
     return skillsBlock(sqliteObjects(hippoRoot).activeSkillsByName(tenantId, MAX_EXPORT_SKILLS));