@saihm/shm 0.0.0-stage → 0.38.0

package/dist/answer/persistent_body_source.js

@@ -0,0 +1,173 @@
+import { SupersedeLedger } from "./supersede.js";
+export class PersistentBodySource {
+    inner;
+    store;
+    opts;
+    erased = new Set();
+    superseded = new SupersedeLedger();
+    unlinkOwed = new Set();
+    atRestHits = 0;
+    misses = 0;
+    filled = 0;
+    skippedPartial = 0;
+    storeErrors = 0;
+    unmappable = 0;
+    olderNotWritten = 0;
+    constructor(inner, store, opts = {}) {
+        this.inner = inner;
+        this.store = store;
+        this.opts = opts;
+    }
+    async fetchByIds(cellIds, hint) {
+        const uniq = [];
+        const seen = new Set();
+        for (const id of cellIds) {
+            if (!seen.has(id)) {
+                seen.add(id);
+                uniq.push(id);
+            }
+        }
+        const clock = this.opts.clock ?? (() => performance.now());
+        const t0 = clock();
+        const stored = await Promise.all(uniq.map(async (id) => {
+            if (this.erased.has(id) || this.unlinkOwed.has(id))
+                return undefined;
+            try {
+                return await this.store.get(id);
+            }
+            catch {
+                this.storeErrors++;
+                return undefined;
+            }
+        }));
+        const ownMs = clock() - t0;
+        const resolved = new Map();
+        const missing = [];
+        for (let i = 0; i < uniq.length; i++) {
+            const id = uniq[i];
+            if (this.erased.has(id))
+                continue;
+            const hit = stored[i];
+            if (hit !== undefined) {
+                this.atRestHits++;
+                resolved.set(id, hit);
+            }
+            else {
+                this.misses++;
+                missing.push(id);
+            }
+        }
+        if (resolved.size > 0)
+            this.served("own", ownMs);
+        if (missing.length > 0) {
+            const t1 = clock();
+            const since = this.superseded.stamp();
+            const fetched = await this.inner.fetchByIds(missing, hint);
+            if (fetched.length > 0)
+                this.served("inner", clock() - t1);
+            const fills = [];
+            for (const b of fetched) {
+                resolved.set(b.cellId, b);
+                fills.push(this.fill(b, since));
+            }
+            for (const o of await Promise.all(fills))
+                this.recordFill(o);
+        }
+        return cellIds.map((id) => resolved.get(id)).filter((b) => b !== undefined);
+    }
+    async warmFill(cellIds) {
+        const targets = cellIds.filter((id) => !this.erased.has(id));
+        if (targets.length === 0)
+            return { attempted: 0, filled: 0, skippedPartial: 0, errors: 0 };
+        const since = this.superseded.stamp();
+        const fetched = await this.inner.fetchByIds(targets);
+        let filled = 0;
+        let skippedPartial = 0;
+        let errors = 0;
+        for (const o of await Promise.all(fetched.map((b) => this.fill(b, since)))) {
+            this.recordFill(o);
+            if (o === "filled")
+                filled++;
+            else if (o === "partial")
+                skippedPartial++;
+            else if (o === "error")
+                errors++;
+        }
+        return { attempted: targets.length, filled, skippedPartial, errors };
+    }
+    async persist(body, since = this.superseded.stamp()) {
+        const o = await this.fill(body, since);
+        this.recordFill(o);
+        return o;
+    }
+    stamp() {
+        return this.superseded.stamp();
+    }
+    async supersede(cellId, seq) {
+        this.superseded.supersede(cellId, seq);
+        this.unlinkOwed.add(cellId);
+        await this.store.delete(cellId);
+        this.unlinkOwed.delete(cellId);
+    }
+    async fill(b, since) {
+        if (b.partial)
+            return "partial";
+        if (this.erased.has(b.cellId))
+            return "erased";
+        if (!this.superseded.admits(b, since))
+            return "superseded";
+        if (this.store.accepts?.(b.cellId) === false)
+            return "unmappable";
+        try {
+            await this.store.put(b);
+            if (this.erased.has(b.cellId)) {
+                await this.store.delete(b.cellId);
+                return "erased";
+            }
+            if (!this.superseded.admits(b, since)) {
+                await this.store.delete(b.cellId);
+                return "superseded";
+            }
+            this.unlinkOwed.delete(b.cellId);
+            return "filled";
+        }
+        catch {
+            return "error";
+        }
+    }
+    served(step, ms) {
+        try {
+            this.opts.onServed?.(step, ms);
+        }
+        catch {
+        }
+    }
+    recordFill(o) {
+        if (o === "filled")
+            this.filled++;
+        else if (o === "partial")
+            this.skippedPartial++;
+        else if (o === "error")
+            this.storeErrors++;
+        else if (o === "unmappable")
+            this.unmappable++;
+        else if (o === "superseded")
+            this.olderNotWritten++;
+    }
+    async forget(cellId) {
+        this.erased.add(cellId);
+        await this.store.delete(cellId);
+    }
+    get stats() {
+        return {
+            atRestHits: this.atRestHits,
+            misses: this.misses,
+            filled: this.filled,
+            skippedPartial: this.skippedPartial,
+            storeErrors: this.storeErrors,
+            unmappable: this.unmappable,
+            olderNotWritten: this.olderNotWritten,
+        };
+    }
+}
+//# sourceMappingURL=persistent_body_source.js.map

