@securecoms/agent-bridge 0.28.1 → 0.29.0

package/dist/memory/unified/read-book.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Unified memory (spec section 8.1; H-4, U11, U15): the per-turn read. The capture is taken first (U11); pinned facts come
+ * from a cache keyed by the owner-DM scope id (never per agent, H-A) and filled from the worker under the memory mutex;
+ * the search runs on the worker; everything shares the turn kind's one deadline (600 ms typed, 250 ms voice). Past it:
+ * pinned facts only (from a current cache). Nothing attaches late. Delivery re-checks the capture and the owner scope.
+ * No SQL here (T-33): the constants come from the import-free ranking-core-constants.ts, never ranking-core.ts.
+ */
+import { type SqliteMlsStateStore } from "@agentvault/connect-mls-store";
+import type { Embedder } from "../embedder/client.js";
+import type { RankingClient } from "./ranking-client.js";
+export interface UnifiedFrameItem {
+    block: "pinned" | "owner" | "reference";
+    id: number;
+    source: string;
+    at: number;
+    text: string;
+}
+/** The runtime's parseUnified limits (connect-agent-runtime memory-unified.ts): one item over them blanks the whole block there. */
+export declare const FRAME_ITEMS_MAX = 210;
+export declare const FRAME_TEXT_MAX = 1000;
+export declare class UnifiedReadBook {
+    private readonly d;
+    private readonly entries;
+    private readonly pinCache;
+    /**
+     * Plan audit M-6: the texts DELIVERED with each message, kept until ack/nack/retire (`drop`), so a forget that follows
+     * a pin in the same message (the pin's dropChannelLocked empties `entries`) still finds its text for the Forgot: line.
+     * Cleared by a clear (dropAllLocked) and an owner-scope purge (dropScopeLocked), never by a channel cache refresh.
+     */
+    private readonly shown;
+    private reads;
+    /** Fix round 1: turns whose read missed its deadline (a local late, or a pins/query answer late or failed); one per turn. */
+    private misses;
+    /**
+     * Fix round 1 (ruling): bumped by every drop*Locked and by bumpGeneration (Task 28: a pin insert). Taken before the
+     * pins request and compared at install and before the entry is kept, so a drop during an await is never undone.
+     */
+    private gen;
+    /** Fix round 2: reads thrown away because the generation moved (a drop, a pin insert); not deadline misses. */
+    private discarded;
+    constructor(d: {
+        store: Pick<SqliteMlsStateStore, "itemCapture">;
+        ranking: Pick<RankingClient, "query" | "pins">;
+        embedder: Embedder;
+        embedOn: () => boolean;
+        indexKey: Uint8Array;
+        exclusive: <T>(fn: () => Promise<T>) => Promise<T>;
+        now?: () => number;
+    });
+    /** The health key memory_reads: owner-DM reads started since boot. */
+    readsAttempted(): number;
+    /** The health key memory_deadline_misses: owner-DM turns that got no search result in time (U15). */
+    deadlineMisses(): number;
+    /** The health key memory_reads_discarded: reads not kept because a drop or pin insert moved the generation during them. */
+    readsDiscarded(): number;
+    /** Invalidates the pin cache and every read in flight (Task 28 calls it, under the memory mutex, when a pin is inserted). */
+    bumpGeneration(): void;
+    prepare(p: {
+        messageId: string;
+        channelId: string;
+        scopeId: string;
+        text: string;
+        kind: "text" | "voice";
+    }): Promise<void>;
+    /** ws flush (synchronous): the entry's own channel and owner scope, its capture still current (H-4, U11). */
+    deliverable(messageId: string, channelId: string, scopeIdNow: string): {
+        items: UnifiedFrameItem[];
+        pinnedMore: number;
+    } | undefined;
+    /** Section 7.4 step 3: texts of owner-trust TYPED items shown with this delivery (never owner_voice, never reference). */
+    coverageTexts(messageId: string, shown: ReadonlySet<number>): string[];
+    /** M-6: what was DELIVERED with this message (kept until ack), not the prepare-time entry a cache refresh can drop. */
+    shownText(messageId: string, itemId: number): string | undefined;
+    /** Task 29 fix round 1: a forgotten item's delivered text leaves the shown map at once (not only at ack). */
+    forgetShown(messageId: string, itemId: number): void;
+    drop(messageId: string): void;
+    dropAllLocked(): void;
+    dropChannelLocked(channelId: string): void;
+    dropScopeLocked(scopeId: string): void;
+}

