@b4run/memory 0.8.28

package/dist/browse-validate.js

@@ -0,0 +1,263 @@
+/** Largest `limit` the UNTRUSTED boundary accepts. Enforced only when a caller passes
+ *  `maxLimit` — in-process callers (the CLI's 10 000-row consolidation scan) are
+ *  trusted and exempt; the HTTP route is not. */
+export const BROWSE_MAX_LIMIT = 1000;
+/** Applied by the stores when `limit` is absent. */
+export const BROWSE_DEFAULT_LIMIT = 50;
+const MAX_STRING_BYTES = 1024;
+const MAX_CURSOR_CHARS = 4096;
+/** Never the deciding constraint: one filter per field over six fields already rejects a
+ *  seventh. This is the fast-fail on an enormous array from an untrusted body, taken
+ *  before the per-filter loop walks it. */
+const MAX_FILTERS = 8;
+const MAX_ORDER_BY = 3;
+const ENCODER = new TextEncoder();
+export const BROWSE_SORT_FIELDS = [
+    "updatedAt",
+    "createdAt",
+    "confidence",
+    "namespace",
+    "kind",
+    "status",
+];
+const STATUSES = ["candidate", "active", "superseded"];
+const KINDS = [
+    "semantic",
+    "episodic",
+    "procedural",
+    "reflection",
+];
+const SOURCE_TYPES = [
+    "run",
+    "user",
+    "tool",
+    "eval",
+    "human",
+];
+const FILTER_FIELDS = [
+    "status",
+    "kind",
+    "content",
+    "namespace",
+    "confidence",
+    "updatedAt",
+];
+const _listsSpellOutTheirUnions = [true, true, true, true, true];
+void _listsSpellOutTheirUnions;
+const CONTENT_OPS = [
+    "contains",
+    "notContains",
+    "equals",
+    "notEquals",
+    "startsWith",
+    "endsWith",
+];
+const NAMESPACE_OPS = ["equals", "startsWith"];
+const CONFIDENCE_OPS = ["eq", "neq", "gt", "gte", "lt", "lte", "between"];
+const UPDATED_AT_OPS = ["onDay", "beforeDay", "afterDay", "betweenDays"];
+const SET_OPS = ["in", "notIn"];
+const ISO_Z = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+/** Every rejection this module raises. The Inspector maps it to 400 `{error}`; the
+ *  stores let it propagate, so a bad query fails loudly instead of silently matching
+ *  zero rows. */
+export class BrowseQueryError extends Error {
+    code;
+    constructor(message, code = "invalid-query") {
+        super(message);
+        this.name = "BrowseQueryError";
+        this.code = code;
+    }
+}
+function fail(message) {
+    throw new BrowseQueryError(message);
+}
+function checkString(value, label) {
+    if (typeof value !== "string")
+        fail(`${label} must be a string`);
+    if (value.length === 0)
+        fail(`${label} must not be empty`);
+    // Every character costs at least one UTF-8 byte, so a too-long string is already
+    // too many bytes — decided without encoding a multi-megabyte untrusted body.
+    if (value.length > MAX_STRING_BYTES || ENCODER.encode(value).length > MAX_STRING_BYTES)
+        fail(`${label} must be at most ${MAX_STRING_BYTES} bytes`);
+}
+function checkFinite(value, label) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        fail(`${label} must be a finite number`);
+}
+function checkInstant(value, label) {
+    // Full-ISO-Z only: the stores compare these TEXT columns lexicographically, so a
+    // shorter or offset form silently windows wrong rather than failing.
+    if (typeof value !== "string" || !ISO_Z.test(value))
+        fail(`${label} must be a full ISO-8601 UTC instant ("YYYY-MM-DDTHH:MM:SS.sssZ")`);
+    // Out-of-range components ROLL OVER rather than fail: "2026-02-31T…" parses as March 3
+    // and "…T24:00:00.000Z" as the next day. Both spellings then sort against the stored
+    // text at the wrong place, so only a string that round-trips names the instant it reads as.
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed) || new Date(parsed).toISOString() !== value)
+        fail(`${label} "${value}" is not a real UTC instant`);
+}
+function checkDay(value, label) {
+    if (typeof value !== "string" || !DAY.test(value))
+        fail(`${label} must be a "YYYY-MM-DD" UTC day`);
+    const parsed = Date.parse(`${value}T00:00:00.000Z`);
+    if (!Number.isFinite(parsed) || new Date(parsed).toISOString().slice(0, 10) !== value)
+        fail(`${label} "${value}" is not a real calendar day`);
+}
+function checkEnum(value, allowed, label) {
+    if (typeof value !== "string" || !allowed.includes(value))
+        fail(`invalid ${label} ${JSON.stringify(value)} (expected one of: ${allowed.join(", ")})`);
+}
+function checkEnumList(value, allowed, label) {
+    const values = typeof value === "string" ? [value] : value;
+    if (!Array.isArray(values))
+        fail(`${label} must be a value or an array of values`);
+    for (const entry of values)
+        checkEnum(entry, allowed, label);
+}
+function checkOp(op, allowed, field) {
+    if (typeof op !== "string" || !allowed.includes(op))
+        fail(`unknown op ${JSON.stringify(op)} for filter field "${field}" (expected one of: ${allowed.join(", ")})`);
+    return op;
+}
+function validateFilter(raw, seen) {
+    const filter = raw;
+    const field = filter?.field;
+    if (typeof field !== "string" || !FILTER_FIELDS.includes(field))
+        fail(`unknown filter field ${JSON.stringify(field)} (expected one of: ${FILTER_FIELDS.join(", ")})`);
+    if (seen.has(field))
+        fail(`at most one filter per field; "${field}" appears twice`);
+    seen.add(field);
+    switch (field) {
+        case "status":
+        case "kind": {
+            checkOp(filter.op, SET_OPS, field);
+            const values = filter.values;
+            if (!Array.isArray(values))
+                fail(`${field} values must be an array`);
+            // An empty list can only be a bug: an inactive filter is never sent.
+            if (values.length === 0)
+                fail(`${field} values must not be empty`);
+            checkEnumList(values, field === "status" ? STATUSES : KINDS, field);
+            return;
+        }
+        case "content": {
+            checkOp(filter.op, CONTENT_OPS, field);
+            checkString(filter.value, "content value");
+            return;
+        }
+        case "namespace": {
+            checkOp(filter.op, NAMESPACE_OPS, field);
+            checkString(filter.value, "namespace value");
+            return;
+        }
+        case "confidence": {
+            const op = checkOp(filter.op, CONFIDENCE_OPS, field);
+            if (op === "between") {
+                const { min, max } = filter;
+                checkFinite(min, "confidence min");
+                checkFinite(max, "confidence max");
+                if (min > max)
+                    fail("confidence between requires min <= max");
+                return;
+            }
+            checkFinite(filter.value, "confidence value");
+            return;
+        }
+        default: {
+            const op = checkOp(filter.op, UPDATED_AT_OPS, field);
+            if (op === "betweenDays") {
+                const { fromDay, untilDay } = filter;
+                checkDay(fromDay, "updatedAt fromDay");
+                checkDay(untilDay, "updatedAt untilDay");
+                // "YYYY-MM-DD" is uniform-width ASCII, so lexicographic order IS chronological.
+                if (fromDay > untilDay)
+                    fail("updatedAt betweenDays requires fromDay <= untilDay");
+                return;
+            }
+            checkDay(filter.day, "updatedAt day");
+        }
+    }
+}
+/**
+ * The single reading of "is this browse query legal". Runs at the Inspector HTTP
+ * boundary (mapped to 400) and defensively inside every store (thrown). Pass
+ * `maxLimit` at untrusted boundaries only — see BROWSE_MAX_LIMIT.
+ *
+ * The empty set is spelled two ways and they do NOT mean the same thing. The shorthand
+ * `status: []` / `kind: []` is legal and means "match nothing" (see `BrowseQuery`), while
+ * `filters: [{ field: "status", op: "in", values: [] }]` is rejected: a filter entry exists
+ * only because a caller constructed one, so an empty value list is a construction bug
+ * rather than a narrowing. A caller translating UI state must use the shorthand to say
+ * "narrowed to nothing".
+ */
+export function validateBrowseQuery(query, opts = {}) {
+    // The query may arrive from JSON, so every field is treated as unknown.
+    const q = query;
+    const limit = q.limit;
+    if (limit !== undefined) {
+        if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1)
+            fail("limit must be an integer >= 1");
+        if (opts.maxLimit !== undefined && limit > opts.maxLimit)
+            fail(`limit must be at most ${opts.maxLimit}`);
+    }
+    const offset = q.offset;
+    if (offset !== undefined) {
+        if (typeof offset !== "number" || !Number.isInteger(offset) || offset < 0)
+            fail("offset must be an integer >= 0");
+    }
+    if (q.cursor !== undefined) {
+        if (typeof q.cursor !== "string" || q.cursor.length === 0)
+            fail("cursor must be a non-empty string");
+        if (q.cursor.length > MAX_CURSOR_CHARS)
+            fail(`cursor must be at most ${MAX_CURSOR_CHARS} characters`);
+        if (offset !== undefined && offset !== 0)
+            fail("cursor and a non-zero offset cannot be combined — a keyset continuation already carries the position");
+    }
+    if (q.namespace !== undefined)
+        checkString(q.namespace, "namespace");
+    if (q.namespacePrefix !== undefined)
+        checkString(q.namespacePrefix, "namespacePrefix");
+    if (q.since !== undefined)
+        checkInstant(q.since, "since");
+    if (q.until !== undefined)
+        checkInstant(q.until, "until");
+    if (q.now !== undefined)
+        checkInstant(q.now, "now");
+    if (q.status !== undefined)
+        checkEnumList(q.status, STATUSES, "status");
+    if (q.kind !== undefined)
+        checkEnumList(q.kind, KINDS, "kind");
+    // Scalar, unlike status/kind: every store binds it as ONE parameter, so an array
+    // reaches the driver as a bad bind rather than a set match.
+    if (q.sourceType !== undefined)
+        checkEnum(q.sourceType, SOURCE_TYPES, "sourceType");
+    if (q.filters !== undefined) {
+        if (!Array.isArray(q.filters))
+            fail("filters must be an array");
+        if (q.filters.length > MAX_FILTERS)
+            fail(`at most ${MAX_FILTERS} filters`);
+        const seen = new Set();
+        for (const filter of q.filters)
+            validateFilter(filter, seen);
+    }
+    if (q.orderBy !== undefined) {
+        if (!Array.isArray(q.orderBy))
+            fail("orderBy must be an array");
+        if (q.orderBy.length > MAX_ORDER_BY)
+            fail(`at most ${MAX_ORDER_BY} orderBy entries`);
+        const seenFields = new Set();
+        for (const raw of q.orderBy) {
+            const entry = raw;
+            const field = entry?.field;
+            if (typeof field !== "string" || !BROWSE_SORT_FIELDS.includes(field))
+                fail(`unknown sort field ${JSON.stringify(field)} (expected one of: ${BROWSE_SORT_FIELDS.join(", ")})`);
+            if (entry.dir !== "asc" && entry.dir !== "desc")
+                fail(`sort direction must be "asc" or "desc", got ${JSON.stringify(entry.dir)}`);
+            if (seenFields.has(field))
+                fail(`orderBy repeats the field "${field}"`);
+            seenFields.add(field);
+        }
+    }
+}

