@securecoms/agent-bridge 0.27.0 → 0.28.0

package/dist/memory/consumer-recall.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Spec §7.1, §7.2 Q4: recall is attached at DELIVERY, to the frame copy only,
+ * for a /v1/ws runtime socket that declared memory_recall and never claimed a
+ * harness. The buffer, the sealed runtime_inbox and `inflight` keep the
+ * original, which has no recall, so a re-buffered message carries none to an
+ * HTTP or harness consumer either. Q1 to Q3 and Q6 live in the source
+ * (`BridgeAgent.recallForDelivery`), which reads the ORIGINAL message's frozen
+ * authorization, never the consumer copy.
+ */
+import type { BridgeMessage } from "../bridge-agent.js";
+import type { RecallItem } from "./recall/recall-book.js";
+export declare function withConsumerRecall(out: BridgeMessage, original: BridgeMessage, session: {
+    consumer: "runtime" | "unknown";
+    harnessClaimed?: boolean;
+    recallConsumer: boolean;
+}, src: {
+    recallForDelivery(m: BridgeMessage): readonly RecallItem[] | undefined;
+}): {
+    message: BridgeMessage;
+    shown: ReadonlySet<number>;
+};

package/dist/memory/embedder/client.d.ts

@@ -0,0 +1,103 @@
+import { type ServiceLog } from "../../service-log.js";
+import { type EmbeddingManifest } from "./manifest.js";
+import { type SpawnHandle } from "./spawn.js";
+export type EmbedderReason = "verify_failed" | "load_failed" | "not_imported" | "worker_failed" | "embedder_unavailable" | "embedder_mismatch" | "embedder_crashed" | "unsupported_platform" | "run_dir_refused" | "acl_unverified";
+export type EmbedderState = {
+    state: "off";
+} | {
+    state: "preparing";
+} | {
+    state: "ready";
+} | {
+    state: "unavailable";
+    reason: EmbedderReason;
+};
+export interface Embedder {
+    state(): EmbedderState;
+    ensureStarted(): void;
+    filesPresent(): boolean;
+    embed(text: string, priority: 0 | 1, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Float32Array>;
+}
+export declare const INERT_EMBEDDER: Embedder;
+/**
+ * E1.7 (owner change 2026-10-08): Windows uses loopback TCP and ships behind the compiled switch in windows.ts, OFF until
+ * the owner's live check (Task 27b) passes. While it is off a win32 bridge reports `unsupported_platform` and never
+ * downloads, spawns or connects.
+ */
+export { WINDOWS_SEMANTIC_ENABLED, windowsSemanticOn } from "./windows.js";
+export interface EmbedderClientOptions {
+    identityId: string;
+    home: string;
+    source: "download" | "import_only";
+    fetchImpl: typeof fetch;
+    manifest?: EmbeddingManifest;
+    /** Default: spawnEmbedder (spawn.ts). A returned handle's exit code maps to a reason (see EXIT_REASON). */
+    spawn?: () => SpawnHandle | void;
+    now?: () => number;
+    log?: ServiceLog;
+    helloTimeoutMs?: number;
+    connectWaitMs?: number;
+    /** Test seam: the files are not on disk in unit tests (the real check is missingFiles under `home`). */
+    filesPresentOverride?: boolean;
+    /** Test seams for E1.7: the platform and the Windows switch. */
+    platform?: NodeJS.Platform;
+    windowsEnabled?: boolean;
+    /** Where dist/embedder.js lives (default: beside this bundle). */
+    distDir?: string;
+    /** Windows seams (Task 11d): the environment holding LOCALAPPDATA, and the ACL check (default windows.ts verifyRunDirAcl). */
+    env?: NodeJS.ProcessEnv;
+    verifyAcl?: (path: string) => Promise<boolean> | boolean;
+}
+export declare class EmbedderClient implements Embedder {
+    private readonly o;
+    private st;
+    private sock;
+    private chan;
+    private seq;
+    private readonly pending;
+    private lastSpawn;
+    private starts;
+    private crashedUntil;
+    private notBefore;
+    private verifyAttempt;
+    private fails;
+    private closed;
+    private readonly m;
+    private readonly now;
+    private readonly log;
+    constructor(o: EmbedderClientOptions);
+    /** Pure: the report path reads this, and reading it never starts, connects or spawns anything (plan audit LOW). */
+    state(): EmbedderState;
+    private tcp;
+    filesPresent(): boolean;
+    private key;
+    /** macOS/Linux: ~/.securecoms/run/embedder. Windows: %LOCALAPPDATA%\\SecureComs\\run\\embedder (E1.7). */
+    private runDir;
+    private paths;
+    /** E1.7 (P-7 delta M2): the run directory's ACL and the token file's own; a token file is re-checked whenever it changes. */
+    /**
+     * 11d review M2: the checks are async (icacls and whoami never block the bridge's event loop; the SID is read once per
+     * process). The directory's result is cached by the directory's identity and re-checked (`force`) at every start() and
+     * right before every spawn; the token file's check is coupled to it: re-run whenever the file changes and whenever the
+     * directory is re-checked.
+     */
+    private aclDir;
+    private aclToken;
+    private aclOk;
+    private fail;
+    ensureStarted(): void;
+    private start;
+    /** The embedder's fixed-code status file (exit 3). True when it decided the state. */
+    private readStatus;
+    /** Audit r1 M4: a load-time verify failure deletes this manifest's files so the next start re-downloads; retry on the backoff. */
+    private failVerifyOrLoad;
+    /** Rule 3: connect, prove the token, require the server's proof and a matching hello within the timeout. True when decided. */
+    private connectOnce;
+    private onFrame;
+    embed(text: string, priority: 0 | 1, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Float32Array>;
+    close(): void;
+}

package/dist/memory/embedder/download.d.ts

@@ -0,0 +1,28 @@
+import { type ServiceLog } from "../../service-log.js";
+import type { EmbeddingManifest, ManifestFile } from "./manifest.js";
+/** `not_imported`: the machine is `import_only` (spec §6.6), so nothing was fetched. */
+export type EnsureResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "verify_failed" | "network" | "not_imported";
+    file?: ManifestFile["name"];
+};
+export declare function retryDelayMs(attempt: number): number;
+/** A file is missing unless it is a regular file of exactly the manifest size (a wrong size is never the verified bytes). */
+export declare function missingFiles(root: string, m: EmbeddingManifest): ManifestFile[];
+/**
+ * Audit r1 M4: after a load-time `verify_failed`, delete this manifest's files so the
+ * next ensure re-downloads them, instead of rehashing the same bad bytes every turn.
+ * The directories are 0555, so make each writable first; it is resealed on install.
+ */
+export declare function removeModelFiles(root: string, m: EmbeddingManifest): void;
+export declare function ensureModelFiles(o: {
+    modelSource: "download" | "import_only";
+    manifest: EmbeddingManifest;
+    root: string;
+    origin: string;
+    fetchImpl: typeof fetch;
+    log?: ServiceLog;
+    stallTimeoutMs?: number;
+}): Promise<EnsureResult>;

package/dist/memory/embedder/embedder-main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/memory/embedder/embedder-paths.d.ts

@@ -0,0 +1,14 @@
+import type { EmbeddingManifest } from "./manifest.js";
+export declare function embedderKey(m: EmbeddingManifest): string;
+export declare const embedderRunDir: (home?: string) => string;
+export declare const embedderPaths: (dir: string, key: string) => {
+    sock: string;
+    token: string;
+    lock: string;
+    status: string;
+    pid: string;
+};
+/** sun_path is 104 bytes on macOS (108 on Linux) including the NUL; the server's temp bind name is the longest path bound. */
+export declare const SOCKET_PATH_MAX = 103;
+/** Spec §20 E1.7: %LOCALAPPDATA%\SecureComs\run\embedder on Windows (native separators; on Windows that is win32). */
+export declare const windowsRunDir: (env?: NodeJS.ProcessEnv) => string;

package/dist/memory/embedder/engine.d.ts

@@ -0,0 +1,21 @@
+export declare class HashMismatch extends Error {
+}
+export declare function verifyBuffer(bytes: Uint8Array, sha256: string, size: number): void;
+export declare function pool(hidden: Float32Array, tokens: number, dims: number, mode: "mean" | "cls"): Float32Array;
+export declare function l2normalize(v: Float32Array): Float32Array;
+type FileSpec = {
+    path: string;
+    sha256: string;
+    size: number;
+};
+export declare function loadVerified<S>(o: {
+    read: (path: string) => Uint8Array;
+    model: FileSpec;
+    vocab: FileSpec;
+    wasm: FileSpec;
+    createSession: (modelBytes: Uint8Array, wasmBytes: Uint8Array) => Promise<S>;
+}): Promise<{
+    session: S;
+    vocabText: string;
+}>;
+export {};

package/dist/memory/embedder/gc.d.ts

@@ -0,0 +1,2 @@
+export declare function touchUserMarker(root: string, modelId: string, identityId: string): void;
+export declare function gcModels(root: string, keepModelIds: readonly string[], now: number, maxAgeMs?: number): string[];

package/dist/memory/embedder/handshake.d.ts

@@ -0,0 +1,7 @@
+export declare const PREAUTH_MAX_CONNECTIONS = 64, PREAUTH_MAX_LINE = 256, PREAUTH_TIMEOUT_MS = 250;
+/** Spec §20 E1.7: on the Windows loopback port (reachable by other local users) at most 8 unauthenticated connections. */
+export declare const PREAUTH_MAX_CONNECTIONS_TCP = 8;
+export declare const nonce: () => string;
+export declare const macClient: (token: string, ns: string, nc: string, protocol?: number) => string;
+export declare const macServer: (token: string, ns: string, nc: string, protocol?: number) => string;
+export declare function macEqual(a: string, b: string): boolean;

package/dist/memory/embedder/heartbeats.d.ts

@@ -0,0 +1,4 @@
+export declare const HEARTBEAT_FUTURE_SKEW_MS = 60000;
+export declare const HEARTBEAT_STALE_MS = 30000;
+export declare function heartbeatAgeFresh(ageMs: number, staleMs?: number): boolean;
+export declare function anyHeartbeatFresh(dir: string, now: number, staleMs?: number): boolean;

package/dist/memory/embedder/import-bundle.d.ts

@@ -0,0 +1,6 @@
+import type { EmbeddingManifest } from "./manifest.js";
+export declare class ModelImportError extends Error {
+}
+export declare function importModelBundle(srcDir: string, root: string, m: EmbeddingManifest): Promise<{
+    imported: string[];
+}>;

package/dist/memory/embedder/inner-source.d.ts

@@ -0,0 +1,2 @@
+/** The inner worker as a data: URL built from source text read ONCE; every (re)spawn uses the same text. */
+export declare function innerWorkerUrl(source: string): URL;

package/dist/memory/embedder/layout.d.ts

@@ -0,0 +1,36 @@
+import type { ManifestFile } from "./manifest.js";
+export declare const defaultModelsRoot: (home?: string) => string;
+/** `.partial` is a SIBLING of the embeddings root, on the same filesystem, so the final rename is atomic and GC never walks it. */
+export declare const partialDir: (root: string) => string;
+export declare const filePath: (root: string, modelId: string, f: ManifestFile) => string;
+/** A path component in the managed tree is not a real directory (a symlink, a file, anything else). Fixed text. */
+export declare class LayoutRefused extends Error {
+    constructor();
+}
+/**
+ * Walk `<dirname(root)>/<basename(root)>/<...parts>`: the models dir, the embeddings
+ * root (or `.partial`, by passing it as the first part with `fromModelsDir`), then each
+ * part. Each component must be a real directory, or be absent: then, with `create`,
+ * it is created ONE level at a time (never recursive), else the walk stops and returns
+ * null. Only the models dir's own parents (the user's home) may be created recursively.
+ * Returns the final directory path, or null when absent and `create` is false.
+ */
+export declare function plainDirChain(root: string, parts: readonly string[], opts: {
+    create: boolean;
+    fromModelsDir?: boolean;
+    mode?: number;
+}): string | null;
+/** True when the file is present as a regular file of the manifest size (a cheap check; the hash is verified at load, §6.5). */
+export declare function presentWithSize(p: string, size: number): boolean;
+/** A model path that holds something no rename can replace (a directory, a FIFO, a socket). A symlink is replaced by the rename itself. */
+export declare function wrongTypeAt(p: string): boolean;
+/**
+ * Move an already-verified partial into place: atomic rename, file 0444, directory 0555.
+ * The partial is always gone afterwards. When another writer has already placed a
+ * correct-size file, that file is kept and this partial is discarded (every writer
+ * writes identical verified bytes, spec §6.4 item 5). Throws LayoutRefused before
+ * touching anything when a directory on the way is not a real directory.
+ */
+export declare function installVerified(root: string, modelId: string, f: ManifestFile, partial: string, opts: {
+    replace: boolean;
+}): void;

package/dist/memory/embedder/locks.d.ts

@@ -0,0 +1,17 @@
+export declare const LOCK_STALE_MS = 10000;
+/** Two boot-time readings of one boot can differ by clock adjustments; different boots differ by far more. */
+export declare const BOOT_TOLERANCE_S = 60;
+/** The seams a test injects to play several processes in one. */
+export interface LockEnv {
+    pid: number;
+    alive(pid: number): boolean;
+    bootTime(): number;
+    startTime(): number;
+    /** Test hook: runs after a lock was judged stale and before it is renamed aside. */
+    beforeSteal?(): void;
+}
+export declare const PROCESS_LOCK_ENV: LockEnv;
+export declare function takeLock(path: string, now?: () => number, env?: LockEnv): {
+    id: string;
+} | null;
+export declare function releaseLock(path: string, id: string): void;

package/dist/memory/embedder/manifest.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Spec §6.3: compiled into each release. The trust root is the Connector
+ * release: no hash, size or URL is ever fetched from the network or the backend.
+ * A model change is a new release with a new model_id and new immutable paths.
+ * Source of every value: scripts/qualification/semantic-memory/decision.json (7b-0).
+ * Written early by Task 9 (the tokenizer test consumes it); Task 10 adds manifest.test.ts.
+ */
+import type { TokenizerOptions } from "./tokenizer.js";
+export declare const MODEL_ORIGIN = "https://downloads.securecoms.ai";
+export interface ManifestFile {
+    readonly name: "model.onnx" | "vocab.txt" | "LICENSE" | "NOTICE";
+    readonly urlPath: string;
+    readonly sha256: string;
+    readonly size: number;
+}
+export interface EmbeddingManifest {
+    readonly modelId: string;
+    readonly dims: 384;
+    readonly maxTokens: number;
+    readonly pooling: "mean" | "cls";
+    readonly normalize: boolean;
+    readonly similarityThreshold: number;
+    readonly onnxInputs: readonly string[];
+    readonly onnxOutput: string;
+    readonly wasmSha256: string;
+    readonly wasmSize: number;
+    readonly files: readonly ManifestFile[];
+}
+export declare const EMBEDDING_MANIFEST: EmbeddingManifest;
+export declare const TOKENIZER_OPTIONS: TokenizerOptions;

package/dist/memory/embedder/no-dial.d.ts

@@ -0,0 +1,3 @@
+export declare const NO_DIAL_MESSAGE = "outbound connections are forbidden in the embedder";
+/** Patch node:net in this thread so connect, createConnection and Socket#connect throw. Idempotent. */
+export declare function forbidOutbound(): void;

package/dist/memory/embedder/protocol.d.ts

@@ -0,0 +1,55 @@
+/** Spec §20 E1.2 to E1.4: newline-delimited JSON frames over the local socket; vectors as base64 little-endian float32. */
+export declare const EMBEDDER_PROTOCOL = 1;
+export declare const MAX_TEXT_BYTES = 8192;
+/**
+ * 11b review M4: the longest sealed job line. Worst case for MAX_TEXT_BYTES of text: every byte a control character that
+ * JSON escapes as \u00XX (6 bytes) = 49152, plus the frame's other fields (< 100), plus the 24-byte nonce and 16-byte
+ * tag = 49292 bytes sealed, which base64 makes 65724. 69632 (68 KiB) bounds it with room, so a legal text always
+ * reaches the length check (too_long) and is never cut off by the line cap.
+ */
+export declare const MAX_LINE_BYTES = 69632;
+export type ClientFrame = {
+    t: "hello";
+    nc: string;
+    mac_c: string;
+} | {
+    t: "job";
+    job_id: number;
+    priority: 0 | 1;
+    text: string;
+} | {
+    t: "cancel";
+    job_id: number;
+};
+export interface ServerChallenge {
+    t: "challenge";
+    protocol: number;
+    ns: string;
+}
+export interface ServerHello {
+    t: "hello";
+    mac_s: string;
+    protocol: number;
+    model_id: string;
+    model_sha256: string;
+    wasm_sha256: string;
+    dims: number;
+}
+export type ServerFrame = ServerHello | {
+    t: "result";
+    job_id: number;
+    model_id: string;
+    vec: string;
+} | {
+    t: "error";
+    job_id: number;
+    code: "busy" | "too_long" | "worker_reset" | "failed";
+};
+export declare function encodeVec64(v: Float32Array): string;
+export declare function decodeVec64(s: string): Float32Array | null;
+/**
+ * Newline-delimited reader. Every line (and any unterminated remainder) is capped in UTF-8 bytes; past the cap the
+ * reader calls onOverflow once and delivers nothing more. Chunks are decoded with a StringDecoder, so a multi-byte
+ * character split across chunks is not corrupted.
+ */
+export declare function lineReader(onLine: (line: string) => void, onOverflow: () => void, maxLine?: number | (() => number)): (chunk: Buffer) => void;

package/dist/memory/embedder/run-dir.d.ts

@@ -0,0 +1,11 @@
+export declare class RunDirRefused extends Error {
+}
+type Lstat = (p: string) => {
+    isSymbolicLink(): boolean;
+    isDirectory(): boolean;
+    uid: number;
+    mode: number;
+};
+/** `lstat` is a test seam (Task 12 gate): it lets a test give the run directory and its parent different owners. */
+export declare function ensureRunDir(dir: string, uid?: number, lstat?: Lstat): void;
+export {};

package/dist/memory/embedder/scheduler.d.ts

@@ -0,0 +1,24 @@
+/** Spec §20 E1.4: queries before background, machine-wide; round-robin across connections; per-connection caps; background rate and call hold. */
+export declare const MAX_QUERIES_PER_CONN = 4, MAX_BACKGROUND_PER_CONN = 1, MAX_CONNECTIONS = 32, BACKGROUND_PER_SECOND = 16;
+export interface Job {
+    readonly conn: number;
+    readonly jobId: number;
+    readonly priority: 0 | 1;
+    readonly text: string;
+}
+export declare class Scheduler {
+    private readonly o;
+    private readonly q;
+    private readonly last;
+    private bgStarts;
+    constructor(o: {
+        now(): number;
+        backgroundHeld(): boolean;
+    });
+    enqueue(j: Job): "ok" | "busy";
+    cancel(conn: number, jobId: number): boolean;
+    dropConnection(conn: number): void;
+    size(): number;
+    private take;
+    next(): Job | undefined;
+}

package/dist/memory/embedder/server.d.ts

@@ -0,0 +1,46 @@
+/** Spec §20: the shared embedder's socket server. One connection is one bridge; results only to their own connection; no cache. */
+import { type AddressInfo } from "node:net";
+import { type ServiceLog } from "../../service-log.js";
+import { type ServerHello } from "./protocol.js";
+import { SOCKET_PATH_MAX } from "./embedder-paths.js";
+export { SOCKET_PATH_MAX };
+export declare class AlreadyRunning extends Error {
+}
+export type StopReason = "closed" | "idle" | "reset_failed";
+/** 11b review M3: a reset that hangs is a failed reset. */
+export declare const RESET_TIMEOUT_MS = 30000;
+/** 11b review L1: a connection that does not read its results is closed once this much is queued for it. */
+export declare const MAX_PENDING_WRITE_BYTES: number;
+export interface EmbedderServerOptions {
+    dir: string;
+    key: string;
+    hello: Omit<ServerHello, "t" | "mac_s">;
+    embed(text: string): Promise<Float32Array>;
+    resetInner(): Promise<void>;
+    now?: () => number;
+    jobTimeoutMs?: number;
+    helloTimeoutMs?: number;
+    idleMs?: number;
+    backgroundHeld?: () => boolean;
+    log?: ServiceLog;
+    uid?: number;
+    /** Called once when the server has stopped and removed its own files; the reason tells the process how to exit. */
+    onExit?: (reason: StopReason) => void;
+    /** How long a reset of the inner worker may take before it counts as failed (default RESET_TIMEOUT_MS). */
+    resetTimeoutMs?: number;
+    /** Re-check interval while jobs wait on the background hold or rate limit (default 250 ms). */
+    retryMs?: number;
+    /**
+     * P-7 (spec §20 E1.7): "unix" (macOS, Linux: a socket in the 0700 run directory) or "tcp" (Windows: 127.0.0.1 only, an
+     * ephemeral port published with the token). Default: "tcp" on win32, else "unix". Windows ships behind the bridge's
+     * compiled WINDOWS_SEMANTIC_ENABLED switch.
+     */
+    transport?: "unix" | "tcp";
+}
+export declare class SocketPathTooLong extends Error {
+}
+export declare function startEmbedderServer(o: EmbedderServerOptions): Promise<{
+    close(): Promise<void>;
+    connections(): number;
+    address(): AddressInfo | string | null;
+}>;

package/dist/memory/embedder/session.d.ts

@@ -0,0 +1,17 @@
+export declare function deriveSessionKeys(token: string, ns: string, nc: string): {
+    c2s: Uint8Array;
+    s2c: Uint8Array;
+};
+/** One direction pair. A frame is base64(nonce24 ‖ ciphertext); its AAD binds the direction and a per-direction counter, so a replayed, reordered or dropped frame fails. */
+export declare class SealedChannel {
+    private readonly sendKey;
+    private readonly recvKey;
+    private readonly sendLabel;
+    private readonly recvLabel;
+    private sendSeq;
+    private recvSeq;
+    constructor(sendKey: Uint8Array, recvKey: Uint8Array, sendLabel: "c2s" | "s2c", recvLabel: "c2s" | "s2c");
+    seal(frame: unknown): string;
+    /** Null on any failure (bad base64, wrong key, tampering, replay): the caller closes the connection. */
+    open(line: string): Record<string, unknown> | null;
+}

package/dist/memory/embedder/spawn.d.ts

@@ -0,0 +1,40 @@
+/** Spec §20 E1.5: the first bridge that needs the embedder spawns it detached; a lock file and the socket bind keep it single. */
+import { spawn } from "node:child_process";
+/**
+ * E1 delta M4: the spawn lock is Task 11b's age-bounded lock (stale only when the holder is dead AND older than 10 s;
+ * stolen by rename, 11b review M1). The id is returned to the taker, so two clients in one process each release only
+ * their own lock and can never strand it.
+ */
+export declare function takeSpawnLock(lockPath: string): string | null;
+export declare function releaseSpawnLock(lockPath: string, id: string): void;
+export declare function permissionFlags(): string[];
+/** E1 delta M1: the embedder inherits only these variables; a bridge's secrets in its environment never reach it. */
+export declare const EMBEDDER_ENV_KEYS: readonly ["HOME", "PATH", "TMPDIR"];
+/**
+ * Windows (Task 11d) has no HOME/TMPDIR: Node's homedir() reads USERPROFILE, the run directory lives under LOCALAPPDATA,
+ * system tools need SystemRoot, and the temp directory is TEMP/TMP. Still an allow-list: no secret passes.
+ */
+export declare const EMBEDDER_ENV_KEYS_WIN32: readonly ["USERPROFILE", "LOCALAPPDATA", "PATH", "SystemRoot", "TEMP", "TMP"];
+export declare function embedderEnv(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): Record<string, string>;
+/**
+ * What the client watches: the child's exit code is the embedder's report of a failed start (11b exit codes), and an
+ * "error" means the child never started at all (for example a missing cwd: ENOENT, reported against the node binary).
+ */
+export interface SpawnHandle {
+    once(ev: "exit", f: (code: number | null) => void): unknown;
+    once(ev: "error", f: (e: NodeJS.ErrnoException) => void): unknown;
+}
+export declare function spawnEmbedder(o: {
+    home: string;
+    key: string;
+    distDir: string;
+    spawnFn?: typeof spawn;
+    onNoPermissionModel?: () => void;
+    /** The run directory (default ~/.securecoms/run/embedder; Windows passes %LOCALAPPDATA%\\SecureComs\\run\\embedder). */
+    runDir?: string;
+    platform?: NodeJS.Platform;
+    /** Test seam for argument-shape tests with a fake spawnFn and fake paths; production always creates it (default true). */
+    createRunDir?: boolean;
+    /** Test seam: the node flags this Node allows (default process.allowedNodeEnvironmentFlags). */
+    nodeFlags?: ReadonlySet<string>;
+}): SpawnHandle;

package/dist/memory/embedder/tokenizer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Semantic memory 7b (spec §6.1): BERT basic tokenizer plus
+ * WordPiece over the pinned vocab.txt. No tokenizer dependency. The golden
+ * fixture (E-1) is the specification: where this file and the reference
+ * encoder disagree, the fixture wins and this file changes.
+ *
+ * The reference is HF `tokenizers` (Rust) driven by the model's tokenizer.json
+ * (BertNormalizer clean_text + handle_chinese_chars + strip_accents + lowercase,
+ * BertPreTokenizer, WordPiece, [CLS] $A [SEP]). Where the Rust behaviour differs
+ * from the Python `transformers` BertTokenizer, the Rust one is followed:
+ *  - Control filter: Cc, Cf, Co (private use) and lone surrogates are removed;
+ *    unassigned code points are kept (they become [UNK]).
+ *  - CJK ranges: the Rust table starts its fifth extension block at U+2B920,
+ *    not U+2B820, so U+2B820..U+2B91F are not split out.
+ *  - Accents are stripped (NFD, drop Mn) BEFORE lower-casing, and lower-casing
+ *    is per code point (no final-sigma context rule).
+ *  - The five BERT special tokens, written literally in the input with exact
+ *    case, are matched before normalization and encode to their own id
+ *    (tokenizer.json added_tokens, normalized: false).
+ */
+export interface TokenizerOptions {
+    lowercase: boolean;
+    stripAccents: boolean;
+    unkToken: string;
+    unknownDropped: boolean;
+    addSpecialTokens: boolean;
+    maxInputCharsPerWord: number;
+}
+export declare class WordPieceTokenizer {
+    private readonly vocab;
+    private readonly o;
+    private readonly added;
+    private constructor();
+    static fromVocab(vocabText: string, opts: TokenizerOptions): WordPieceTokenizer;
+    /** Normalization and pre-tokenization of text that holds no literal special token. */
+    basicTokenize(text: string): string[];
+    private wordPiece;
+    /** Splits out literal special tokens (exact case, leftmost first), as the reference does before normalizing. */
+    private segments;
+    encode(text: string, maxTokens: number): number[];
+}

package/dist/memory/embedder/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Spec §6.2, erratum E1: what the shared embedder process hands its inner inference worker.
+ * The embedder read and verified each file once; the worker gets those very BYTES, never a path,
+ * no store handle and no key. Shared by the inner worker (Task 11a) and the embedder process (Task 11b).
+ */
+import type { TokenizerOptions } from "./tokenizer.js";
+export interface EmbedderWorkerData {
+    bytes: {
+        model: Uint8Array;
+        vocab: Uint8Array;
+        wasm: Uint8Array;
+    };
+    model: {
+        sha256: string;
+        size: number;
+    };
+    vocab: {
+        sha256: string;
+        size: number;
+    };
+    wasm: {
+        sha256: string;
+        size: number;
+    };
+    tokenizer: TokenizerOptions;
+    maxTokens: number;
+    dims: number;
+    pooling: "mean" | "cls";
+    normalize: boolean;
+    inputs: readonly string[];
+    output: string;
+}

package/dist/memory/embedder/windows.d.ts

@@ -0,0 +1,46 @@
+/** Compiled; flipped only by Task 27b's follow-up PR. While false, a win32 bridge reports `unsupported_platform`. */
+export declare const WINDOWS_SEMANTIC_ENABLED = false;
+export declare const windowsSemanticOn: (platform: NodeJS.Platform, enabled?: boolean) => boolean;
+/** %LOCALAPPDATA%\SecureComs\run\embedder; it lives in embedder-paths.ts so the embedder bundle never imports this module. */
+export { windowsRunDir } from "./embedder-paths.js";
+/** icacls /save writes UTF-16LE: line 1 is the path, line 2 the SDDL. */
+export declare function parseSaveSddl(saveFile: Buffer): string;
+/**
+ * P-7 delta M2 and 11d review L1/L2. The SDDL is parsed, not pattern-matched:
+ * - the owner (`O:`), when the save file carries one, must be the user SID, SYSTEM (SY) or Administrators (BA);
+ * - the DACL is anchored on the FIRST `D:`; its flags are letters only; then one or more `(…)` ACEs whose bodies may not
+ *   contain `(` (a conditional ACE such as `(XA;;FA;;;S-1-…;(@User.x))` is rejected outright); after the ACEs only an
+ *   `S:` section or the end may follow (a second `D:` or any trailing text is rejected);
+ * - "A" (allow) must name the user SID, SY or BA; "D" (deny) grants nothing and is accepted; every other type (OA, XA,
+ *   ZA, AU, …), a missing DACL and an empty `D:` are rejected. Inherited entries (the ID flag) get no exemption.
+ */
+export declare function aclAllows(sddl: string, ownerSid: string): boolean;
+/** Any component of the path is a reparse point (Node reports junctions and symlinks as symbolic links). */
+export declare function hasReparsePoint(path: string, lstat?: (p: string) => {
+    isSymbolicLink(): boolean;
+}): boolean;
+type Runner = (cmd: string, args: string[]) => Promise<Buffer | string> | Buffer | string;
+/** P-7 delta M1: the SID from `whoami /user /fo csv /nh`, never the environment; any S-1-… (local, domain, Microsoft account or Entra S-1-12-1-…). */
+export declare function currentUserSid(run?: Runner): Promise<string>;
+export interface AclDeps {
+    run?: Runner;
+    lstat?: (p: string) => {
+        isSymbolicLink(): boolean;
+    };
+    tmp?: string;
+}
+/**
+ * True only when `path` (the run directory, or the token file inside it) has no reparse point on the way and its DACL
+ * allows only this user, SYSTEM and Administrators. P-7 delta H1: icacls' stdout is localized text and is never parsed;
+ * the /save FILE is always read. Any failure is false (fail closed). `sid` is the cached per-process SID (WindowsAcl).
+ */
+export declare function verifyRunDirAcl(path: string, deps?: AclDeps, sid?: () => Promise<string>): Promise<boolean>;
+/** One per process: the current user's SID is read once (a failed read is not cached, so the next check retries). */
+export declare class WindowsAcl {
+    private readonly deps;
+    private sidP;
+    constructor(deps?: AclDeps);
+    sid(): Promise<string>;
+    check(path: string): Promise<boolean>;
+}
+export declare const PROCESS_WINDOWS_ACL: WindowsAcl;