@kindgi/api 0.1.4-rc.5 → 0.1.5-rc.0

package/dist/routes/memory-erasures.js

@@ -0,0 +1,214 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { Hono } from 'hono';
+import { ref } from '@kindgi/authz';
+import { statusFor, toWireError } from '../errors.js';
+import { callerRef } from './memory-access.js';
+import { clampLimit } from './pagination.js';
+/**
+ * Erasing a person's words (T273 M-5):
+ *
+ *   - `POST /v1/memory/erasures`          start one (202); `409 legal-hold`
+ *                                         when a fact it reaches is held
+ *   - `GET  /v1/memory/erasures`          newest first, in pages
+ *   - `GET  /v1/memory/erasures/export`   the whole ledger, content-free,
+ *                                         to keep off-box
+ *   - `GET  /v1/memory/erasures/:id`      one, and how far it got
+ *   - `POST /v1/memory/erasures/:id/resume`  try again now; `force`: stop
+ *                                         waiting for a shared flow's run
+ *   - `POST /v1/memory/erasures/replay`   after a backup restore: the
+ *                                         exported ledger back, its
+ *                                         erasures run again
+ *
+ * PEP: a tenant admin only, for every selector (`admin` on
+ * `tenant:<tenantId>`), as retention; a service account only through an
+ * explicit tenant-admin grant.
+ */
+export function memoryErasuresRouter(binding, authorizer) {
+    const r = new Hono();
+    if (authorizer !== undefined) {
+        r.use('/*', async (c, next) => {
+            const tenantId = c.get('tenantId');
+            const mw = authorizer.authorize('admin', async () => ref('tenant', tenantId));
+            return mw(c, next);
+        });
+    }
+    r.post('/', async (c) => {
+        const tenantId = c.get('tenantId');
+        const body = await jsonBody(c);
+        const selector = parseSelector(body);
+        if (typeof selector === 'string')
+            return fail(c, 'bad-input', selector);
+        const outcome = await binding.create({ tenantId, selector, requestedBy: callerRef(c) });
+        if (outcome.kind === 'refused') {
+            const { code, message, factIds } = outcome.refusal;
+            return fail(c, code, message, factIds !== undefined ? { factIds: [...factIds] } : {});
+        }
+        c.status(202);
+        return c.json({
+            ...outcome.erasure,
+            ...(outcome.warnings.length > 0 && { warnings: outcome.warnings }),
+        });
+    });
+    r.get('/', async (c) => {
+        const tenantId = c.get('tenantId');
+        const cursor = c.req.query('cursor');
+        const page = await binding.list(tenantId, {
+            limit: clampLimit(c.req.query('limit')),
+            ...(cursor !== undefined && cursor !== '' && { cursor }),
+        });
+        if (page === undefined)
+            return fail(c, 'bad-input', '`cursor` is not one this list issued');
+        return c.json({
+            data: page.data,
+            hasMore: page.nextCursor !== undefined,
+            ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor }),
+        });
+    });
+    r.get('/export', async (c) => {
+        const tenantId = c.get('tenantId');
+        return c.json({ data: await binding.exportLedger(tenantId) });
+    });
+    r.post('/replay', async (c) => {
+        const tenantId = c.get('tenantId');
+        const body = await jsonBody(c);
+        const entries = parseLedger(body);
+        if (typeof entries === 'string')
+            return fail(c, 'bad-input', entries);
+        return c.json(await binding.replay(tenantId, entries));
+    });
+    r.post('/:erasureId/resume', async (c) => {
+        const tenantId = c.get('tenantId');
+        const id = c.req.param('erasureId');
+        const body = (await jsonBody(c)) ?? {};
+        const force = body.force;
+        if (typeof body !== 'object' ||
+            Array.isArray(body) ||
+            (force !== undefined && typeof force !== 'boolean')) {
+            return fail(c, 'bad-input', 'The body is `{force?: boolean}`');
+        }
+        const erasure = UUID.test(id)
+            ? await binding.resume(tenantId, id, { ...(force === true && { force: true }) })
+            : undefined;
+        if (erasure === undefined)
+            return fail(c, 'not-found', `No erasure ${id}`);
+        return c.json(erasure);
+    });
+    r.get('/:erasureId', async (c) => {
+        const tenantId = c.get('tenantId');
+        const id = c.req.param('erasureId');
+        const erasure = UUID.test(id) ? await binding.get(tenantId, id) : undefined;
+        if (erasure === undefined)
+            return fail(c, 'not-found', `No erasure ${id}`);
+        return c.json(erasure);
+    });
+    return r;
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SUBJECT_KINDS = ['participant', 'external'];
+const SELECTOR_KINDS = [
+    'fact',
+    'participant',
+    'external',
+    'conversation',
+];
+const STATUSES = ['pending', 'running', 'waiting-on-run', 'completed', 'failed'];
+const MAX_ID = 256;
+const MAX_LEDGER = 10_000;
+function fail(c, code, message, extra = {}) {
+    c.status(statusFor(code));
+    return c.json(toWireError({ code, message, ...extra }, c.get('requestId')));
+}
+async function jsonBody(c) {
+    try {
+        return await c.req.json();
+    }
+    catch {
+        return undefined;
+    }
+}
+const isId = (v) => typeof v === 'string' && v.trim() !== '' && v.length <= MAX_ID;
+/** Exactly one of `factId`, `subject` or `conversationId`; or why not. */
+function parseSelector(body) {
+    if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+        return 'The body must be an object naming one of `factId`, `subject` or `conversationId`';
+    }
+    const b = body;
+    const named = ['factId', 'subject', 'conversationId'].filter((k) => b[k] !== undefined);
+    if (named.length !== 1) {
+        return 'Name exactly one of `factId`, `subject` (`{kind, id}`) or `conversationId`';
+    }
+    const unknown = Object.keys(b).filter((k) => !['factId', 'subject', 'conversationId'].includes(k));
+    if (unknown.length > 0)
+        return `Unknown field \`${unknown[0]}\``;
+    if (b.factId !== undefined) {
+        return isId(b.factId) ? { factId: b.factId } : '`factId` must be a non-empty string';
+    }
+    if (b.conversationId !== undefined) {
+        return isId(b.conversationId)
+            ? { conversationId: b.conversationId }
+            : '`conversationId` must be a non-empty string';
+    }
+    const s = b.subject;
+    if (s === null || typeof s !== 'object')
+        return '`subject` must be `{kind, id}`';
+    if (s.kind === 'user') {
+        return "Erasing a Kindgi user isn't offered: `subject.kind` must be `participant` (an app's end user) or `external`";
+    }
+    if (!SUBJECT_KINDS.includes(s.kind)) {
+        return '`subject.kind` must be `participant` or `external`';
+    }
+    if (!isId(s.id))
+        return '`subject.id` must be a non-empty string';
+    return { subject: { kind: s.kind, id: s.id } };
+}
+/** `{erasures: MemoryErasureLedgerEntry[]}`, as `GET /export` gave it; or why not. */
+function parseLedger(body) {
+    const list = body?.erasures;
+    if (!Array.isArray(list))
+        return 'The body must be `{erasures: [...]}`, as the export gave them';
+    if (list.length > MAX_LEDGER)
+        return `At most ${MAX_LEDGER} erasures per replay`;
+    const out = [];
+    for (const [i, raw] of list.entries()) {
+        const e = raw;
+        const at = `erasures[${i}]`;
+        if (e === null || typeof e !== 'object')
+            return `${at} must be an object`;
+        if (typeof e.id !== 'string' || !UUID.test(e.id))
+            return `${at}.id must be a uuid`;
+        if (!SELECTOR_KINDS.includes(e.selectorKind)) {
+            return `${at}.selectorKind must be one of ${SELECTOR_KINDS.join(', ')}`;
+        }
+        if (e.selectorHmac !== undefined &&
+            (typeof e.selectorHmac !== 'string' || !/^[0-9a-f]{64}$/.test(e.selectorHmac))) {
+            return `${at}.selectorHmac must be 64 hex characters`;
+        }
+        if (e.keyId !== undefined && !isId(e.keyId))
+            return `${at}.keyId must be a string`;
+        if (!isId(e.requestedBy))
+            return `${at}.requestedBy must be a string`;
+        if (!STATUSES.includes(e.status)) {
+            return `${at}.status must be one of ${STATUSES.join(', ')}`;
+        }
+        for (const k of ['createdAt', 'completedAt']) {
+            const v = e[k];
+            if (v === undefined && k === 'completedAt')
+                continue;
+            if (typeof v !== 'string' || Number.isNaN(Date.parse(v)))
+                return `${at}.${k} must be a time`;
+        }
+        out.push({
+            id: e.id,
+            selectorKind: e.selectorKind,
+            ...(typeof e.selectorHmac === 'string' && { selectorHmac: e.selectorHmac }),
+            ...(typeof e.keyId === 'string' && { keyId: e.keyId }),
+            requestedBy: e.requestedBy,
+            status: e.status,
+            createdAt: e.createdAt,
+            ...(typeof e.completedAt === 'string' && { completedAt: e.completedAt }),
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=memory-erasures.js.map

package/dist/routes/memory-erasures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-erasures.js","sourceRoot":"","sources":["../../src/routes/memory-erasures.ts"],"names":[],"mappings":"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"}

package/dist/routes/memory-parse.d.ts

@@ -0,0 +1,38 @@
+/** Request parsing for `/v1/memory`: fact writes, supersedes, retrieve intents and query values. */
+import type { FactSubject, MemoryScope, Retention } from '@kindgi/memory';
+import type { Timestamp } from '@kindgi/types';
+import type { MemoryRetrieveIntent } from '../memory-binding.js';
+export type ValidationResult<T> = {
+    readonly kind: 'ok';
+    readonly value: T;
+} | {
+    readonly kind: 'err';
+    readonly message: string;
+};
+export declare function parseScopeParam(raw: string): Partial<MemoryScope> | null;
+/** An ISO 8601 time, as a query value or a body field. */
+export declare function parseTime(raw: unknown, field: string): ValidationResult<Timestamp | undefined>;
+/** A revision number: a whole number of 1 or more. */
+export declare function parseVersion(raw: unknown, field: string): ValidationResult<number | undefined>;
+/** The fields a write and a supersede share: retention, subjects and the times. */
+export interface ValidatedFactFields {
+    readonly retention?: Retention;
+    readonly subjects?: readonly FactSubject[];
+    readonly validFrom?: Timestamp;
+    readonly validUntil?: Timestamp;
+    readonly observedAt?: Timestamp;
+}
+export interface ValidatedWriteFactBody extends ValidatedFactFields {
+    readonly type: string;
+    readonly scope: MemoryScope;
+    readonly content: unknown;
+    readonly contentHash?: string;
+}
+export declare function validateWriteFactBody(body: Record<string, unknown>): ValidationResult<ValidatedWriteFactBody>;
+export interface ValidatedSupersedeBody extends ValidatedFactFields {
+    readonly content: unknown;
+    readonly expectVersion?: number;
+}
+export declare function validateSupersedeBody(body: Record<string, unknown>): ValidationResult<ValidatedSupersedeBody>;
+export declare function validateRetrieveIntent(body: Record<string, unknown>): ValidationResult<MemoryRetrieveIntent>;
+//# sourceMappingURL=memory-parse.d.ts.map

package/dist/routes/memory-parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-parse.d.ts","sourceRoot":"","sources":["../../src/routes/memory-parse.ts"],"names":[],"mappings":"AAGA,oGAAoG;AAEpG,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC1E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEjE,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAC1C;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAOvD,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI,CAQxE;AAED,0DAA0D;AAC1D,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAAC,SAAS,GAAG,SAAS,CAAC,CAM9F;AAED,sDAAsD;AACtD,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAAC,MAAM,GAAG,SAAS,CAAC,CAO9F;AAiED,mFAAmF;AACnF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC;CACjC;AA2BD,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,gBAAgB,CAAC,sBAAsB,CAAC,CAwB1C;AAED,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,gBAAgB,CAAC,sBAAsB,CAAC,CAa1C;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,gBAAgB,CAAC,oBAAoB,CAAC,CA6CxC"}

package/dist/routes/memory-parse.js

@@ -0,0 +1,199 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+const ok = (value) => ({ kind: 'ok', value });
+const err = (message) => ({ kind: 'err', message });
+const MAX_SUBJECTS = 20;
+export function parseScopeParam(raw) {
+    try {
+        const decoded = JSON.parse(raw);
+        if (decoded === null || typeof decoded !== 'object' || Array.isArray(decoded))
+            return null;
+        return decoded;
+    }
+    catch {
+        return null;
+    }
+}
+/** An ISO 8601 time, as a query value or a body field. */
+export function parseTime(raw, field) {
+    if (raw === undefined)
+        return ok(undefined);
+    if (typeof raw !== 'string' || Number.isNaN(Date.parse(raw))) {
+        return err(`\`${field}\` must be an ISO 8601 time`);
+    }
+    return ok(new Date(raw).toISOString());
+}
+/** A revision number: a whole number of 1 or more. */
+export function parseVersion(raw, field) {
+    if (raw === undefined)
+        return ok(undefined);
+    const n = typeof raw === 'string' && raw.trim() !== '' ? Number(raw) : raw;
+    if (typeof n !== 'number' || !Number.isInteger(n) || n < 1) {
+        return err(`\`${field}\` must be a revision number (1 or more)`);
+    }
+    return ok(n);
+}
+function parseScope(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return err('Field `scope` must be an object');
+    }
+    const scope = raw;
+    if (typeof scope.tenantId !== 'string')
+        return err('Field `scope.tenantId` must be a string');
+    if (scope.participantId !== undefined &&
+        (typeof scope.participantId !== 'string' || scope.participantId.length === 0)) {
+        return err('Field `scope.participantId` must be a non-empty string');
+    }
+    if (scope.participantId !== undefined && scope.projectId === undefined) {
+        return err("`scope.participantId` needs `scope.projectId`: an app's end users belong to a project");
+    }
+    return ok(scope);
+}
+function parseRetention(raw) {
+    if (raw === undefined)
+        return ok(undefined);
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return err('Field `retention` must be an object when present');
+    }
+    const r = raw;
+    const keepUntil = parseTime(r.keepUntil, 'retention.keepUntil');
+    if (keepUntil.kind === 'err')
+        return keepUntil;
+    if (r.keepDays !== undefined &&
+        (typeof r.keepDays !== 'number' || !Number.isInteger(r.keepDays) || r.keepDays < 1)) {
+        return err('`retention.keepDays` must be a whole number of days (1 or more)');
+    }
+    if (r.legalHold !== undefined && typeof r.legalHold !== 'boolean') {
+        return err('`retention.legalHold` must be true or false');
+    }
+    return ok(r);
+}
+function parseSubjects(raw) {
+    if (raw === undefined)
+        return ok(undefined);
+    const shape = "Field `subjects` is a list of whom the fact is about: [{ kind: 'participant' | 'user' | 'external', id }]";
+    if (!Array.isArray(raw) || raw.length > MAX_SUBJECTS) {
+        return err(`${shape}, at most ${MAX_SUBJECTS}`);
+    }
+    for (const s of raw) {
+        const o = s;
+        if (o === null ||
+            typeof o !== 'object' ||
+            !['participant', 'user', 'external'].includes(o.kind) ||
+            typeof o.id !== 'string' ||
+            o.id.length === 0 ||
+            Object.keys(o).length !== 2) {
+            return err(shape);
+        }
+    }
+    return ok(raw);
+}
+function parseFactFields(body) {
+    const retention = parseRetention(body.retention);
+    if (retention.kind === 'err')
+        return retention;
+    const subjects = parseSubjects(body.subjects);
+    if (subjects.kind === 'err')
+        return subjects;
+    const times = {};
+    for (const field of ['validFrom', 'validUntil', 'observedAt']) {
+        const t = parseTime(body[field], field);
+        if (t.kind === 'err')
+            return t;
+        if (t.value !== undefined)
+            times[field] = t.value;
+    }
+    if (times.validFrom !== undefined &&
+        times.validUntil !== undefined &&
+        times.validFrom > times.validUntil) {
+        return err('`validFrom` must not be after `validUntil`');
+    }
+    return ok({
+        ...(retention.value !== undefined && { retention: retention.value }),
+        ...(subjects.value !== undefined && { subjects: subjects.value }),
+        ...times,
+    });
+}
+export function validateWriteFactBody(body) {
+    const type = body.type;
+    if (typeof type !== 'string' || type.length === 0) {
+        return err('Field `type` must be a non-empty string');
+    }
+    const scope = parseScope(body.scope);
+    if (scope.kind === 'err')
+        return scope;
+    if (!('content' in body))
+        return err('Field `content` is required');
+    const rawContentHash = body.contentHash;
+    if (rawContentHash !== undefined &&
+        (typeof rawContentHash !== 'string' || rawContentHash.length === 0)) {
+        return err('Field `contentHash` must be a non-empty string when present');
+    }
+    const fields = parseFactFields(body);
+    if (fields.kind === 'err')
+        return fields;
+    return ok({
+        type,
+        scope: scope.value,
+        content: body.content,
+        ...(typeof rawContentHash === 'string' && { contentHash: rawContentHash }),
+        ...fields.value,
+    });
+}
+export function validateSupersedeBody(body) {
+    if (!('content' in body)) {
+        return err("Field `content` is required: the fact's next revision");
+    }
+    const expectVersion = parseVersion(body.expectVersion, 'expectVersion');
+    if (expectVersion.kind === 'err')
+        return expectVersion;
+    const fields = parseFactFields(body);
+    if (fields.kind === 'err')
+        return fields;
+    return ok({
+        content: body.content,
+        ...(expectVersion.value !== undefined && { expectVersion: expectVersion.value }),
+        ...fields.value,
+    });
+}
+export function validateRetrieveIntent(body) {
+    const mode = body.mode;
+    if (mode !== 'list' && mode !== 'keyword' && mode !== 'semantic' && mode !== 'both') {
+        return err('Field `mode` must be one of "list", "keyword", "semantic", "both"');
+    }
+    const rawQuery = body.query;
+    if (rawQuery !== undefined && typeof rawQuery !== 'string') {
+        return err('Field `query` must be a string when present');
+    }
+    if ((mode === 'keyword' || mode === 'semantic' || mode === 'both') && rawQuery === undefined) {
+        return err(`Field \`query\` is required when \`mode\` is "${mode}"`);
+    }
+    const rawType = body.type;
+    if (rawType !== undefined && (typeof rawType !== 'string' || rawType.length === 0)) {
+        return err('Field `type` must be a non-empty string when present');
+    }
+    const rawScope = body.scope;
+    if (rawScope !== undefined &&
+        (rawScope === null || typeof rawScope !== 'object' || Array.isArray(rawScope))) {
+        return err('Field `scope` must be an object when present');
+    }
+    const rawLimit = body.limit;
+    if (rawLimit !== undefined &&
+        (typeof rawLimit !== 'number' || !Number.isFinite(rawLimit) || rawLimit < 1)) {
+        return err('Field `limit` must be a positive number when present');
+    }
+    const rawEmbeddingModel = body.embeddingModel;
+    if (rawEmbeddingModel !== undefined &&
+        (typeof rawEmbeddingModel !== 'string' || rawEmbeddingModel.length === 0)) {
+        return err('Field `embeddingModel` must be a non-empty string when present');
+    }
+    return ok({
+        mode,
+        ...(typeof rawQuery === 'string' && { query: rawQuery }),
+        ...(typeof rawType === 'string' && { type: rawType }),
+        ...(rawScope !== undefined && { scope: rawScope }),
+        ...(typeof rawLimit === 'number' && { limit: Math.floor(rawLimit) }),
+        ...(typeof rawEmbeddingModel === 'string' && { embeddingModel: rawEmbeddingModel }),
+    });
+}
+//# sourceMappingURL=memory-parse.js.map

package/dist/routes/memory-parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-parse.js","sourceRoot":"","sources":["../../src/routes/memory-parse.ts"],"names":[],"mappings":"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"}

package/dist/routes/memory.d.ts

@@ -1,16 +1,21 @@
 import { Hono } from 'hono';
 import type { MemoryBinding } from '../memory-binding.js';
 import type { AppEnv } from '../types.js';
+import { type MemoryAccessDeps } from './memory-access.js';
 /**
  * Memory resource routes.
  *
  * Storage is caller-plugged via `MemoryBinding`. The API package does
- * not own memory persistence, retrieval, or embeddings — deployments
+ * not own memory persistence, retrieval, or embeddings: deployments
  * wire a binding that wraps the memory subsystem alongside their own
  * `EmbeddingProviderRegistry` and per-type retrieval policies.
  *
- * Facts are append-only: supersession replaces delete. Physical removal
- * is left to the retention sweep.
+ * A fact keeps its id across revisions: supersede writes the next one,
+ * delete tombstones it (the retention sweep removes it later), verify
+ * marks it verified. Every read sees only what the caller may
+ * (`memory-access.ts`): the binding applies it inside its query, and a
+ * fact the caller can't see is not found. Every write is checked against
+ * the scope it names.
  */
-export declare function memoryRouter(binding: MemoryBinding): Hono<AppEnv>;
+export declare function memoryRouter(binding: MemoryBinding, access?: MemoryAccessDeps): Hono<AppEnv>;
 //# sourceMappingURL=memory.d.ts.map

package/dist/routes/memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/routes/memory.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAM5B,OAAO,KAAK,EAAE,aAAa,EAA4C,MAAM,sBAAsB,CAAC;AACpG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAI1C;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC,MAAM,CAAC,CAmNjE"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/routes/memory.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,IAAI,EAAE,MAAM,MAAM,CAAC;AAM1C,OAAO,KAAK,EACV,aAAa,EAGd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EACL,KAAK,gBAAgB,EAKtB,MAAM,oBAAoB,CAAC;AAY5B;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,GAAE,gBAAqB,GAAG,IAAI,CAAC,MAAM,CAAC,CA0NhG"}