package/dist/browse.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The PURE browse contract: types, validation, the sort whitelist, range math and the
+ * cursor codec. Deliberately imports nothing from `sqlite-store.ts`, so importing
+ * `@b4run/memory/browse` never pulls `node:sqlite` — bundled server routes and
+ * browser code can both use it.
+ */
+export type { BrowseCursorPayload, BrowseCursorValue } from "./browse-cursor.js";
+export { BROWSE_CURSOR_VERSION, browseCursorKey, browseQueryFingerprint, decodeBrowseCursor, encodeBrowseCursor, } from "./browse-cursor.js";
+export { normalizeSetFilter } from "./browse-filter.js";
+export type { ResolvedBrowseSort } from "./browse-order.js";
+export { DEFAULT_BROWSE_ORDER, resolveBrowseOrder } from "./browse-order.js";
+export { namespacePrefixUpperBound, utcDayAfter, utcDayStart } from "./browse-range.js";
+export { BROWSE_DEFAULT_LIMIT, BROWSE_MAX_LIMIT, BROWSE_SORT_FIELDS, BrowseQueryError, validateBrowseQuery, } from "./browse-validate.js";
+export type { BrowseFilter, BrowsePage, BrowseQuery, BrowseSortEntry, BrowseSortField, MemoryKind, MemoryRecord, MemorySource, MemoryStatus, } from "./types.js";
+//# sourceMappingURL=browse.d.ts.map

