@spinabot/brigade 0.1.1 → 1.0.0

package/dist/storage/encryption.js

@@ -0,0 +1,389 @@
+// src/storage/encryption.ts
+//
+// Brigade at-rest encryption. The operator supplies a 32-byte master key
+// via `BRIGADE_ENCRYPTION_KEY` (hex-encoded, 64 chars). When set, every
+// Convex byte column the storage layer writes goes through this module's
+// `seal` first; reads run through `open`. The Convex backend never sees
+// plaintext.
+//
+// Format (binary, written into Convex `Enc()` byte columns):
+//
+//   [0]      magic byte = 0x42 ('B' for Brigade)
+//   [1]      version = 0x01
+//   [2..14)  12-byte nonce (random per write)
+//   [14..30) 16-byte GCM auth tag
+//   [30..]   ciphertext
+//
+// When the magic byte is absent, the value is treated as plaintext bytes —
+// this preserves the old un-encrypted shape and lets a key be turned on
+// later without a flag day. Reads decrypt sealed values automatically; if
+// the key is missing or wrong, decryption fails closed (throws).
+//
+// Algorithm: AES-256-GCM via Node's built-in `crypto` (no native deps —
+// the design doc referenced libsodium, but native AES-GCM is FIPS-able,
+// well-audited, and ships zero extra bytes).
+//
+// Key rotation: write a new key into BRIGADE_ENCRYPTION_KEY, set the OLD
+// one in BRIGADE_ENCRYPTION_KEY_OLD. Reads try the new key first then the
+// old. Once everything has been re-sealed, drop the OLD env var.
+//
+// Customer-facing surface: a CLI command (`brigade encrypt status`) reports
+// whether the key is set + a sample round-trip. Operators rotate keys with
+// `brigade encrypt rotate --to <new-hex>` (calls re-seal across all
+// sensitive columns; lands as a follow-up).
+import { createCipheriv, createDecipheriv, createHash, hkdfSync, randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { resolveEncryptionKeyFilePath } from "../config/paths.js";
+const MAGIC = 0x42;
+const VERSION = 0x01;
+const HEADER_LEN = 2;
+const NONCE_LEN = 12;
+const TAG_LEN = 16;
+const KEY_ENV_PRIMARY = "BRIGADE_ENCRYPTION_KEY";
+const KEY_ENV_OLD = "BRIGADE_ENCRYPTION_KEY_OLD";
+/** Fixed app salt for HKDF subkey derivation (domain separation, not secret). */
+const HKDF_SALT = Buffer.from("brigade-memory-hkdf-v1", "utf8");
+/** Cache derived subkeys (keyed by masterFingerprint‖context) — HKDF is cheap
+ *  but runs on every seal/open, and origins repeat. Cleared on key-cache reset. */
+const subkeyCache = new Map();
+/**
+ * Derive a per-CONTEXT 32-byte subkey from a master via HKDF-SHA256. The basis
+ * for per-origin crypto-isolation: each origin seals with ITS OWN subkey, so a
+ * cross-origin read needs the right `context` — not just the master. Multi-tenant
+ * ready: when each tenant has its own master/root, swapping the root in here
+ * keeps origins crypto-separated ACROSS tenants for free (a tenant can't derive
+ * another tenant's subkeys without that tenant's root).
+ */
+export function deriveSubkey(master, context) {
+    const fp = createHash("sha256").update(master).digest("hex"); // FULL fingerprint: a 32-bit prefix could collide across many tenant roots (keys the cache only; subkey is fp-independent)
+    const cacheKey = `${fp}|${context}`;
+    const hit = subkeyCache.get(cacheKey);
+    if (hit)
+        return hit;
+    const sub = Buffer.from(hkdfSync("sha256", master, HKDF_SALT, Buffer.from(context, "utf8"), 32));
+    subkeyCache.set(cacheKey, sub);
+    return sub;
+}
+function parseHexKey(name, raw) {
+    if (!raw || raw.trim().length === 0)
+        return undefined;
+    const hex = raw.trim();
+    if (!/^[0-9a-f]{64}$/i.test(hex)) {
+        const detail = hex.length === 64
+            ? `Got 64 chars but it contains non-hex characters.`
+            : `Got ${hex.length} chars.`;
+        throw new Error(`${name} must be a 64-char hex string (32 bytes). ${detail} ` +
+            `Generate one with: node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"`);
+    }
+    return Buffer.from(hex, "hex");
+}
+let cachedPrimary;
+let cachedOld;
+let cachedSource = "none";
+let cacheStamp = "";
+// File-key cache: `undefined` = not checked yet; `null` = checked, absent.
+// seal/open run on every convex write, so the key file is read once per
+// process (and re-primed by saveEncryptionKeyToFile / the test reset) —
+// never per call. Mid-process file changes go through env rotation instead.
+let cachedFileKey;
+function readKeyFileOnce() {
+    if (cachedFileKey !== undefined)
+        return cachedFileKey ?? undefined;
+    try {
+        const raw = fs.readFileSync(resolveEncryptionKeyFilePath(), "utf8").trim();
+        cachedFileKey = parseHexKey("encryption key file", raw) ?? null;
+    }
+    catch {
+        cachedFileKey = null;
+    }
+    return cachedFileKey ?? undefined;
+}
+function getKeys() {
+    // Re-resolve when the env-side inputs might have changed (cheap; env reads
+    // are fast). Tests + the rotate CLI need this so they don't have to
+    // restart the process. The key FILE rides its own once-per-process cache.
+    const stamp = (process.env[KEY_ENV_PRIMARY] ?? "") +
+        "|" +
+        (process.env[KEY_ENV_OLD] ?? "") +
+        "|" +
+        (process.env.BRIGADE_ENCRYPTION_KEY_FILE ?? "");
+    if (stamp !== cacheStamp) {
+        cachedPrimary = parseHexKey(KEY_ENV_PRIMARY, process.env[KEY_ENV_PRIMARY]);
+        cachedOld = parseHexKey(KEY_ENV_OLD, process.env[KEY_ENV_OLD]);
+        // A changed key-file override invalidates the file cache too.
+        cachedFileKey = undefined;
+        cachedSource = cachedPrimary !== undefined ? "env" : "none";
+        cacheStamp = stamp;
+    }
+    let primary = cachedPrimary;
+    if (primary === undefined) {
+        // Env var always wins; the auto-generated key file is the fallback so
+        // onboarding can persist a key without asking the operator to manage
+        // shell profiles. See resolveEncryptionKeyFilePath for why the file
+        // lives OUTSIDE ~/.brigade.
+        primary = readKeyFileOnce();
+        cachedSource = primary !== undefined ? "file" : "none";
+    }
+    else {
+        cachedSource = "env";
+    }
+    return {
+        ...(primary !== undefined ? { primary } : {}),
+        ...(cachedOld !== undefined ? { old: cachedOld } : {}),
+    };
+}
+/** Is at-rest encryption configured? */
+export function isEncryptionEnabled() {
+    return getKeys().primary !== undefined;
+}
+/** Where the active key came from: the env var, the key file, or nowhere. */
+export function encryptionKeySource() {
+    getKeys();
+    return cachedSource;
+}
+/**
+ * Persist a key to the key file (0600). REFUSES to overwrite an existing
+ * key file — overwriting would orphan every row sealed with the old key.
+ * Pass `backupExisting: true` to rename the current file to
+ * `encryption.key.bak-<stamp>` first (start-fresh flow) — the old key is
+ * never destroyed, only set aside.
+ */
+export function saveEncryptionKeyToFile(hex, opts = {}) {
+    const parsed = parseHexKey("encryption key", hex);
+    if (!parsed)
+        throw new Error("saveEncryptionKeyToFile: key must be 64 hex chars");
+    const filePath = resolveEncryptionKeyFilePath();
+    let backedUpTo;
+    if (fs.existsSync(filePath)) {
+        if (!opts.backupExisting) {
+            throw new Error(`an encryption key already exists — refusing to overwrite it. ` +
+                `(Overwriting would make data sealed with the current key unreadable.)`);
+        }
+        const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+        backedUpTo = `${filePath}.bak-${stamp}`;
+        fs.renameSync(filePath, backedUpTo);
+    }
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, `${hex.trim()}\n`, { encoding: "utf8", mode: 0o600 });
+    if (process.platform !== "win32") {
+        try {
+            fs.chmodSync(filePath, 0o600);
+        }
+        catch {
+            /* FAT32 etc. */
+        }
+    }
+    // Prime the in-process cache so the key is live immediately.
+    cachedFileKey = parsed;
+    return { path: filePath, ...(backedUpTo !== undefined ? { backedUpTo } : {}) };
+}
+/**
+ * Set the key file aside as `encryption.key.bak-<stamp>` (factory reset:
+ * the data the key sealed is gone, so the next onboard mints a fresh key).
+ * The old key is NEVER deleted — an old backup of the erased data may still
+ * need it. No-op when no key file exists.
+ */
+export function retireEncryptionKeyFile() {
+    const filePath = resolveEncryptionKeyFilePath();
+    if (!fs.existsSync(filePath))
+        return {};
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const backedUpTo = `${filePath}.bak-${stamp}`;
+    fs.renameSync(filePath, backedUpTo);
+    cachedFileKey = undefined; // re-read (now absent) on next getKeys
+    return { backedUpTo };
+}
+/** True when a key file exists at the resolved path. */
+export function encryptionKeyFileExists() {
+    try {
+        return fs.existsSync(resolveEncryptionKeyFilePath());
+    }
+    catch {
+        return false;
+    }
+}
+/** Test-only: drop the in-process key caches so env/file changes re-read. */
+export function __resetEncryptionKeyCacheForTests() {
+    cachedPrimary = undefined;
+    cachedOld = undefined;
+    cachedFileKey = undefined;
+    cachedSource = "none";
+    cacheStamp = "";
+    subkeyCache.clear();
+}
+/** Encrypt arbitrary bytes. When no key is configured, returns the bytes
+ *  unchanged (so existing data and freshly-onboarded operators without a
+ *  key continue to work). */
+export function seal(plaintext, aad, keyContext) {
+    const master = getKeys().primary;
+    const buf = toBuffer(plaintext);
+    if (!master) {
+        // Return the raw plaintext (no magic header) — `open` will see no
+        // magic byte and pass through.
+        return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+    }
+    // Per-origin (or per-tenant) crypto-isolation: seal with the context subkey.
+    const key = keyContext ? deriveSubkey(master, keyContext) : master;
+    const nonce = randomBytes(NONCE_LEN);
+    const cipher = createCipheriv("aes-256-gcm", key, nonce);
+    if (aad)
+        cipher.setAAD(Buffer.from(aad, "utf8"));
+    const ct = Buffer.concat([cipher.update(buf), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const out = Buffer.alloc(HEADER_LEN + NONCE_LEN + TAG_LEN + ct.length);
+    out[0] = MAGIC;
+    out[1] = VERSION;
+    nonce.copy(out, HEADER_LEN);
+    tag.copy(out, HEADER_LEN + NONCE_LEN);
+    ct.copy(out, HEADER_LEN + NONCE_LEN + TAG_LEN);
+    return out.buffer.slice(out.byteOffset, out.byteOffset + out.byteLength);
+}
+/** Decrypt bytes if they carry the magic prefix; otherwise return as-is. */
+export function open(payload, aad, keyContext) {
+    if (!payload)
+        return Buffer.alloc(0);
+    const buf = toBuffer(payload);
+    if (buf.length < HEADER_LEN + NONCE_LEN + TAG_LEN || buf[0] !== MAGIC || buf[1] !== VERSION) {
+        // Not a sealed payload — treat as plaintext bytes. Gate on magic AND version
+        // AND a full minimum envelope: plaintext that merely STARTS with 0x42 ('B',
+        // e.g. "Brigade…") must pass through unchanged, not be misread as a short or
+        // wrong-version sealed blob and throw into the read path. This is the no-key
+        // passthrough contract — turning a key on later must never have corrupted a
+        // pre-existing plaintext value that happened to begin with 'B'.
+        return buf;
+    }
+    const { primary, old: oldKey } = getKeys();
+    if (!primary) {
+        throw new Error(`brigade encryption: sealed payload received but ${KEY_ENV_PRIMARY} is not set. ` +
+            "Set the matching key to read this row, or rotate via `brigade encrypt rotate`.");
+    }
+    const nonce = buf.subarray(HEADER_LEN, HEADER_LEN + NONCE_LEN);
+    const tag = buf.subarray(HEADER_LEN + NONCE_LEN, HEADER_LEN + NONCE_LEN + TAG_LEN);
+    const ct = buf.subarray(HEADER_LEN + NONCE_LEN + TAG_LEN);
+    const tryDecrypt = (key) => {
+        try {
+            const dec = createDecipheriv("aes-256-gcm", key, nonce);
+            if (aad)
+                dec.setAAD(Buffer.from(aad, "utf8"));
+            dec.setAuthTag(tag);
+            return Buffer.concat([dec.update(ct), dec.final()]);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    // Candidate keys, in order. The context SUBKEY first (current per-origin
+    // seals), then the RAW master (legacy rows sealed before HKDF was added —
+    // organic migration: they re-seal with the subkey on their next write), then
+    // the same pair for the rotated-out OLD key. A row sealed for origin A can't
+    // be opened with origin B's context (its subkey won't decrypt + the master
+    // won't either, since A used a subkey) — cross-origin isolation.
+    const candidates = [];
+    if (keyContext)
+        candidates.push(deriveSubkey(primary, keyContext));
+    candidates.push(primary);
+    if (oldKey) {
+        if (keyContext)
+            candidates.push(deriveSubkey(oldKey, keyContext));
+        candidates.push(oldKey);
+    }
+    for (const key of candidates) {
+        const r = tryDecrypt(key);
+        if (r !== undefined)
+            return r;
+    }
+    throw new Error(`brigade encryption: failed to decrypt sealed payload — wrong key or corrupted data`);
+}
+// =============================================================================
+// Convenience helpers
+// =============================================================================
+/** Encrypt a UTF-8 string. Returns the sealed ArrayBuffer ready to send
+ *  into a Convex `v.bytes()` column. */
+export function sealString(text, aad, keyContext) {
+    return seal(Buffer.from(text, "utf8"), aad, keyContext);
+}
+/** Decrypt a sealed-or-plain ArrayBuffer back into a UTF-8 string. */
+export function openToString(payload, aad, keyContext) {
+    if (!payload)
+        return "";
+    return open(payload, aad, keyContext).toString("utf8");
+}
+/** Encrypt a JSON-serialisable value. */
+export function sealJson(value) {
+    return seal(Buffer.from(JSON.stringify(value ?? null), "utf8"));
+}
+/** Decrypt a sealed JSON payload. Returns `undefined` when the input is
+ *  empty / undecodable. */
+export function openJson(payload) {
+    if (!payload)
+        return undefined;
+    const text = open(payload).toString("utf8");
+    if (text.length === 0)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+// =============================================================================
+// Internals
+// =============================================================================
+function toBuffer(value) {
+    if (typeof value === "string")
+        return Buffer.from(value, "utf8");
+    if (Buffer.isBuffer(value))
+        return value;
+    if (value instanceof ArrayBuffer)
+        return Buffer.from(value);
+    return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+}
+/** Generate a fresh master key as 64-char hex. Used by `brigade encrypt init`. */
+export function generateMasterKeyHex() {
+    return randomBytes(32).toString("hex");
+}
+/** Self-check: confirms the key is parseable AND a round-trip works. */
+export function encryptionStatus() {
+    const keys = getKeys();
+    const source = encryptionKeySource();
+    if (!keys.primary) {
+        return { enabled: false, hasOldKey: keys.old !== undefined, algorithm: null, source };
+    }
+    try {
+        const sample = "brigade-encryption-self-check";
+        const sealed = sealString(sample);
+        const opened = openToString(sealed);
+        if (opened !== sample) {
+            return {
+                enabled: true,
+                hasOldKey: keys.old !== undefined,
+                algorithm: "aes-256-gcm",
+                source,
+                error: "round-trip mismatch",
+            };
+        }
+        // First 8 hex chars of a sha256 of the key — gives operators a
+        // short, non-revealing fingerprint to confirm two installs share
+        // the same key.
+        const fp = createHash("sha256").update(keys.primary).digest("hex").slice(0, 8);
+        return {
+            enabled: true,
+            hasOldKey: keys.old !== undefined,
+            algorithm: "aes-256-gcm",
+            source,
+            primaryKeyFingerprint: fp,
+        };
+    }
+    catch (err) {
+        return {
+            enabled: true,
+            hasOldKey: keys.old !== undefined,
+            algorithm: "aes-256-gcm",
+            source,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+//# sourceMappingURL=encryption.js.map

package/dist/storage/encryption.js.map

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

package/dist/storage/factory-reset.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Remove the entire local Brigade state dir (`~/.brigade` by default) so the
+ * next onboard/boot re-seeds defaults. Idempotent (`force` — a missing dir is
+ * fine). Returns the path that was cleared.
+ */
+export declare function wipeLocalBrigadeState(stateDir?: string): string;
+//# sourceMappingURL=factory-reset.d.ts.map

package/dist/storage/factory-reset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory-reset.d.ts","sourceRoot":"","sources":["../../src/storage/factory-reset.ts"],"names":[],"mappings":"AA2BA;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,GAAE,MAA0B,GAAG,MAAM,CAGlF"}

package/dist/storage/factory-reset.js

@@ -0,0 +1,34 @@
+// src/storage/factory-reset.ts
+//
+// Factory-reset the LOCAL Brigade state so a re-onboard lands VIRGIN — byte-for-
+// byte the same starting point as a first-ever onboard, with NO carryover of the
+// previous install's workspace personas, skills, sessions, or memory facts.
+//
+// Why this exists: the "clean slate" paths used to clear only the Convex backend.
+// The local ~/.brigade tree (workspace, skills, sessions, facts.jsonl, the
+// workspace-setup stamp) always survived and was re-mirrored / re-read on the
+// next boot, so "Start fresh" was NOT a fresh start. This wipes it.
+//
+// What is intentionally NOT touched:
+//   • The encryption key — it lives OUTSIDE the state dir (OS config dir) and is
+//     retired-to-`.bak` separately, never destroyed, so an OLD backup of the
+//     erased data stays readable.
+//   • The Convex backend — the caller erases that explicitly (it's a different
+//     store); this helper only clears the LOCAL side.
+//
+// Caller contract: the gateway MUST be stopped first (open file handles +
+// write-behind chains would otherwise race a directory removal), and the mode
+// sentinel must be re-pinned afterward if the chosen mode should persist (the
+// onboard wizard pins it after this runs; `store reset` deletes it on purpose).
+import * as fs from "node:fs";
+import { resolveStateDir } from "../config/paths.js";
+/**
+ * Remove the entire local Brigade state dir (`~/.brigade` by default) so the
+ * next onboard/boot re-seeds defaults. Idempotent (`force` — a missing dir is
+ * fine). Returns the path that was cleared.
+ */
+export function wipeLocalBrigadeState(stateDir = resolveStateDir()) {
+    fs.rmSync(stateDir, { recursive: true, force: true });
+    return stateDir;
+}
+//# sourceMappingURL=factory-reset.js.map

package/dist/storage/factory-reset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory-reset.js","sourceRoot":"","sources":["../../src/storage/factory-reset.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,EAAE;AACF,iFAAiF;AACjF,iFAAiF;AACjF,4EAA4E;AAC5E,EAAE;AACF,kFAAkF;AAClF,2EAA2E;AAC3E,8EAA8E;AAC9E,oEAAoE;AACpE,EAAE;AACF,qCAAqC;AACrC,iFAAiF;AACjF,6EAA6E;AAC7E,kCAAkC;AAClC,+EAA+E;AAC/E,sDAAsD;AACtD,EAAE;AACF,0EAA0E;AAC1E,8EAA8E;AAC9E,8EAA8E;AAC9E,gFAAgF;AAEhF,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAE9B,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,WAAmB,eAAe,EAAE;IACzE,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,OAAO,QAAQ,CAAC;AACjB,CAAC"}

package/dist/storage/facts-cache.d.ts

@@ -0,0 +1,24 @@
+import type { MemoryRecord } from "../agents/memory/records.js";
+import type { BrigadeStore } from "./store.js";
+export declare function factsFlushErrorCount(workspaceId: string): number;
+/** Canonical, case-STABLE workspace key. The convex cache is shared between the BOOT
+ *  hydration (keyed off the config agent id) and the runtime FactStore (keyed off the
+ *  on-disk path, which `resolveAgentWorkspaceDir` LOWERCASES). If the two disagree on
+ *  case, every convex read misses the boot-primed cache → silent memory amnesia. So
+ *  BOTH sides funnel the key through this one lowercasing rule. */
+export declare function canonicalWorkspaceId(id: string): string;
+/** "main" for the top-level workspace; the canonicalised agent id for
+ *  `agents/<id>/workspace`-shaped dirs. NOTE: a `cfg.agents.<id>.workspace` OVERRIDE
+ *  pointing outside that shape can't be id-resolved from the path alone and collapses
+ *  to "main" — passing the canonical agent id explicitly is the full fix (future). */
+export declare function workspaceIdFromDir(workspaceDir: string): string;
+export declare function primeFactsCache(workspaceId: string, records: MemoryRecord[]): void;
+export declare function getCachedFacts(workspaceId: string): MemoryRecord[] | undefined;
+/** Diff `next` against the cached records by memoryId, prime, and enqueue
+ *  the authoritative row mutations. */
+export declare function writeThroughFactsCache(store: BrigadeStore, workspaceId: string, next: MemoryRecord[]): void;
+/** Resolves when every facts mutation enqueued so far reached the backend. */
+export declare function awaitFactsFlush(): Promise<void>;
+/** Test-only. */
+export declare function __resetFactsCacheForTests(): void;
+//# sourceMappingURL=facts-cache.d.ts.map

package/dist/storage/facts-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facts-cache.d.ts","sourceRoot":"","sources":["../../src/storage/facts-cache.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAU/C,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;mEAImE;AACnE,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;sFAGsF;AACtF,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAQ/D;AAED,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,IAAI,CAElF;AAED,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY,EAAE,GAAG,SAAS,CAE9E;AAED;uCACuC;AACvC,wBAAgB,sBAAsB,CACrC,KAAK,EAAE,YAAY,EACnB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,YAAY,EAAE,GAClB,IAAI,CA2CN;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED,iBAAiB;AACjB,wBAAgB,yBAAyB,IAAI,IAAI,CAIhD"}

package/dist/storage/facts-cache.js

@@ -0,0 +1,110 @@
+// src/storage/facts-cache.ts
+//
+// Convex-mode in-process cache for memory facts (facts.jsonl equivalent),
+// keyed per workspace. FactStore's two IO choke points (readAll + the
+// private whole-file writeAll) dispatch here in convex mode: reads serve
+// the cache, writes prime it and enqueue the per-record mutations realising
+// the diff (authoritative upserts + deletes by memoryId).
+//
+// Workspace identity: "main" for the shared top-level workspace, the agent
+// id for per-agent workspaces — derived from the workspaceDir path shape
+// (`~/.brigade/agents/<id>/workspace` vs anything else).
+//
+// Filesystem mode never touches this module.
+import path from "node:path";
+const _byWorkspace = new Map();
+let _flushChain = Promise.resolve();
+/** PER-WORKSPACE count of facts-flush batches that FAILED (after retries). A caller that
+ *  needs the write durable before acting (the extraction cursor) snapshots ITS workspace's
+ *  count, awaits the flush, and checks for an increase — so it never advances past facts
+ *  that didn't reach the backend. Keyed per workspace so one agent's failing flush can't
+ *  falsely stall a DIFFERENT, healthy agent's cursor (the chain is shared; the blame is not). */
+const _flushErrorCount = new Map();
+export function factsFlushErrorCount(workspaceId) {
+    return _flushErrorCount.get(workspaceId) ?? 0;
+}
+/** Canonical, case-STABLE workspace key. The convex cache is shared between the BOOT
+ *  hydration (keyed off the config agent id) and the runtime FactStore (keyed off the
+ *  on-disk path, which `resolveAgentWorkspaceDir` LOWERCASES). If the two disagree on
+ *  case, every convex read misses the boot-primed cache → silent memory amnesia. So
+ *  BOTH sides funnel the key through this one lowercasing rule. */
+export function canonicalWorkspaceId(id) {
+    return id.trim().toLowerCase();
+}
+/** "main" for the top-level workspace; the canonicalised agent id for
+ *  `agents/<id>/workspace`-shaped dirs. NOTE: a `cfg.agents.<id>.workspace` OVERRIDE
+ *  pointing outside that shape can't be id-resolved from the path alone and collapses
+ *  to "main" — passing the canonical agent id explicitly is the full fix (future). */
+export function workspaceIdFromDir(workspaceDir) {
+    const parts = path.resolve(workspaceDir).split(path.sep);
+    const i = parts.lastIndexOf("agents");
+    if (i >= 0 && i + 2 < parts.length && parts[i + 2] === "workspace") {
+        const id = parts[i + 1];
+        if (id && id.trim().length > 0)
+            return canonicalWorkspaceId(id);
+    }
+    return "main";
+}
+export function primeFactsCache(workspaceId, records) {
+    _byWorkspace.set(workspaceId, structuredClone(records));
+}
+export function getCachedFacts(workspaceId) {
+    return _byWorkspace.get(workspaceId);
+}
+/** Diff `next` against the cached records by memoryId, prime, and enqueue
+ *  the authoritative row mutations. */
+export function writeThroughFactsCache(store, workspaceId, next) {
+    const prev = _byWorkspace.get(workspaceId) ?? [];
+    primeFactsCache(workspaceId, next);
+    const prevById = new Map(prev.map((r) => [r.memoryId, r]));
+    const nextById = new Map(next.map((r) => [r.memoryId, r]));
+    const ops = [];
+    for (const [id, rec] of nextById) {
+        const old = prevById.get(id);
+        if (old && JSON.stringify(old) === JSON.stringify(rec))
+            continue;
+        const frozen = structuredClone(rec);
+        ops.push(() => store.memory.upsertFactRecordRaw(workspaceId, frozen));
+    }
+    for (const id of prevById.keys()) {
+        if (!nextById.has(id))
+            ops.push(() => store.memory.deleteFactRecordRaw(workspaceId, id));
+    }
+    if (ops.length === 0)
+        return;
+    _flushChain = _flushChain
+        .then(async () => {
+        for (const op of ops) {
+            let lastErr;
+            // Bounded retry — a transient convex blip (network, backend restart, rate
+            // limit) must not silently DROP a durable fact. 3 attempts, then give up.
+            for (let attempt = 0; attempt < 3; attempt++) {
+                try {
+                    await op();
+                    lastErr = undefined;
+                    break;
+                }
+                catch (e) {
+                    lastErr = e;
+                }
+            }
+            if (lastErr)
+                throw lastErr;
+        }
+    })
+        .catch((err) => {
+        _flushErrorCount.set(workspaceId, (_flushErrorCount.get(workspaceId) ?? 0) + 1);
+        console.error(`brigade: memory facts write to convex failed (workspace ${workspaceId}) — ${err.message}`);
+    });
+}
+/** Resolves when every facts mutation enqueued so far reached the backend. */
+export function awaitFactsFlush() {
+    return _flushChain;
+}
+/** Test-only. */
+export function __resetFactsCacheForTests() {
+    _byWorkspace.clear();
+    _flushChain = Promise.resolve();
+    _flushErrorCount.clear();
+}
+//# sourceMappingURL=facts-cache.js.map

package/dist/storage/facts-cache.js.map

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

package/dist/storage/flush.d.ts

@@ -0,0 +1,4 @@
+/** Await every storage write-behind chain. Safe in both modes; no-op when no
+ *  writes are pending. Call before `process.exit()` in any mutating CLI path. */
+export declare function flushAllPendingWrites(): Promise<void>;
+//# sourceMappingURL=flush.d.ts.map

package/dist/storage/flush.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flush.d.ts","sourceRoot":"","sources":["../../src/storage/flush.ts"],"names":[],"mappings":"AAmBA;iFACiF;AACjF,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAmG3D"}