package/dist/answer/persistent_body_source.js.map

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

package/dist/answer/saihm_body_source.d.ts

@@ -0,0 +1,27 @@
+import type { RecalledBody, SaihmReadPort } from "../saihm_client/types.js";
+import type { BodyFetchHint, BodySource } from "./types.js";
+export interface SaihmBodySourceConfig {
+    readonly recallTimeoutMs?: number;
+    readonly recallConcurrency?: number;
+}
+export declare class SaihmBodySource implements BodySource {
+    private readonly port;
+    private readonly cfg;
+    private index;
+    private forgotten;
+    private readonly erased;
+    private readonly concurrency;
+    private recallFailures;
+    private tier3Fallbacks;
+    constructor(port: SaihmReadPort, cfg?: SaihmBodySourceConfig);
+    forget(cellId: string): void;
+    fetchByIds(cellIds: readonly string[], hint?: BodyFetchHint): Promise<RecalledBody[]>;
+    invalidate(): void;
+    private ensureIndex;
+    private safeRecall;
+    get stats(): {
+        recallFailures: number;
+        tier3Fallbacks: number;
+    };
+}
+//# sourceMappingURL=saihm_body_source.d.ts.map

package/dist/answer/saihm_body_source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saihm_body_source.d.ts","sourceRoot":"","sources":["../../src/answer/saihm_body_source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAExF,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE5D,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAID,qBAAa,eAAgB,YAAW,UAAU;IAS9C,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG;IATtB,OAAO,CAAC,KAAK,CAAsC;IACnD,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,cAAc,CAAK;gBAGR,IAAI,EAAE,aAAa,EACnB,GAAG,GAAE,qBAA0B;IAOlD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAMtB,UAAU,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAkC3F,UAAU,IAAI,IAAI;YAKJ,WAAW;YAaX,UAAU;IAWxB,IAAI,KAAK,IAAI;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAE9D;CACF"}

package/dist/answer/saihm_body_source.js

