@seanhogg/builderforce-memory 2026.9.34 → 2026.10.2

package/dist/storage/types.js

@@ -0,0 +1,90 @@
+/**
+ * storage/types.ts – Narrow storage/transaction ports for durable memory.
+ *
+ * This module is the seam the offline-memory scope (M01–M05) requires:
+ *   - MemoryStore no longer owns IndexedDB directly; it speaks to a
+ *     {@link FactStoragePort} with REAL transaction semantics (a write resolves
+ *     only after the transaction commits, and rejects on abort — M02).
+ *   - Facts carry explicit scope partitions (account/tenant/project/repository/
+ *     chat — or the explicit unbound scope for personal, never-connected
+ *     memory), durable revisions, operation identity and provenance (M03/M04).
+ *   - Deletes write tombstones, and every mutation appends to a sync journal in
+ *     the SAME transaction as the fact change, so a crash can never acknowledge
+ *     a fact whose journal entry was lost (M02/M04).
+ *
+ * Two durable adapters implement the port:
+ *   - `IdbStorageAdapter`       (browser / VSIX webview — IndexedDB)
+ *   - `NodeFileStorageAdapter`  (VSIX extension host / MCP — atomic JSON file)
+ * An in-memory IndexedDB shim (fake-indexeddb) is a TEST double, never a
+ * durability claim.
+ */
+import { SSMError } from '../errors/SSMError.js';
+/** The explicit "no account, never connected" partition — NOT the absence of a scope. */
+export const UNBOUND_SCOPE = Object.freeze({});
+const SCOPE_FIELDS = ['account', 'tenant', 'project', 'repository', 'chat'];
+/**
+ * Canonical partition string for a scope. The unbound scope partitions to the
+ * empty string, so legacy records (written before scopes existed) land in the
+ * unbound partition and stay readable. Two scopes that differ in any field are
+ * different partitions — callers can never widen a recall by omitting a field
+ * unless they genuinely target the unbound partition.
+ */
+export function scopePartitionKey(scope) {
+    if (!scope)
+        return '';
+    const parts = [];
+    for (const f of SCOPE_FIELDS) {
+        const v = scope[f];
+        if (v != null && v !== '')
+            parts.push(`${f}=${encodeURIComponent(v)}`);
+    }
+    return parts.join('|');
+}
+/**
+ * Physical record id for a (scope, key) pair. Unbound-scope ids are the bare
+ * key — byte-identical to pre-scope records, so existing databases migrate
+ * without rewriting keys.
+ */
+export function scopedRecordId(scope, key) {
+    const partition = scopePartitionKey(scope);
+    return partition === '' ? key : `${partition}::${key}`;
+}
+/**
+ * Secondary index on {@link StoredFactRecord.key}. Key lookup uses this (or the
+ * primary key) — never a full scan — when the adapter has built it.
+ */
+export const FACT_KEY_INDEX = 'byKey';
+/**
+ * Secondary multi-entry index on {@link StoredFactRecord.tags}. Tag lookup uses
+ * this when present and falls back to a scan only when the index is missing.
+ */
+export const FACT_TAG_INDEX = 'byTag';
+/**
+ * The public {@link SSMError} code for each storage code. Callers that predate
+ * the storage layer branch on `code === 'MEMORY_UNAVAILABLE'` (what MemoryStore
+ * always rejected with when IndexedDB was missing or faulted), so unavailable
+ * and aborted storage keep that code; a CAS conflict is the new `MEMORY_CONFLICT`.
+ */
+const PUBLIC_CODE = {
+    STORAGE_UNAVAILABLE: 'MEMORY_UNAVAILABLE',
+    STORAGE_ABORTED: 'MEMORY_UNAVAILABLE',
+    STORAGE_CONFLICT: 'MEMORY_CONFLICT',
+};
+/**
+ * A storage-layer failure. It IS an {@link SSMError} whose `code` is the public
+ * contract (`MEMORY_UNAVAILABLE` / `MEMORY_CONFLICT`); `storageCode` keeps the
+ * detailed storage code for callers that need it.
+ */
+export class MemoryStorageError extends SSMError {
+    storageCode;
+    constructor(storageCode, message, cause) {
+        super(PUBLIC_CODE[storageCode], message, cause);
+        this.storageCode = storageCode;
+        this.name = 'MemoryStorageError';
+    }
+}
+/** Type guard for conflict errors so callers can reconcile instead of blindly retrying. */
+export function isStorageConflict(err) {
+    return err instanceof MemoryStorageError && err.storageCode === 'STORAGE_CONFLICT';
+}
+//# sourceMappingURL=types.js.map