package/dist/browse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browse.d.ts","sourceRoot":"","sources":["../src/browse.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,YAAY,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAChF,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACvD,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAC5E,OAAO,EAAE,yBAAyB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACvF,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EACV,YAAY,EACZ,UAAU,EACV,WAAW,EACX,eAAe,EACf,eAAe,EACf,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,YAAY,GACb,MAAM,YAAY,CAAA"}

package/dist/browse.js

@@ -0,0 +1,5 @@
+export { BROWSE_CURSOR_VERSION, browseCursorKey, browseQueryFingerprint, decodeBrowseCursor, encodeBrowseCursor, } from "./browse-cursor.js";
+export { normalizeSetFilter } from "./browse-filter.js";
+export { DEFAULT_BROWSE_ORDER, resolveBrowseOrder } from "./browse-order.js";
+export { namespacePrefixUpperBound, utcDayAfter, utcDayStart } from "./browse-range.js";
+export { BROWSE_DEFAULT_LIMIT, BROWSE_MAX_LIMIT, BROWSE_SORT_FIELDS, BrowseQueryError, validateBrowseQuery, } from "./browse-validate.js";

package/dist/distill.d.ts

@@ -0,0 +1,81 @@
+import type { MemoryRecord } from "./types.js";
+/** Event time for distillation ordering/grouping: when it happened, not when the row moved. */
+export declare function eventTimeOf(record: MemoryRecord): string;
+/** ISO-week key (UTC): "<isoYear>-W<isoWeek>", so a batch is one namespace-week. */
+export declare function isoWeekKey(iso: string): string;
+export interface ConsolidationBatch {
+    readonly namespace: string;
+    readonly period: {
+        readonly since: string;
+        readonly until: string;
+    };
+    readonly records: readonly MemoryRecord[];
+}
+/** Group active episodic records into per-(namespace, ISO week) batches, ordered by
+ *  event time; groups below minBatchSize are dropped (summarizing 2 runs is noise),
+ *  groups above maxBatchSize are chunked. Pure: the caller filters by age/status. */
+export declare function selectConsolidationBatches(records: readonly MemoryRecord[], opts: {
+    readonly minBatchSize: number;
+    readonly maxBatchSize: number;
+}): ConsolidationBatch[];
+export interface ReflectionInput {
+    readonly namespace: string;
+    readonly records: readonly MemoryRecord[];
+    /** The newest event time covered — becomes the next pass's watermark. */
+    readonly coveredUntil: string;
+}
+/** Records strictly newer than the watermark, newest-capped then re-sorted ascending.
+ *  Returns null below the threshold — that null is what makes `b4 memory reflect`
+ *  a cheap no-op for cron. Callers pass records from ONE namespace. */
+export declare function selectReflectionInput(records: readonly MemoryRecord[], opts: {
+    readonly minNewRecords: number;
+    readonly maxRecords: number;
+    readonly coveredUntil?: string;
+}): ReflectionInput | null;
+export declare function buildConsolidationPrompt(batch: ConsolidationBatch): string;
+export declare function buildReflectionPrompt(input: ReflectionInput): string;
+export declare function parseConsolidationOutput(raw: string): {
+    summary: string;
+};
+export interface ReflectionInsight {
+    readonly insight: string;
+    readonly confidence: number;
+    readonly tags: readonly string[];
+}
+/** Deliberate leniency asymmetry: a missing/garbage `confidence` falls back to
+ *  0.5 and non-string tags are dropped (cosmetic fields — don't fail a whole
+ *  batch over them), while a missing `insight` throws (that IS the payload). */
+export declare function parseReflectionOutput(raw: string): {
+    insights: ReflectionInsight[];
+};
+/** One summary per batch: the id is derived, not random, so re-consolidating the
+ *  SAME batch overwrites its own summary instead of piling up duplicates — the
+ *  idempotency the engine relies on.
+ *  The source ids are part of the hash because (namespace, period) alone is NOT
+ *  unique: when every record in a namespace-week shares an exactly equal event
+ *  time (bulk import, backfill) and maxBatchSize splits them, each chunk derives
+ *  the same since/until (t and t+1ms) — two distinct batches, one id, and the
+ *  second summary would silently overwrite the first. Hashing the chunk's own
+ *  record ids disambiguates them and still yields a stable id for an identical
+ *  re-run. Covered by "gives same-period chunks distinct summary ids". */
+export declare function buildSummaryRecord(batch: ConsolidationBatch, summary: string, now: string, opts?: {
+    readonly ttlMs?: number;
+}): MemoryRecord;
+/** A pass that legitimately yields NO durable insight still did the work, and the
+ *  watermark is the only place that fact can live. Without this record the
+ *  namespace is re-selected — and re-PAID for — on every subsequent cron run,
+ *  forever, because `readWatermark` finds nothing to advance past.
+ *  It is written `superseded` on purpose: `recall` sees only active/candidate
+ *  rows, so the sentinel can never surface as a fake insight, while `browse`
+ *  (which readWatermark uses, and which does not filter by status unless asked)
+ *  still finds it. The id is derived from (namespace, coveredUntil) only — an
+ *  identical re-run overwrites its own sentinel instead of piling up.
+ *  Covered by "a zero-insight pass still advances the watermark" (distill-engine). */
+export declare function buildReflectionWatermarkRecord(input: ReflectionInput, now: string): MemoryRecord;
+/** The id hashes (namespace, coveredUntil, insight) — so the SAME insight text in
+ *  the SAME pass is one record, not two (the engine's put dedupes it), while a
+ *  later pass with a newer watermark restates it as a distinct record. */
+export declare function buildReflectionRecords(input: ReflectionInput, insights: readonly ReflectionInsight[], now: string, opts: {
+    readonly status: "candidate" | "active";
+}): MemoryRecord[];
+//# sourceMappingURL=distill.d.ts.map

package/dist/distill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"distill.d.ts","sourceRoot":"","sources":["../src/distill.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,+FAA+F;AAC/F,wBAAgB,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAExD;AAED,oFAAoF;AACpF,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAW9C;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;IACnE,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAA;CAC1C;AAED;;qFAEqF;AACrF,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,IAAI,EAAE;IAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACrE,kBAAkB,EAAE,CAsCtB;AAOD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAA;IACzC,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAC9B;AAED;;uEAEuE;AACvE,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,IAAI,EAAE;IACJ,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B,GACA,eAAe,GAAG,IAAI,CAWxB;AAiDD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAiB1E;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAiBpE;AAyFD,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAQzE;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CACjC;AAED;;gFAEgF;AAChF,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAA;CAAE,CAwBpF;AAOD;;;;;;;;;0EAS0E;AAC1E,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACjC,YAAY,CAgCd;AAED;;;;;;;;;sFASsF;AACtF,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAkBhG;AAED;;0EAE0E;AAC1E,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAA;CAAE,GAChD,YAAY,EAAE,CAoBhB"}