@@ -0,0 +1,88 @@
+import { mapWithConcurrency } from "../util/concurrency.js";
+const DEFAULT_RECALL_CONCURRENCY = 4;
+export class SaihmBodySource {
+    port;
+    cfg;
+    index;
+    forgotten;
+    erased = new Set();
+    concurrency;
+    recallFailures = 0;
+    tier3Fallbacks = 0;
+    constructor(port, cfg = {}) {
+        this.port = port;
+        this.cfg = cfg;
+        const rc = cfg.recallConcurrency;
+        this.concurrency =
+            typeof rc === "number" && Number.isInteger(rc) && rc >= 1 ? rc : DEFAULT_RECALL_CONCURRENCY;
+    }
+    forget(cellId) {
+        this.erased.add(cellId);
+        this.index?.delete(cellId);
+        this.forgotten?.add(cellId);
+    }
+    async fetchByIds(cellIds, hint) {
+        const idx = await this.ensureIndex();
+        const found = new Map();
+        const want = new Set(cellIds.filter((id) => !this.forgotten.has(id)));
+        const q = hint?.query?.trim();
+        if (q) {
+            for (const b of await this.safeRecall(q)) {
+                if (want.has(b.cellId) && !found.has(b.cellId))
+                    found.set(b.cellId, b);
+            }
+        }
+        const misses = [...want].filter((id) => !found.has(id));
+        const recalled = await mapWithConcurrency(misses, this.concurrency, async (id) => {
+            const label = idx.get(id)?.label?.trim();
+            if (!label)
+                return undefined;
+            return (await this.safeRecall(label)).find((b) => b.cellId === id);
+        });
+        for (let i = 0; i < misses.length; i++) {
+            const hit = recalled[i];
+            if (hit)
+                found.set(misses[i], hit);
+        }
+        for (const id of want) {
+            if (found.has(id))
+                continue;
+            const e = idx.get(id);
+            if (!e || !e.label)
+                continue;
+            found.set(id, { cellId: id, plaintext: e.label, epoch: e.epoch, tier: e.tier, partial: true });
+            this.tier3Fallbacks++;
+        }
+        return cellIds.map((id) => found.get(id)).filter((b) => b !== undefined);
+    }
+    invalidate() {
+        this.index = undefined;
+        this.forgotten = undefined;
+    }
+    async ensureIndex() {
+        if (!this.index) {
+            const entries = await this.port.readIndex();
+            this.index = new Map(entries.filter((e) => !e.forgotten).map((e) => [e.cellId, e]));
+            this.forgotten = new Set(entries.filter((e) => e.forgotten).map((e) => e.cellId));
+            for (const id of this.erased) {
+                this.index.delete(id);
+                this.forgotten.add(id);
+            }
+        }
+        return this.index;
+    }
+    async safeRecall(query) {
+        try {
+            const opts = this.cfg.recallTimeoutMs !== undefined ? { timeoutMs: this.cfg.recallTimeoutMs } : undefined;
+            return await this.port.recallByQuery(query, opts);
+        }
+        catch {
+            this.recallFailures++;
+            return [];
+        }
+    }
+    get stats() {
+        return { recallFailures: this.recallFailures, tier3Fallbacks: this.tier3Fallbacks };
+    }
+}
+//# sourceMappingURL=saihm_body_source.js.map

package/dist/answer/saihm_body_source.js.map

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

package/dist/answer/structured_answerer.d.ts

@@ -0,0 +1,23 @@
+import type { Answerer, AnswerContext, AnswerRequest, RawAnswer } from "./types.js";
+export type CompleteFn = (prompt: string) => Promise<string>;
+export type AnswerOutcome = "answered" | "abstained" | "malformed-parse" | "backend-error";
+export interface AnswerTiming {
+    readonly outcome: AnswerOutcome;
+    readonly completeMs: number;
+    readonly parseMs: number;
+    readonly totalMs: number;
+}
+export interface StructuredAnswererConfig {
+    readonly modelId: string;
+    readonly onTiming?: (t: AnswerTiming) => void;
+}
+export declare function formatAnswerPrompt(ctx: AnswerContext): string;
+export declare class StructuredAnswerer implements Answerer {
+    private readonly complete;
+    private readonly cfg;
+    constructor(complete: CompleteFn, cfg: StructuredAnswererConfig);
+    get modelId(): string;
+    answer(req: AnswerRequest): Promise<RawAnswer>;
+    private emit;
+}
+//# sourceMappingURL=structured_answerer.d.ts.map

package/dist/answer/structured_answerer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured_answerer.d.ts","sourceRoot":"","sources":["../../src/answer/structured_answerer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEpF,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE7D,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,WAAW,GAAG,iBAAiB,GAAG,eAAe,CAAC;AAE3F,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,CAAC;CAC/C;AAmBD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAE7D;AAED,qBAAa,kBAAmB,YAAW,QAAQ;IAE/C,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBADH,QAAQ,EAAE,UAAU,EACpB,GAAG,EAAE,wBAAwB;IAGhD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAEK,MAAM,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC;IAkBpD,OAAO,CAAC,IAAI;CAGb"}

package/dist/answer/structured_answerer.js