package/dist/memory/unified/switch.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Unified agent memory, part 1 (spec 2026-10-10 §18, R-U25): a compiled literal, default off, flipped only by the
+ * release task after the Mac mini live check. A backend flag is not used: it would let the server widen cross-scope
+ * reads. While false the bridge behaves as 0.28.2 on every memory path.
+ */
+export declare const UNIFIED_MEMORY_PART1 = true;
+/** `injected` is the test seam (the bridge agent's deps field for this switch); production never passes it (switch.arch.test.ts). */
+export declare function unifiedPart1On(injected?: boolean): boolean;

package/dist/memory/unified/text.d.ts

@@ -0,0 +1,15 @@
+export declare function foldText(s: string): string;
+export declare function tokens(s: string): string[];
+/** H-1, H-2: English cardinals and ordinals count as digit-bearing (65 words, frozen). */
+export declare const NUMBER_WORDS: ReadonlySet<string>;
+/** A canonical Roman numeral (lower case after foldText). Note: "i", "v", "x" and "mix" match; Task 35 measures the effect. */
+export declare function isRomanNumeral(t: string): boolean;
+export declare function isDigitBearing(t: string): boolean;
+/** §11.5: a fixed English stop-word list (126 words: the NLTK English list without its contractions), never indexed. */
+export declare const STOP_WORDS: ReadonlySet<string>;
+/** L-3: the fixed English suffix set for query-side expansion (the plan enumerates it, spec §11.5). y↔ies is added below. */
+export declare const QUERY_SUFFIXES: readonly string[];
+/** §11.5: an item's exact, de-duplicated tokens, stop words dropped. No stems. */
+export declare function indexTokens(text: string): string[];
+/** L-3: the token, the token plus each suffix, the token minus each suffix it ends with (never below 3 characters), and y↔ies. */
+export declare function queryExpansions(t: string): string[];

package/dist/memory/unified/worker-protocol.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Unified memory (spec section 8.5, H-7, T-33): the messages between the bridge and its ranking worker. Only ids, scores and
+ * the opened texts of the items selected for a turn cross back. No message type FROM the worker carries a vector or a
+ * raw sealed buffer (worker-protocol.arch.test.ts, Task 14). The query vector goes TO the worker.
+ */
+import type { ItemKind, ItemSource, ItemTrust, ScopeKind } from "@agentvault/connect-mls-store/memory-items";
+export interface WorkerInit {
+    dbPath: string;
+    identityId: string;
+    storeKey: Uint8Array;
+    modelId: string;
+    threshold: number;
+    warm: boolean;
+    /** Plan Task 35, the recall eval only: replaces OWNER_SCOPE_PRIOR / RECENCY_SLOPE (0.05 since U1-G). Production never sets them (worker-protocol.arch.test.ts). */
+    priorOverride?: number;
+    recencySlopeOverride?: number;
+}
+export interface RankQuery {
+    scopes: string[];
+    ownerScope: string | null;
+    vec: Float32Array | null;
+    macs: Uint8Array[];
+    historyConversation: string;
+    currentMessageId: string;
+    maxItems: number;
+    maxChars: number;
+    nowMs: number;
+    excludeOriginIds: string[];
+}
+export interface OpenedItem {
+    itemId: number;
+    scopeKind: ScopeKind;
+    scopeId: string;
+    channelId: string;
+    kind: ItemKind;
+    originId: string;
+    originAt: number;
+    source: ItemSource;
+    trust: ItemTrust;
+    text: string;
+}
+export type ToWorker = {
+    type: "query";
+    id: number;
+    q: RankQuery;
+} | {
+    type: "pins";
+    id: number;
+    scopeId: string;
+    maxChars: number;
+} | {
+    type: "pending";
+    id: number;
+    limit: number;
+} | {
+    type: "added";
+    itemIds: number[];
+} | {
+    type: "removed";
+    itemIds: number[];
+} | {
+    type: "reset";
+};
+export type FromWorker = {
+    type: "ready";
+    hot: number;
+    hotBytes: number;
+} | {
+    type: "result";
+    id: number;
+    items: OpenedItem[];
+    openFailed: number;
+} | {
+    type: "pins";
+    id: number;
+    pins: OpenedItem[];
+    more: number;
+    openFailed: number;
+} | {
+    type: "pending";
+    id: number;
+    rows: Array<{
+        itemId: number;
+        channelId: string;
+        scopeKind: ScopeKind;
+        scopeId: string;
+        originId: string;
+        chunkIndex: number;
+        text: string;
+    }>;
+} | {
+    type: "stats";
+    hot: number;
+    hotBytes: number;
+}
+/** Final review bridge M-4: a request whose handler threw; the client answers it `failed` (a miss), the worker lives on. */
+ | {
+    type: "failed";
+    id: number;
+} | {
+    type: "fatal";
+};