hippo-memory 1.68.0 → 1.70.0

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

@@ -23,41 +23,21 @@
  * 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/decisions.ts).
+ * unrepresentable. Mirrors the v30 decisions pattern (src/objects/decisions.ts).
  *
- * Dual-write atomicity: `saveProcess` writes the memory + processes row (and,
- * when superseding, the predecessor's UPDATE) inside writeEntry's SAVEPOINT
- * 'write_entry' via the afterWrite hook, so a failure in any step rolls all of
- * them back. Pattern matches saveDecision (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.
  */
-import { type KeysetPosition } from './keyset.js';
-import type { JsonValue } from './json.js';
-export type ProcessStatus = 'active' | 'superseded' | 'closed';
+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';
 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;
 export declare const MAX_PROCESS_STEP_LEN = 2000;
-export interface Process {
-    id: number;
-    /** Nullable: ON DELETE SET NULL lets memory deletion (forget / consolidate /
-     *  archive) proceed without breaking the process row. */
-    memoryId: string | null;
-    tenantId: string;
-    processName: string;
-    description: string | null;
-    /** Ordered step list (the process body). Stored as a JSON array of strings. */
-    steps: string[];
-    /** Server-derived: 1 on a fresh create, predecessor.version + 1 on supersede. */
-    version: number;
-    status: ProcessStatus;
-    /** Successor process id; set only when status === 'superseded'. */
-    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 SaveProcessOpts {
     processName: string;
     steps: string[];
@@ -82,12 +62,13 @@ export interface ListProcessesOpts {
  * discipline.
  */
 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 atomically inside writeEntry's SAVEPOINT
- * 'write_entry'. When supersedesProcessId is given, the referenced ACTIVE row is
+ * 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 SAVEPOINT (CAS: WHERE status='active' AND id != <new id>; throws on
+ * 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.
@@ -95,8 +76,7 @@ export declare function validateProcessSteps(steps: JsonValue): string[];
 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. CAS guard: WHERE status='active'; 0
- * changes distinguishes not-found from not-active. A superseded row is already
+ * only; the memory mirror is not mutated. A superseded row is already
  * terminal in the chain and cannot be closed.
  */
 export declare function closeProcess(hippoRoot: string, tenantId: string, id: number, actor?: string): Process;

package/dist/objects/processes.js

@@ -0,0 +1,146 @@
+/**
+ * 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.
+ */
+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',
+    'closed',
+]);
+/** 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.
+ */
+export function validateProcessSteps(steps) {
+    if (!Array.isArray(steps)) {
+        throw new BadRequestError('saveProcess: steps must be an array of strings');
+    }
+    if (steps.length > MAX_PROCESS_STEPS) {
+        throw new BadRequestError(`saveProcess: steps exceeds the ${MAX_PROCESS_STEPS}-step cap (got ${steps.length})`);
+    }
+    const out = [];
+    for (let i = 0; i < steps.length; i++) {
+        const raw = steps[i];
+        if (!isJsonString(raw)) {
+            throw new BadRequestError(`saveProcess: step ${i + 1} is not a string`);
+        }
+        const trimmed = raw.trim();
+        if (trimmed.length === 0) {
+            throw new BadRequestError(`saveProcess: step ${i + 1} is empty`);
+        }
+        if (trimmed.length > MAX_PROCESS_STEP_LEN) {
+            throw new BadRequestError(`saveProcess: step ${i + 1} exceeds the ${MAX_PROCESS_STEP_LEN}-char cap`);
+        }
+        out.push(trimmed);
+    }
+    return out;
+}
+/** The recall-surface content for the memory mirror: name + numbered steps +
+ *  optional description, so `hippo recall` shows the process body. */
+function buildProcessContent(processName, steps, description) {
+    const numbered = steps.map((s, i) => `${i + 1}. ${s}`).join('\n');
+    let content = processName;
+    if (numbered)
+        content += `\n\n${numbered}`;
+    if (description)
+        content += `\n\nDescription: ${description}`;
+    return content;
+}
+export const PROCESS = {
+    kind: 'process',
+    label: 'process',
+    plural: 'processes',
+    fn: { get: 'loadProcessById', close: 'closeProcess', list: 'loadProcesses', save: 'saveProcess' },
+    states: VALID_PROCESS_STATES,
+    closableFrom: ['active'],
+    draft(opts) {
+        // The name is stored as written, so only a blank one is refused.
+        if (!opts.processName || opts.processName.trim().length === 0) {
+            throw new BadRequestError('saveProcess: processName is required');
+        }
+        const steps = validateProcessSteps(opts.steps);
+        return {
+            fields: { processName: opts.processName, description: opts.description, steps },
+            content: buildProcessContent(opts.processName, steps, opts.description),
+            tags: opts.extraTags ?? [],
+            supersedesId: opts.supersedesProcessId,
+            changeSummary: opts.changeSummary,
+            at: new Date().toISOString(),
+        };
+    },
+};
+// ---------------------------------------------------------------------------
+// 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.
+ */
+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.
+ */
+export function closeProcess(hippoRoot, tenantId, id, actor = 'cli') {
+    return closeObjectAt(hippoRoot, PROCESS, tenantId, id, actor);
+}
+export function loadProcessById(hippoRoot, tenantId, id) {
+    return objectByIdAt(hippoRoot, PROCESS, tenantId, id);
+}
+export function loadProcesses(hippoRoot, tenantId, opts = {}) {
+    return listObjectsAt(hippoRoot, PROCESS, tenantId, opts);
+}
+export function loadActiveProcesses(hippoRoot, tenantId, opts = {}) {
+    return loadProcesses(hippoRoot, tenantId, { status: 'active', limit: opts.limit });
+}
+//# sourceMappingURL=processes.js.map

package/dist/{project-briefs.d.ts → objects/project-briefs.d.ts}

@@ -20,8 +20,12 @@
  * Lifecycle: active -> superseded (a newer version replaces it) or active ->
  * closed (retired).
  */
-import { type KeysetPosition } from './keyset.js';
-export type BriefStatus = 'active' | 'superseded' | 'closed';
+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 { Objects } from '../store/port.js';
+export type { BriefStatus, ProjectBrief } from '../store/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. */
@@ -33,26 +37,6 @@ export declare const MAX_CHANGE_SUMMARY_LEN = 4096;
 export declare const MAX_BRIEF_RECEIPTS = 50;
 /** Truncate each receipt's headline in the assembled digest. */
 export declare const MAX_RECEIPT_HEADLINE_LEN = 200;
-export interface ProjectBrief {
-    id: number;
-    /** Nullable: ON DELETE SET NULL lets memory deletion proceed without breaking
-     *  the brief row. */
-    memoryId: string | null;
-    tenantId: string;
-    /** The repo identifier this brief is scoped to (e.g. `hippo`). */
-    repo: string;
-    /** The brief body. */
-    summary: string;
-    /** Server-derived: 1 on a fresh create, predecessor.version + 1 on supersede. */
-    version: number;
-    status: BriefStatus;
-    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 SaveProjectBriefOpts {
     repo: string;
     summary: string;
@@ -75,17 +59,17 @@ export interface ListProjectBriefsOpts {
     /** Resume after this row: the position the previous page ended on. */
     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 atomically inside writeEntry's
- * SAVEPOINT. When supersedesBriefId is given, the referenced ACTIVE row is
+ * 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 SAVEPOINT; the new version = predecessor.version + 1 (server-derived).
+ * in the same transaction; the new version = predecessor.version + 1 (server-derived).
  */
 export declare function saveProjectBrief(hippoRoot: string, tenantId: string, opts: SaveProjectBriefOpts, actor?: string): ProjectBrief;
 /**
- * Close (retire) an active brief. CAS guard WHERE status='active'; 0 changes
- * distinguishes not-found from not-active. 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;
@@ -109,20 +93,15 @@ export declare function loadActiveBriefForRepo(hippoRoot: string, tenantId: stri
  * surrounding quotes are load-bearing — they stop `hip` matching `path:hippo`.
  * `repo` is LIKE-escaped + parameterized (operator-supplied; security.md).
  */
-export declare function assembleBriefFromReceipts(hippoRoot: string, tenantId: string, repo: string): {
+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>;
+export interface BriefDigest {
     markdown: string;
     receiptCount: number;
-};
-/**
- * Auto-refresh the repo's brief from its receipts: assemble the digest, then create
- * a new version. If the repo already has an active brief it is superseded (the
- * change_summary records the auto-refresh + the audit metadata carries
- * `refreshed: true`); otherwise a v1 is created. Returns the new brief.
- *
- * The assemble (a read of `memories`) happens BEFORE writeEntry opens its SAVEPOINT;
- * a concurrent receipt write landing between the read and the brief write simply
- * appears in the NEXT refresh — the brief is a derived snapshot, not a transactional
- * aggregate, so no consistency invariant is violated.
- */
+}
+/** 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>;
 //# sourceMappingURL=project-briefs.d.ts.map

package/dist/objects/project-briefs.js

@@ -0,0 +1,255 @@
+/**
+ * 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).
+ */
+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',
+    'closed',
+]);
+/** Field caps (untrusted at the HTTP/SDK boundary). summary is a body, so a larger
+ *  cap than the 4096 short-field convention. */
+export const MAX_REPO_LEN = 256;
+export const MAX_BRIEF_SUMMARY_LEN = 8192;
+export const MAX_CHANGE_SUMMARY_LEN = 4096;
+/** Bound the receipts gathered per refresh (a refresh reads memories; cap the scan
+ *  + the rendered body). Realistic repos have far fewer recent receipts than this. */
+export const MAX_BRIEF_RECEIPTS = 50;
+/** Truncate each receipt's headline in the assembled digest. */
+export const MAX_RECEIPT_HEADLINE_LEN = 200;
+export const PROJECT_BRIEF = {
+    kind: 'project_brief',
+    label: 'brief',
+    plural: 'briefs',
+    fn: { get: 'loadProjectBriefById', close: 'closeProjectBrief', list: 'loadProjectBriefs', save: 'saveProjectBrief' },
+    states: VALID_BRIEF_STATES,
+    closableFrom: ['active'],
+    draft(opts) {
+        // The repo becomes a path tag on the refresh match and a heading in the digest, so it must be one line.
+        const repo = requireLine(opts.repo, MAX_REPO_LEN, {
+            required: 'saveProjectBrief: repo is required',
+            singleLine: 'saveProjectBrief: repo must be a single line (no newlines)',
+            tooLong: `saveProjectBrief: repo exceeds the ${MAX_REPO_LEN}-char cap`,
+        });
+        checkText(opts.summary, MAX_BRIEF_SUMMARY_LEN, {
+            required: 'saveProjectBrief: summary is required',
+            tooLong: `saveProjectBrief: summary exceeds the ${MAX_BRIEF_SUMMARY_LEN}-char cap`,
+        });
+        checkText(opts.changeSummary, MAX_CHANGE_SUMMARY_LEN, {
+            tooLong: `saveProjectBrief: changeSummary exceeds the ${MAX_CHANGE_SUMMARY_LEN}-char cap`,
+        });
+        return {
+            fields: { repo, summary: opts.summary, receiptCount: opts.refreshReceiptCount },
+            content: buildBriefContent(repo, opts.summary),
+            tags: opts.extraTags ?? [],
+            supersedesId: opts.supersedesBriefId,
+            changeSummary: opts.changeSummary,
+            at: new Date().toISOString(),
+        };
+    },
+};
+/** Recall-surface content for the memory mirror: repo + summary. Named (mirrors
+ *  buildSkillContent) so the recall surface is deterministic + unit-testable. */
+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).
+ */
+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.
+ */
+export function closeProjectBrief(hippoRoot, tenantId, id, actor = 'cli') {
+    return closeObjectAt(hippoRoot, PROJECT_BRIEF, tenantId, id, actor);
+}
+export function loadProjectBriefById(hippoRoot, tenantId, id) {
+    return objectByIdAt(hippoRoot, PROJECT_BRIEF, 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) {
+    assertTenantId('loadActiveBriefForRepo', tenantId);
+    if (repo === '')
+        return null;
+    return sqliteObjects(hippoRoot).listObjects(tenantId, 'project_brief', newestActive(repo))[0] ?? null;
+}
+/** An empty filter lists every repo, so the callers refuse an empty repo first. */
+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;
+}
+/** 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.
+function fitReceiptLines(receipts) {
+    const buildReceiptLine = (r) => `- ${(r.created ?? '').slice(0, 10)} [${r.source}] ${receiptHeadline(r.content)}`;
+    const receiptLines = [];
+    if (receipts.length > 0) {
+        // Header + "## Recent receipts" + a worst-case omission footer cost; keep slack
+        // so the joined markdown stays <= MAX_BRIEF_SUMMARY_LEN even after the footer.
+        const SLACK = 400;
+        let bodyBudget = MAX_BRIEF_SUMMARY_LEN - SLACK;
+        for (const r of receipts) {
+            const line = buildReceiptLine(r);
+            if (line.length + 1 > bodyBudget)
+                break;
+            receiptLines.push(line);
+            bodyBudget -= line.length + 1;
+        }
+    }
+    return receiptLines;
+}
+function renderBriefDigest(normalizedRepo, receiptCount, receiptLines) {
+    const omitted = receiptCount - receiptLines.length;
+    const lines = [];
+    lines.push(`# Project Brief: ${normalizedRepo}`);
+    lines.push('');
+    lines.push(omitted > 0
+        ? `_Auto-assembled from ${receiptLines.length} of ${receiptCount} receipt(s)._`
+        : `_Auto-assembled from ${receiptCount} receipt(s)._`);
+    lines.push('');
+    lines.push('## Recent receipts');
+    lines.push('');
+    if (receiptCount === 0) {
+        lines.push(`_No receipts found for ${normalizedRepo}._`);
+    }
+    else {
+        lines.push(...receiptLines);
+        if (omitted > 0) {
+            lines.push('');
+            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.
+    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).
+ */
+export function assembleBriefFromReceipts(hippoRoot, tenantId, repo) {
+    const normalizedRepo = requiredRepo('assembleBriefFromReceipts', tenantId, repo);
+    return briefDigest(normalizedRepo, sqliteObjects(hippoRoot).briefReceipts(tenantId, receiptTag(normalizedRepo), MAX_BRIEF_RECEIPTS));
+}
+/** `assembleBriefFromReceipts` over a served store's group. */
+export async function briefFromReceipts(objects, tenantId, repo) {
+    const normalizedRepo = requiredRepo('assembleBriefFromReceipts', tenantId, repo);
+    return briefDigest(normalizedRepo, await objects.briefReceipts(tenantId, receiptTag(normalizedRepo), MAX_BRIEF_RECEIPTS));
+}
+function requiredRepo(fn, tenantId, repo) {
+    assertTenantId(fn, tenantId);
+    const normalizedRepo = (repo ?? '').trim();
+    if (normalizedRepo.length === 0)
+        throw new BadRequestError(`${fn}: repo is required`);
+    return normalizedRepo;
+}
+function briefDigest(normalizedRepo, receipts) {
+    return { markdown: renderBriefDigest(normalizedRepo, receipts.length, fitReceiptLines(receipts)), receiptCount: receipts.length };
+}
+/** The version a refresh saves: a successor of the repo's active brief when it has one, else a first version. */
+function refreshWrite(normalizedRepo, digest, active) {
+    return {
+        repo: normalizedRepo,
+        summary: digest.markdown,
+        changeSummary: active ? `auto-refresh from ${digest.receiptCount} receipt(s)` : undefined,
+        supersedesBriefId: active ? active.id : undefined,
+        refreshReceiptCount: digest.receiptCount,
+        // The path tag lets path-aware recall boost the brief; it cannot become its own receipt, because receipts leave out source project_brief.
+        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. */
+export function refreshBrief(hippoRoot, tenantId, repo, actor = 'cli') {
+    const normalizedRepo = requiredRepo('refreshBrief', tenantId, repo);
+    const digest = assembleBriefFromReceipts(hippoRoot, tenantId, normalizedRepo);
+    const active = loadActiveBriefForRepo(hippoRoot, tenantId, normalizedRepo);
+    return saveProjectBrief(hippoRoot, tenantId, refreshWrite(normalizedRepo, digest, active), actor);
+}
+/** `refreshBrief` over a served store's group. */
+export async function refreshedBrief(objects, site, repo) {
+    const normalizedRepo = requiredRepo('refreshBrief', site.tenantId, repo);
+    const digest = await briefFromReceipts(objects, site.tenantId, normalizedRepo);
+    const [active = null] = await objects.listObjects(site.tenantId, 'project_brief', newestActive(normalizedRepo));
+    return saveObject(objects, PROJECT_BRIEF, site, refreshWrite(normalizedRepo, digest, active));
+}
+//# sourceMappingURL=project-briefs.js.map

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

@@ -21,8 +21,11 @@
  * Lifecycle: active -> superseded (a newer version replaces it) or active ->
  * closed (retired). Export renders ACTIVE skills only.
  */
-import { type KeysetPosition } from './keyset.js';
-export type SkillStatus = 'active' | 'superseded' | 'closed';
+import type { KeysetPosition } from '../util/keyset.js';
+import type { SavableDescriptor } from './descriptor.js';
+import type { Skill, SkillStatus } from '../store/object-types.js';
+import type { Objects } from '../store/port.js';
+export type { Skill, SkillStatus } from '../store/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. */
@@ -32,26 +35,6 @@ export declare 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 declare const MAX_EXPORT_SKILLS = 1000;
-export interface Skill {
-    id: number;
-    /** Nullable: ON DELETE SET NULL lets memory deletion proceed without breaking
-     *  the skill row. */
-    memoryId: string | null;
-    tenantId: string;
-    skillName: string;
-    instructions: string;
-    /** Optional "when to apply"; stored in the trigger_text column. */
-    trigger: string | null;
-    /** Server-derived: 1 on a fresh create, predecessor.version + 1 on supersede. */
-    version: number;
-    status: SkillStatus;
-    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 SaveSkillOpts {
     skillName: string;
     instructions: string;
@@ -70,17 +53,17 @@ export interface ListSkillsOpts {
     /** Resume after this row: the position the previous page ended on. */
     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 atomically inside writeEntry's SAVEPOINT. When
+ * 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 SAVEPOINT;
+ * version) BEFORE the INSERT, then CAS-UPDATEd -> superseded in the same transaction;
  * the new version = predecessor.version + 1 (server-derived).
  */
 export declare function saveSkill(hippoRoot: string, tenantId: string, opts: SaveSkillOpts, actor?: string): Skill;
 /**
- * Close (retire) an active skill. CAS guard WHERE status='active'; 0 changes
- * distinguishes not-found from not-active. 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;
@@ -98,4 +81,6 @@ export declare function loadActiveSkills(hippoRoot: string, tenantId: string, op
  * active rows; each field is capped on save, so the rendered string is bounded.
  */
 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>;
 //# sourceMappingURL=skills.d.ts.map