@@ -0,0 +1,103 @@
+import { performance } from "node:perf_hooks";
+const MALFORMED = Object.freeze({
+    text: "",
+    abstained: false,
+    confidence: Number.NaN,
+    citedCellIds: Object.freeze([]),
+});
+const JSON_INSTRUCTION = "\n\nRespond with ONLY a single JSON object and nothing else — no prose, no " +
+    "markdown, no code fence. It must have EXACTLY these keys:\n" +
+    '{"text": string, "abstained": boolean, "confidence": number, "citedCellIds": string[]}\n' +
+    '- "text": the answer grounded in the retrieved memory, or "" if you abstain.\n' +
+    '- "abstained": true iff the retrieved memory does not answer the question.\n' +
+    '- "confidence": your calibrated confidence as a number in [0,1].\n' +
+    '- "citedCellIds": the cell ids you used, each copied VERBATIM from a cell=... ' +
+    "marker above; cite only ids shown there, or [] if abstaining.";
+export function formatAnswerPrompt(ctx) {
+    return ctx.prompt + JSON_INSTRUCTION;
+}
+export class StructuredAnswerer {
+    complete;
+    cfg;
+    constructor(complete, cfg) {
+        this.complete = complete;
+        this.cfg = cfg;
+    }
+    get modelId() {
+        return this.cfg.modelId;
+    }
+    async answer(req) {
+        const prompt = formatAnswerPrompt(req.context);
+        const t0 = performance.now();
+        let completion;
+        try {
+            completion = await this.complete(prompt);
+        }
+        catch {
+            const t = performance.now();
+            this.emit({ outcome: "backend-error", completeMs: t - t0, parseMs: 0, totalMs: t - t0 });
+            return MALFORMED;
+        }
+        const t1 = performance.now();
+        const { raw, outcome } = parseStructured(completion);
+        const t2 = performance.now();
+        this.emit({ outcome, completeMs: t1 - t0, parseMs: t2 - t1, totalMs: t2 - t0 });
+        return raw;
+    }
+    emit(t) {
+        this.cfg.onTiming?.(t);
+    }
+}
+const MALFORMED_PARSED = { raw: MALFORMED, outcome: "malformed-parse" };
+function parseStructured(s) {
+    if (typeof s !== "string")
+        return MALFORMED_PARSED;
+    const obj = extractJsonObject(s);
+    if (obj === undefined)
+        return MALFORMED_PARSED;
+    const { text, abstained, confidence, citedCellIds } = obj;
+    if (typeof text !== "string")
+        return MALFORMED_PARSED;
+    if (typeof abstained !== "boolean")
+        return MALFORMED_PARSED;
+    if (typeof confidence !== "number" ||
+        !Number.isFinite(confidence) ||
+        confidence < 0 ||
+        confidence > 1) {
+        return MALFORMED_PARSED;
+    }
+    if (!Array.isArray(citedCellIds) || !citedCellIds.every((c) => typeof c === "string")) {
+        return MALFORMED_PARSED;
+    }
+    const raw = { text, abstained, confidence, citedCellIds: citedCellIds };
+    return { raw, outcome: abstained ? "abstained" : "answered" };
+}
+function extractJsonObject(s) {
+    const trimmed = s.trim();
+    for (const cand of [trimmed, stripFence(trimmed), braceSpan(trimmed)]) {
+        if (cand === undefined)
+            continue;
+        const v = tryParse(cand);
+        if (typeof v === "object" && v !== null && !Array.isArray(v))
+            return v;
+    }
+    return undefined;
+}
+function tryParse(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return undefined;
+    }
+}
+function stripFence(s) {
+    const m = /^```(?:json)?\s*\n?([\s\S]*?)\n?```$/i.exec(s);
+    return m ? m[1] : undefined;
+}
+function braceSpan(s) {
+    const i = s.indexOf("{");
+    const j = s.lastIndexOf("}");
+    return i >= 0 && j > i ? s.slice(i, j + 1) : undefined;
+}
+//# sourceMappingURL=structured_answerer.js.map

package/dist/answer/structured_answerer.js.map

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

package/dist/answer/supersede.d.ts

@@ -0,0 +1,12 @@
+export declare class SupersedeLedger {
+    private clock;
+    private readonly cells;
+    stamp(): number;
+    supersede(cellId: string, seq?: string): void;
+    admits(body: {
+        readonly cellId: string;
+        readonly seq?: string;
+    }, since: number): boolean;
+    get size(): number;
+}
+//# sourceMappingURL=supersede.d.ts.map

