hippo-memory 1.69.0 → 1.71.0

package/dist/objects/policies.js

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

package/dist/objects/processes.d.ts

@@ -0,0 +1,43 @@
+/** 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';
+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 SaveProcessOpts {
+    processName: string;
+    steps: string[];
+    description?: string;
+    /** The delta note for a supersession; ignored (stored NULL) on a fresh create. */
+    changeSummary?: string;
+    /** Table id of an ACTIVE process this new version supersedes. */
+    supersedesProcessId?: number;
+    /** Extra memory tags merged after ['process']. */
+    extraTags?: string[];
+}
+export interface ListProcessesOpts {
+    status?: ProcessStatus;
+    limit?: number;
+    /** Resume after this row: the position the previous page ended on. */
+    after?: KeysetPosition;
+}
+/** 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 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; 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[];
+export declare function loadActiveProcesses(hippoRoot: string, tenantId: string, opts?: {
+    limit?: number;
+}): Process[];
+//# sourceMappingURL=processes.d.ts.map

package/dist/objects/processes.js

@@ -0,0 +1,92 @@
+/** 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';
+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;
+/** 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');
+    }
+    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(),
+        };
+    },
+};
+/** 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; a superseded row 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/objects/project-briefs.d.ts

@@ -0,0 +1,63 @@
+/** 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 { 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. */
+export declare const MAX_REPO_LEN = 256;
+export declare const MAX_BRIEF_SUMMARY_LEN = 8192;
+export declare 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 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 SaveProjectBriefOpts {
+    repo: string;
+    summary: string;
+    /** The delta note for a supersession; ignored (stored NULL) on a fresh create. */
+    changeSummary?: string;
+    /** Table id of an ACTIVE brief this new version supersedes. */
+    supersedesBriefId?: number;
+    /** Extra memory tags merged after ['project_brief']. */
+    extraTags?: string[];
+    /** 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 {
+    status?: BriefStatus;
+    /** Filter to a single repo. */
+    repo?: string;
+    limit?: number;
+    /** 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 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. */
+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[];
+/** 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>;
+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. */
+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,194 @@
+/** 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';
+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}`;
+}
+/** 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. */
+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. 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;
+    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 };
+}
+/** 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()}`;
+}
+// `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 = [];
+    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: 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; 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));
+}
+/** `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/objects/skills.d.ts

@@ -0,0 +1,51 @@
+/** 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 { 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. */
+export declare const MAX_SKILL_NAME_LEN = 256;
+export declare const MAX_SKILL_INSTRUCTIONS_LEN = 8192;
+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 SaveSkillOpts {
+    skillName: string;
+    instructions: string;
+    /** Optional "when to apply" trigger. */
+    trigger?: string;
+    /** The delta note for a supersession; ignored (stored NULL) on a fresh create. */
+    changeSummary?: string;
+    /** Table id of an ACTIVE skill this new version supersedes. */
+    supersedesSkillId?: number;
+    /** Extra memory tags merged after ['skill']. */
+    extraTags?: string[];
+}
+export interface ListSkillsOpts {
+    status?: SkillStatus;
+    limit?: number;
+    /** 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 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. */
+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 (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>;
+//# sourceMappingURL=skills.d.ts.map

package/dist/objects/skills.js

@@ -0,0 +1,110 @@
+/** 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';
+export const VALID_SKILL_STATES = new Set([
+    'active',
+    'superseded',
+    'closed',
+]);
+/** Field caps (untrusted at the HTTP/SDK boundary). instructions is a body, so a
+ *  larger cap than the 4096 short-field convention. */
+export const MAX_SKILL_NAME_LEN = 256;
+export const MAX_SKILL_INSTRUCTIONS_LEN = 8192;
+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;
+/** 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)
+        return null;
+    if (trigger.length > MAX_SKILL_TRIGGER_LEN) {
+        throw new BadRequestError(`saveSkill: trigger exceeds the ${MAX_SKILL_TRIGGER_LEN}-char cap`);
+    }
+    if (/[\r\n]/.test(trigger)) {
+        throw new BadRequestError('saveSkill: trigger must be a single line (no newlines)');
+    }
+    return trigger;
+}
+/** Recall-surface content for the memory mirror: name, optional trigger, instructions. */
+function buildSkillContent(skillName, instructions, trigger) {
+    let content = skillName;
+    if (trigger)
+        content += `\n\nWhen: ${trigger}`;
+    content += `\n\n${instructions}`;
+    return content;
+}
+export const SKILL = {
+    kind: 'skill',
+    label: 'skill',
+    plural: 'skills',
+    fn: { get: 'loadSkillById', close: 'closeSkill', list: 'loadSkills', save: 'saveSkill' },
+    states: VALID_SKILL_STATES,
+    closableFrom: ['active'],
+    draft(opts) {
+        // The name becomes an H2 header in the export, so it must be one line.
+        const name = requireLine(opts.skillName, MAX_SKILL_NAME_LEN, {
+            required: 'saveSkill: skillName is required',
+            singleLine: 'saveSkill: skillName must be a single line (no newlines)',
+            tooLong: `saveSkill: skillName exceeds the ${MAX_SKILL_NAME_LEN}-char cap`,
+        });
+        checkText(opts.instructions, MAX_SKILL_INSTRUCTIONS_LEN, {
+            required: 'saveSkill: instructions are required',
+            tooLong: `saveSkill: instructions exceed the ${MAX_SKILL_INSTRUCTIONS_LEN}-char cap`,
+        });
+        const trigger = checkTrigger(opts.trigger);
+        return {
+            fields: { name, instructions: opts.instructions, trigger },
+            content: buildSkillContent(name, opts.instructions, trigger),
+            tags: opts.extraTags ?? [],
+            supersedesId: opts.supersedesSkillId,
+            changeSummary: opts.changeSummary,
+            at: new Date().toISOString(),
+        };
+    },
+};
+/** 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. */
+export function closeSkill(hippoRoot, tenantId, id, actor = 'cli') {
+    return closeObjectAt(hippoRoot, SKILL, tenantId, id, actor);
+}
+export function loadSkillById(hippoRoot, tenantId, id) {
+    return objectByIdAt(hippoRoot, SKILL, tenantId, id);
+}
+export function loadSkills(hippoRoot, tenantId, opts = {}) {
+    return listObjectsAt(hippoRoot, SKILL, 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 (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));
+}
+/** `exportSkills` over a served store's group. */
+export async function skillsMarkdown(objects, tenantId) {
+    assertTenantId('exportSkills', tenantId);
+    return skillsBlock(await objects.activeSkillsByName(tenantId, MAX_EXPORT_SKILLS));
+}
+function skillsBlock(skills) {
+    return skills
+        .map((s) => {
+        let block = `## ${s.skillName}`;
+        if (s.trigger)
+            block += `\n\n**When:** ${s.trigger}`;
+        block += `\n\n${s.instructions}`;
+        return block;
+    })
+        .join('\n\n');
+}
+//# sourceMappingURL=skills.js.map