package/dist/storage/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,QAAQ,EAAqB,MAAM,uBAAuB,CAAC;AAWpE,yFAAyF;AACzF,MAAM,CAAC,MAAM,aAAa,GAAgB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAE5D,MAAM,YAAY,GAAG,CAAC,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,CAAU,CAAC;AAErF;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAA8B;IAC5D,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,YAAY,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACnB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAA8B,EAAE,GAAW;IACtE,MAAM,SAAS,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAC3C,OAAO,SAAS,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,KAAK,GAAG,EAAE,CAAC;AAC3D,CAAC;AAcD;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAEtC;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAiJtC;;;;;GAKG;AACH,MAAM,WAAW,GAA2C;IACxD,mBAAmB,EAAE,oBAAoB;IACzC,eAAe,EAAM,oBAAoB;IACzC,gBAAgB,EAAK,iBAAiB;CACzC,CAAC;AAEF;;;;GAIG;AACH,MAAM,OAAO,kBAAmB,SAAQ,QAAQ;IACnC,WAAW,CAAmB;IAEvC,YAAY,WAA6B,EAAE,OAAe,EAAE,KAAe;QACvE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;QAChD,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACrC,CAAC;CACJ;AAED,2FAA2F;AAC3F,MAAM,UAAU,iBAAiB,CAAC,GAAY;IAC1C,OAAO,GAAG,YAAY,kBAAkB,IAAI,GAAG,CAAC,WAAW,KAAK,kBAAkB,CAAC;AACvF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanhogg/builderforce-memory",
-  "version": "2026.9.34",
+  "version": "2026.10.2",
   "description": "BuilderForce Agent Memory — runtime layer. SSM execution, Transformer orchestration, online distillation, enterprise RAG (ingestion pipelines, vector-store adapters, tenant/ACL-scoped hybrid retrieval), multi-agent graph orchestration, LLM telemetry and cost accounting, and persistent agent memory for BuilderForce.ai agents.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -99,7 +99,7 @@
   },
   "homepage": "https://github.com/SeanHogg/builderforce-memory/tree/main/packages/memory#readme",
   "peerDependencies": {
-    "@seanhogg/builderforce-memory-engine": "^2026.9.34"
+    "@seanhogg/builderforce-memory-engine": "^2026.10.2"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
@@ -113,7 +113,7 @@
     "ts-jest": "^29.2.0",
     "typescript": "^6.0.3",
     "@typescript/native-preview": "7.0.0-dev.20260627.2",
-    "@seanhogg/builderforce-memory-engine": "2026.9.34"
+    "@seanhogg/builderforce-memory-engine": "2026.10.2"
   },
   "jest": {
     "preset": "ts-jest/presets/default-esm",

package/src/errors/SSMError.ts

@@ -11,6 +11,7 @@ export type SSMErrorCode =
     | 'BRIDGE_REQUEST_FAILED'    // fetch to transformer API returned non-OK
     | 'BRIDGE_RESPONSE_INVALID'  // unexpected shape in transformer API response
     | 'MEMORY_UNAVAILABLE'       // IndexedDB unavailable or operation called without a MemoryStore
+    | 'MEMORY_CONFLICT'          // compare-and-set memory write found a newer revision
     | 'DISTILL_FAILED'           // distillation pipeline threw an unexpected error
     | 'UNKNOWN';                 // unexpected error (original in .cause)
 

package/src/handoff/handoff.test.ts

@@ -29,12 +29,22 @@ function expectWithinBudget(pack: HandoffPack, budget = 80): void {
   expect(pack.estimatedTokens).toBeLessThanOrEqual(budget);
 }
 
+/** The note (right after the leading system message); its role must alternate with what follows. */
 function noteOf(pack: HandoffPack): string {
   const note = pack.messages[1]!;
-  expect(note.role).toBe('assistant');
+  const next = pack.messages[2];
+  expect(note.role).toBe(next === undefined || next.role === 'assistant' ? 'user' : 'assistant');
   return note.content as string;
 }
 
+/** No two consecutive user turns and no two consecutive assistant turns. */
+function expectAlternating(messages: readonly HandoffMessage[]): void {
+  for (let i = 1; i < messages.length; i++) {
+    const [a, b] = [messages[i - 1]!.role, messages[i]!.role];
+    if (a === 'user' || a === 'assistant') expect(b).not.toBe(a);
+  }
+}
+
 describe('handoffBudget', () => {
   it('subtracts the reply reserve and tool schemas, never below zero', () => {
     expect(handoffBudget({ targetContextTokens: 8192, reserveOutputTokens: 1024, toolsTokens: 500 })).toBe(6668);
@@ -70,7 +80,8 @@ describe('packHandoff', () => {
     expect(seen[0]!.some((m) => m.role === 'system')).toBe(false);
     // The tail is verbatim and ends on the last message.
     expect(pack.messages[pack.messages.length - 1]!.content).toBe(msg('assistant', 'a4').content);
-    expect(pack.messages.filter((m) => m.role === 'assistant' && m.content === 'the earlier work, summarized')).toHaveLength(1);
+    expect(pack.messages.filter((m) => m.content === 'the earlier work, summarized')).toHaveLength(1);
+    expectAlternating(pack.messages);
   });
 
   it('cuts an oversized summary to the room left instead of overflowing', async () => {
@@ -171,6 +182,45 @@ describe('packHandoff', () => {
     expect(pack.messages.filter((m) => m.role === 'system')).toHaveLength(2);
   });
 
+  it('keeps only LEADING system messages as the prefix; a mid-conversation one stays in place', async () => {
+    const mid = msg('system', 'mid policy');
+    // u1 a1 u2 a2 [mid] u3 a3 u4 a4 — the tail reaches back past `mid` at a large budget.
+    const messages = [...chat().slice(0, 5), mid, ...chat().slice(5)];
+    const wide = await packHandoff({ messages, targetContextTokens: 115, reserveOutputTokens: 0 });
+    expectWithinBudget(wide, 115);
+    expect(wide.messages[0]).toBe(SYSTEM);
+    expect(wide.messages[1]!.role).not.toBe('system');
+    const at = wide.messages.indexOf(mid);
+    expect(at).toBeGreaterThan(1);
+    expect(wide.messages[at + 1]!.content).toBe(msg('user', 'u3').content);
+
+    // At a small budget `mid` falls in the dropped middle: dropped, not hoisted.
+    const seen: HandoffMessage[][] = [];
+    const tight = await packHandoff({ messages, ...BUDGET, summarize: async (d) => { seen.push([...d]); return 'S'; } });
+    expectWithinBudget(tight);
+    expect(tight.messages.includes(mid)).toBe(false);
+    expect(tight.messages.filter((m) => m.role === 'system')).toEqual([SYSTEM]);
+    expect(seen[0]).toContain(mid);
+  });
+
+  it('makes the note a user turn when the verbatim tail starts with an assistant turn', async () => {
+    // Budget 80: the tail is a3 u4 a4, so an assistant note would sit next to a3.
+    const pack = await packHandoff({ messages: chat(), ...BUDGET, summarize: async () => 'S' });
+    expectWithinBudget(pack);
+    expect(pack.messages[2]!.role).toBe('assistant');
+    expect(pack.messages[1]).toEqual({ role: 'user', content: 'S' });
+    expectAlternating(pack.messages);
+  });
+
+  it('keeps the note an assistant turn when the re-injected directive follows it', async () => {
+    const directive = msg('user', 'fix the bug');
+    const messages: HandoffMessage[] = [SYSTEM, msg('user', 'old task'), msg('assistant', 'ok'), directive];
+    for (let i = 0; i < 10; i++) messages.push(msg('assistant', `step${i}`));
+    const pack = await packHandoff({ messages, ...BUDGET });
+    expect(pack.messages[1]!.role).toBe('assistant');
+    expect(pack.messages[2]).toBe(directive);
+  });
+
   it('prefixes the note with a hand-off line only when from and to differ', async () => {
     const handed = await packHandoff({ messages: chat(), ...BUDGET, from: 'cloud/claude', to: 'local/qwen', summarize: async () => 'S' });
     expectWithinBudget(handed);

package/src/handoff/index.ts

@@ -2,11 +2,11 @@
  * Model hand-off packing — the `@seanhogg/builderforce-memory/handoff` subpath (PRD 34 §3.3).
  *
  * When a conversation moves to another model (a local one with a small window, say),
- * {@link packHandoff} fits the transcript into that model's budget: the system message(s)
- * stay, the latest user directive stays verbatim, tool calls are never split from their
- * results, the verbatim tail takes what the budget allows, and the dropped middle becomes
- * ONE assistant note (summary → memory recall → elision marker, with a one-line hand-off
- * note when the models differ).
+ * {@link packHandoff} fits the transcript into that model's budget: the leading system
+ * message(s) stay first, the latest user directive stays verbatim, tool calls are never
+ * split from their results, the verbatim tail takes what the budget allows, and the
+ * dropped middle becomes ONE note (summary → memory recall → elision marker, with a
+ * one-line hand-off note when the models differ) whose role keeps turns alternating.
  *
  * Pure: no WebGPU, no IndexedDB, no `node:*` — runs in a Cloudflare Worker, a browser
  * page and Node alike.

package/src/handoff/note.ts

@@ -1,5 +1,5 @@
 /**
- * The ONE assistant note that stands in for the dropped middle of a handed-off
+ * The ONE note that stands in for the dropped middle of a handed-off
  * transcript: an optional one-line hand-off note, then the first body source that
  * succeeds — the `summarize` result, else the `recall` memory block for the latest
  * directive, else an elision marker. A failing, timing-out or empty source falls through

package/src/handoff/pack.ts

@@ -4,13 +4,22 @@
  * Shape of the result, mirroring Builderforce's `assembleCompacted`
  * (brain-embedded/src/workingTranscript.ts):
  *
- *   system message(s) · ONE assistant note for the dropped middle · the latest user
+ *   leading system message(s) · ONE note for the dropped middle · the latest user
  *   directive re-injected verbatim (only when it fell in the middle) · the verbatim tail
  *
+ * Only the LEADING run of system messages is the fixed prefix. A system message later in
+ * the conversation stays where it was: in the tail when the tail reaches it, else in the
+ * dropped middle — never hoisted to the front, where it would read as if it governed the
+ * whole conversation.
+ *
+ * The note's role keeps turns alternating: it is an `assistant` note when a user turn (the
+ * re-injected directive, or a tail that starts with one) follows it, and a `user` note
+ * when an assistant turn follows or nothing does — never two assistant turns in a row.
+ *
  * The tail is the longest run of whole units (see `segments.ts`) from the end that fits
- * what is left after the system message(s), the directive and room for an elision marker.
- * Whatever room the tail leaves is the note's: summary, else recall, else the marker.
- * The result never exceeds the budget unless the system message(s) + directive alone do.
+ * what is left after the prefix, the directive and room for an elision marker. Whatever
+ * room the tail leaves is the note's: summary, else recall, else the marker. The result
+ * never exceeds the budget unless the prefix + directive alone do.
  */
 
 import { defaultEstimateTokens, handoffBudget, messageTokens, tokensOf } from './budget.js';
@@ -24,6 +33,18 @@ interface Tail {
   tokens: number;
 }
 
+/** Length of the leading run of `system` messages. */
+function leadingSystemCount(all: readonly HandoffMessage[]): number {
+  let n = 0;
+  while (n < all.length && all[n]!.role === 'system') n += 1;
+  return n;
+}
+
+/** The note's role: `user` before an assistant turn (or at the end), else `assistant`. */
+function noteRole(next: HandoffMessage | undefined): 'user' | 'assistant' {
+  return next === undefined || next.role === 'assistant' ? 'user' : 'assistant';
+}
+
 /** Index of the last `user` message, or -1. */
 function latestDirectiveIndex(convo: readonly HandoffMessage[]): number {
   for (let i = convo.length - 1; i >= 0; i--) if (convo[i]!.role === 'user') return i;
@@ -85,8 +106,9 @@ export async function packHandoff(input: HandoffPackInput): Promise<HandoffPack>
   // Under budget: hand the transcript over untouched.
   if (tokensOf(all, estimate) <= budget) return result(all.slice(), 0, estimate);
 
-  const system = all.filter((m) => m.role === 'system');
-  const convo = all.filter((m) => m.role !== 'system');
+  const prefixLen = leadingSystemCount(all);
+  const system = all.slice(0, prefixLen);
+  const convo = all.slice(prefixLen);
   const systemTokens = tokensOf(system, estimate);
   const directiveIdx = latestDirectiveIndex(convo);
   const directive = directiveIdx >= 0 ? convo[directiveIdx] : undefined;
@@ -122,10 +144,11 @@ export async function packHandoff(input: HandoffPackInput): Promise<HandoffPack>
       })
     : null;
 
+  const after: HandoffMessage[] = reinject && directive ? [directive] : [];
+  after.push(...convo.slice(tail.start));
   const messages: HandoffMessage[] = [...system];
-  if (note) messages.push({ role: 'assistant', content: note.text });
-  if (reinject && directive) messages.push(directive);
-  messages.push(...convo.slice(tail.start));
+  if (note) messages.push({ role: noteRole(after[0]), content: note.text });
+  messages.push(...after);
   return result(messages, droppedMsgs.length, estimate, {
     summarized: note?.summarized ?? false,
     recalled: note?.recalled ?? false,