package/dist/answer/supersede.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supersede.d.ts","sourceRoot":"","sources":["../../src/answer/supersede.ts"],"names":[],"mappings":"AAEA,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkF;IAExG,KAAK,IAAI,MAAM;IAIf,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ7C,MAAM,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAOxF,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/answer/supersede.js

@@ -0,0 +1,27 @@
+const DECIMAL = /^\d+$/;
+export class SupersedeLedger {
+    clock = 0;
+    cells = new Map();
+    stamp() {
+        return this.clock;
+    }
+    supersede(cellId, seq) {
+        const cur = this.cells.get(cellId)?.floor;
+        const v = seq !== undefined && DECIMAL.test(seq) ? BigInt(seq) : undefined;
+        const floor = cur === undefined ? v : v === undefined || v < cur ? cur : v;
+        this.clock++;
+        this.cells.set(cellId, { at: this.clock, floor });
+    }
+    admits(body, since) {
+        const c = this.cells.get(body.cellId);
+        if (c === undefined)
+            return true;
+        if (c.floor !== undefined && body.seq !== undefined && DECIMAL.test(body.seq))
+            return BigInt(body.seq) >= c.floor;
+        return since >= c.at;
+    }
+    get size() {
+        return this.cells.size;
+    }
+}
+//# sourceMappingURL=supersede.js.map

package/dist/answer/supersede.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supersede.js","sourceRoot":"","sources":["../../src/answer/supersede.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,GAAG,OAAO,CAAC;AAExB,MAAM,OAAO,eAAe;IAClB,KAAK,GAAG,CAAC,CAAC;IACD,KAAK,GAAG,IAAI,GAAG,EAAuE,CAAC;IAExG,KAAK;QACH,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,SAAS,CAAC,MAAc,EAAE,GAAY;QACpC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC;QAC1C,MAAM,CAAC,GAAG,GAAG,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3E,MAAM,KAAK,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3E,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,MAAM,CAAC,IAAwD,EAAE,KAAa;QAC5E,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACtC,IAAI,CAAC,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACjC,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC;QAClH,OAAO,KAAK,IAAI,CAAC,CAAC,EAAE,CAAC;IACvB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF"}

package/dist/answer/types.d.ts

@@ -0,0 +1,53 @@
+import type { RecalledBody } from "../saihm_client/types.js";
+export interface AnswerContext {
+    readonly prompt: string;
+    readonly cellIds: readonly string[];
+    readonly blockCount: number;
+    readonly neutralized: boolean;
+    readonly nonce: string;
+}
+export interface AnswerRequest {
+    readonly question: string;
+    readonly context: AnswerContext;
+}
+export interface RawAnswer {
+    readonly text: string;
+    readonly abstained: boolean;
+    readonly confidence: number;
+    readonly citedCellIds: readonly string[];
+}
+export interface Answerer {
+    readonly modelId: string;
+    answer(req: AnswerRequest): Promise<RawAnswer>;
+}
+export interface BodySource {
+    fetchByIds(cellIds: readonly string[], hint?: BodyFetchHint): Promise<RecalledBody[]>;
+}
+export interface ErasableBodySource extends BodySource {
+    forget(cellId: string): void | Promise<void>;
+}
+export type ServeStep = "own" | "inner";
+export interface BodyFetchHint {
+    readonly query?: string;
+}
+export interface AbstentionConfig {
+    readonly minConfidence: number;
+    readonly requireCitation: boolean;
+}
+export declare const DEFAULT_ABSTENTION: AbstentionConfig;
+export interface GroundingBudgetAudit {
+    readonly usedTokens: number;
+    readonly droppedForBudget: readonly string[];
+}
+export type GroundedAnswer = {
+    readonly answered: true;
+    readonly text: string;
+    readonly citations: readonly string[];
+    readonly droppedCitations: readonly string[];
+    readonly budget?: GroundingBudgetAudit;
+} | {
+    readonly answered: false;
+    readonly reason: "answerer-abstained" | "below-confidence-threshold" | "ungrounded" | "malformed-answer";
+    readonly budget?: GroundingBudgetAudit;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/answer/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/answer/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;CACjC;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CACvF;AAED,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AAED,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,OAAO,CAAC;AAExC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC;AAED,eAAO,MAAM,kBAAkB,EAAE,gBAAgE,CAAC;AAElG,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED,MAAM,MAAM,cAAc,GACtB;IACE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAC;CACxC,GACD;IACE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IACzB,QAAQ,CAAC,MAAM,EACX,oBAAoB,GACpB,4BAA4B,GAC5B,YAAY,GACZ,kBAAkB,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAC;CACxC,CAAC"}

package/dist/answer/types.js

@@ -0,0 +1,2 @@
+export const DEFAULT_ABSTENTION = { minConfidence: 0.5, requireCitation: true };
+//# sourceMappingURL=types.js.map

package/dist/answer/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/answer/types.ts"],"names":[],"mappings":"AA8CA,MAAM,CAAC,MAAM,kBAAkB,GAAqB,EAAE,aAAa,EAAE,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC"}

package/dist/assemble/brief.d.ts

@@ -0,0 +1,83 @@
+import type { RankedHit, MatchProvenance } from "../retrieval/semantic.js";
+import type { LinkGraph } from "../retrieval/link_graph.js";
+import type { StandingStatus } from "../standing/standing_answers.js";
+export type Freshness = StandingStatus;
+export type LabelLookup = (cellId: string) => string | undefined;
+export type FreshnessLookup = (cellId: string) => Freshness;
+export type ThreadLookup = (cellId: string) => string | undefined;
+export interface AssemblyConfig {
+    readonly bridgeDegreeFraction: number;
+    readonly minBridgeDegree: number;
+}
+export declare const DEFAULT_ASSEMBLY: AssemblyConfig;
+export declare function claimAge(ingestEpoch: number | undefined, nowEpoch: number | undefined): {
+    ingestEpoch?: number;
+    ageHours?: number;
+};
+export interface BriefCell {
+    readonly cellId: string;
+    readonly rank: number;
+    readonly label?: string;
+    readonly matched?: MatchProvenance;
+    readonly freshness: Freshness;
+    readonly supersededBy?: string;
+    readonly ingestEpoch?: number;
+    readonly ageHours?: number;
+}
+export interface BriefGroup {
+    readonly members: readonly BriefCell[];
+    readonly bestRank: number;
+    readonly anchorLabel?: string;
+    readonly edges: number;
+}
+export interface BriefConnector {
+    readonly cell: BriefCell;
+    readonly degree: number;
+    readonly touches: readonly number[];
+}
+export interface ThreadGroup {
+    readonly thread: string;
+    readonly members: readonly BriefCell[];
+    readonly bestRank: number;
+}
+export interface ThreadView {
+    readonly consulted: boolean;
+    readonly groups: readonly ThreadGroup[];
+    readonly unstamped: number;
+    readonly spanning: number;
+}
+export type BriefVerdict = "empty" | "unstructured" | "assembled";
+export interface AssemblyStats {
+    readonly cells: number;
+    readonly inducedEdges: number;
+    readonly groups: number;
+    readonly multiCellGroups: number;
+    readonly singletons: number;
+    readonly connectors: number;
+    readonly largestGroup: number;
+    readonly freshnessKnown: number;
+    readonly freshnessUnknown: number;
+    readonly stale: number;
+    readonly duplicatesDropped: number;
+}
+export interface Brief {
+    readonly verdict: BriefVerdict;
+    readonly posture: readonly BriefCell[];
+    readonly groups: readonly BriefGroup[];
+    readonly connectors: readonly BriefConnector[];
+    readonly threads: ThreadView;
+    readonly stats: AssemblyStats;
+    readonly note: string;
+}
+export interface AssembleOptions {
+    readonly labelOf?: LabelLookup;
+    readonly freshnessOf?: FreshnessLookup;
+    readonly posture?: readonly RankedHit[];
+    readonly nowEpoch?: number;
+    readonly staleAfterHours?: number;
+    readonly graph?: LinkGraph;
+    readonly threadOf?: ThreadLookup;
+    readonly config?: Partial<AssemblyConfig>;
+}
+export declare function assembleBrief(hits: readonly RankedHit[], opts?: AssembleOptions): Brief;
+//# sourceMappingURL=brief.d.ts.map