@seanhogg/builderforce-memory 2026.9.33 → 2026.10.1

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.33",
+  "version": "2026.10.1",
   "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",
@@ -18,6 +18,10 @@
       "types": "./dist/wire/index.d.ts",
       "import": "./dist/wire/index.js"
     },
+    "./handoff": {
+      "types": "./dist/handoff/index.d.ts",
+      "import": "./dist/handoff/index.js"
+    },
     "./distillation": {
       "types": "./dist/distillation/index.d.ts",
       "import": "./dist/distillation/index.js"
@@ -95,7 +99,7 @@
   },
   "homepage": "https://github.com/SeanHogg/builderforce-memory/tree/main/packages/memory#readme",
   "peerDependencies": {
-    "@seanhogg/builderforce-memory-engine": "^2026.9.33"
+    "@seanhogg/builderforce-memory-engine": "^2026.10.1"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
@@ -109,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.33"
+    "@seanhogg/builderforce-memory-engine": "2026.10.1"
   },
   "jest": {
     "preset": "ts-jest/presets/default-esm",
@@ -144,6 +148,7 @@
     "collectCoverageFrom": [
       "src/**/*.ts",
       "!src/**/index.ts",
+      "!src/**/*.test.ts",
       "!src/session/**",
       "!src/limbic/LimbicSession.ts"
     ],

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/budget.ts

@@ -0,0 +1,78 @@
+/**
+ * Token estimate + budget math for the hand-off packer.
+ *
+ * The estimate matches Builderforce's gateway heuristic (`workingTranscript.ts`
+ * `messageTokens`): a string content's length / 4, a non-string content's JSON length / 4,
+ * plus any `tool_calls` payload's JSON length, plus 4 tokens of role/framing overhead.
+ */
+
+import type { HandoffBudgetInput, HandoffMessage, TokenEstimator } from './types.js';
+
+/** Per-message role/framing overhead, in tokens. */
+export const MESSAGE_OVERHEAD_TOKENS = 4;
+
+/** Default estimator — chars/4, rounded up. */
+export const defaultEstimateTokens: TokenEstimator = (text) => Math.ceil(text.length / 4);
+
+/**
+ * The tokens a hand-off may use: the next model's window less the reply reserve and the
+ * advertised tool schemas. Never negative.
+ */
+export function handoffBudget(input: HandoffBudgetInput): number {
+  const budget = input.targetContextTokens - input.reserveOutputTokens - (input.toolsTokens ?? 0);
+  return Math.max(0, Math.floor(budget));
+}
+
+/** A message's content as text: the string itself, else its JSON. */
+export function contentText(content: unknown): string {
+  if (typeof content === 'string') return content;
+  return JSON.stringify(content ?? '') ?? '';
+}
+
+/** Does this assistant message carry tool calls? */
+export function hasToolCalls(m: HandoffMessage): boolean {
+  if (m.tool_calls == null) return false;
+  return Array.isArray(m.tool_calls) ? m.tool_calls.length > 0 : true;
+}
+
+/** Estimated tokens for one message (content + tool-call payload + framing). */
+export function messageTokens(m: HandoffMessage, estimate: TokenEstimator): number {
+  let text = contentText(m.content);
+  if (m.tool_calls != null) text += JSON.stringify(m.tool_calls) ?? '';
+  return estimate(text) + MESSAGE_OVERHEAD_TOKENS;
+}
+
+/** Estimated tokens for a list of messages. */
+export function tokensOf(msgs: readonly HandoffMessage[], estimate: TokenEstimator): number {
+  let total = 0;
+  for (const m of msgs) total += messageTokens(m, estimate);
+  return total;
+}
+
+/**
+ * The longest prefix of `text` (with a trailing ellipsis when cut) whose estimate is at
+ * most `maxTokens`; '' when not even one character fits. Binary search, so it works for
+ * any monotone estimator, not only chars/4.
+ */
+export function fitText(text: string, maxTokens: number, estimate: TokenEstimator): string {
+  if (maxTokens <= 0) return '';
+  if (estimate(text) <= maxTokens) return text;
+  let lo = 0;
+  let hi = text.length;
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2);
+    if (estimate(`${text.slice(0, mid)}…`) <= maxTokens) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo > 0 ? `${text.slice(0, lo).trimEnd()}…` : '';
+}
+
+/** A char budget a `recall` callback can honour for `tokens` tokens under `estimate`. */
+export function charsForTokens(tokens: number, estimate: TokenEstimator): number {
+  if (tokens <= 0) return 0;
+  // Calibrate on a probe so a custom estimator gets a proportionate budget; fitText
+  // enforces the token ceiling on whatever comes back either way.
+  const probe = 'x'.repeat(400);
+  const perChar = Math.max(estimate(probe), 1) / probe.length;
+  return Math.max(0, Math.floor(tokens / perChar));
+}

package/src/handoff/handoff.test.ts

@@ -0,0 +1,247 @@
+/**
+ * src/handoff/handoff.test.ts
+ * `packHandoff` (PRD 34 §3.3) — the hand-off packing rules: untouched under budget, the
+ * dropped middle as ONE note (summary → recall → elision), tool pairs never split, the
+ * latest directive verbatim, system kept, the from→to line, and `fits:false` only when
+ * the irreducible core overflows.
+ */
+
+import { handoffBudget, packHandoff, type HandoffMessage, type HandoffPack } from './index.js';
+
+/** A message costing exactly 14 tokens under the default estimate (40 chars / 4 + 4). */
+function msg(role: HandoffMessage['role'], tag: string): HandoffMessage {
+  return { role, content: tag.padEnd(40, '.') };
+}
+
+const SYSTEM = msg('system', 'sys');
+
+/** u1 a1 u2 a2 u3 a3 u4 a4 — the latest directive is u4. */
+function chat(): HandoffMessage[] {
+  const out: HandoffMessage[] = [SYSTEM];
+  for (let i = 1; i <= 4; i++) out.push(msg('user', `u${i}`), msg('assistant', `a${i}`));
+  return out;
+}
+
+const BUDGET = { targetContextTokens: 100, reserveOutputTokens: 20 }; // 80 usable
+
+function expectWithinBudget(pack: HandoffPack, budget = 80): void {
+  expect(pack.fits).toBe(true);
+  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]!;
+  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);
+    expect(handoffBudget({ targetContextTokens: 4096, reserveOutputTokens: 96 })).toBe(4000);
+    expect(handoffBudget({ targetContextTokens: 100, reserveOutputTokens: 200 })).toBe(0);
+  });
+});
+
+describe('packHandoff', () => {
+  it('hands the transcript over untouched when it fits', async () => {
+    const messages = chat();
+    const pack = await packHandoff({ messages, targetContextTokens: 10_000, reserveOutputTokens: 100, from: 'a', to: 'b' });
+    expect(pack.messages).toEqual(messages);
+    expect(pack).toMatchObject({ dropped: 0, summarized: false, recalled: false, fits: true });
+    expect(pack.estimatedTokens).toBe(14 * messages.length);
+  });
+
+  it('drops the middle and puts the summary in ONE note after the system message', async () => {
+    const seen: HandoffMessage[][] = [];
+    const pack = await packHandoff({
+      messages: chat(),
+      ...BUDGET,
+      summarize: async (dropped) => { seen.push([...dropped]); return 'the earlier work, summarized'; },
+    });
+    expectWithinBudget(pack);
+    expect(pack.summarized).toBe(true);
+    expect(pack.recalled).toBe(false);
+    expect(pack.dropped).toBeGreaterThan(0);
+    expect(pack.messages[0]).toBe(SYSTEM);
+    expect(noteOf(pack)).toBe('the earlier work, summarized');
+    expect(seen).toHaveLength(1);
+    expect(seen[0]).toHaveLength(pack.dropped);
+    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.content === 'the earlier work, summarized')).toHaveLength(1);
+    expectAlternating(pack.messages);
+  });
+
+  it('cuts an oversized summary to the room left instead of overflowing', async () => {
+    const pack = await packHandoff({ messages: chat(), ...BUDGET, summarize: async () => 'y'.repeat(5_000) });
+    expectWithinBudget(pack);
+    expect(pack.summarized).toBe(true);
+    expect(noteOf(pack).endsWith('…')).toBe(true);
+  });
+
+  it('falls back to recall for the latest directive when summarize fails', async () => {
+    const calls: Array<[string, number]> = [];
+    const pack = await packHandoff({
+      messages: chat(),
+      ...BUDGET,
+      summarize: async () => { throw new Error('summarizer down'); },
+      recall: async (query, budgetChars) => { calls.push([query, budgetChars]); return 'remembered: X'; },
+    });
+    expectWithinBudget(pack);
+    expect(pack).toMatchObject({ summarized: false, recalled: true });
+    expect(calls).toHaveLength(1);
+    expect(calls[0]![0]).toBe(msg('user', 'u4').content);
+    expect(calls[0]![1]).toBeGreaterThan(0);
+    expect(noteOf(pack)).toBe('remembered: X');
+  });
+
+  it('treats a summarize that outlives timeoutMs as a failure', async () => {
+    const pack = await packHandoff({
+      messages: chat(),
+      ...BUDGET,
+      timeoutMs: 10,
+      summarize: () => new Promise<string>(() => { /* never settles */ }),
+      recall: async () => 'recalled instead',
+    });
+    expect(pack.recalled).toBe(true);
+    expect(noteOf(pack)).toBe('recalled instead');
+  });
+
+  it('falls back to the elision marker when neither summary nor recall is available', async () => {
+    const pack = await packHandoff({
+      messages: chat(),
+      ...BUDGET,
+      summarize: async () => '   ',
+      recall: async () => { throw new Error('no memory'); },
+    });
+    expectWithinBudget(pack);
+    expect(pack).toMatchObject({ summarized: false, recalled: false });
+    expect(noteOf(pack)).toBe(`[${pack.dropped} earlier messages omitted]`);
+
+    const bare = await packHandoff({ messages: chat(), ...BUDGET });
+    expect(noteOf(bare)).toBe(`[${bare.dropped} earlier messages omitted]`);
+  });
+
+  it('never splits an assistant tool_calls message from its tool results', async () => {
+    const call = {
+      role: 'assistant' as const,
+      content: '',
+      tool_calls: [{ id: 'c1', type: 'function', function: { name: 'read', arguments: '{}' } }, { id: 'c2', type: 'function', function: { name: 'read', arguments: '{}' } }],
+    };
+    const messages: HandoffMessage[] = [
+      SYSTEM,
+      msg('user', 'go'),
+      call,
+      { role: 'tool', tool_call_id: 'c1', content: 'z'.repeat(400) },
+      { role: 'tool', tool_call_id: 'c2', content: 'small result'.padEnd(40, '.') },
+      msg('assistant', 'done'),
+    ];
+    for (const target of [70, 90, 140, 250]) {
+      const pack = await packHandoff({ messages, targetContextTokens: target, reserveOutputTokens: 0 });
+      expectWithinBudget(pack, target);
+      const out = pack.messages;
+      const hasCall = out.includes(call);
+      expect(out.includes(messages[3]!)).toBe(hasCall);
+      expect(out.includes(messages[4]!)).toBe(hasCall);
+      out.forEach((m, i) => {
+        if (m.role === 'tool') expect(out[i - 1] === call || out[i - 1]!.role === 'tool').toBe(true);
+      });
+    }
+  });
+
+  it('re-injects the latest directive verbatim right after the note when it falls in the middle', 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 });
+    expectWithinBudget(pack);
+    expect(pack.messages[0]).toBe(SYSTEM);
+    expect(pack.messages[2]).toBe(directive);
+    expect(pack.messages.filter((m) => m === directive)).toHaveLength(1);
+    expect(pack.messages[pack.messages.length - 1]!.content).toBe(msg('assistant', 'step9').content);
+    expect(pack.dropped).toBe(messages.length - pack.messages.length + 1); // +1: the note is new
+  });
+
+  it('keeps every system message, first', async () => {
+    const extra = msg('system', 'policy');
+    const messages = [SYSTEM, extra, ...chat().slice(1)];
+    const pack = await packHandoff({ messages, ...BUDGET });
+    expect(pack.messages.slice(0, 2)).toEqual([SYSTEM, extra]);
+    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);
+    expect(noteOf(handed)).toBe('Handed off from cloud/claude to local/qwen.\nS');
+
+    const same = await packHandoff({ messages: chat(), ...BUDGET, from: 'local/qwen', to: 'local/qwen', summarize: async () => 'S' });
+    expect(noteOf(same)).toBe('S');
+  });
+
+  it('reports fits:false only when the system message + directive alone exceed the budget', async () => {
+    const big = { role: 'system' as const, content: 'q'.repeat(400) }; // 104 tokens
+    const directive = msg('user', 'do it');
+    const over = await packHandoff({ messages: [big, msg('user', 'first'), msg('assistant', 'r'), directive], targetContextTokens: 110, reserveOutputTokens: 0 });
+    expect(over.fits).toBe(false);
+    expect(over.messages).toEqual([big, directive]);
+
+    // Exactly system + directive: fits, everything else dropped, no room for a note.
+    const exact = await packHandoff({ messages: [SYSTEM, msg('user', 'first'), msg('assistant', 'r'), directive], targetContextTokens: 28, reserveOutputTokens: 0 });
+    expect(exact.fits).toBe(true);
+    expect(exact.estimatedTokens).toBeLessThanOrEqual(28);
+    expect(exact.messages).toEqual([SYSTEM, directive]);
+    expect(exact.dropped).toBe(2);
+  });
+});

package/src/handoff/index.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 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.
+ */
+
+export { packHandoff } from './pack.js';
+export { handoffBudget, defaultEstimateTokens, messageTokens, tokensOf } from './budget.js';
+export { handoffLine, elisionMarker } from './note.js';
+export type {
+  HandoffMessage,
+  HandoffPackInput,
+  HandoffPack,
+  HandoffBudgetInput,
+  TokenEstimator,
+} from './types.js';

package/src/handoff/note.ts

@@ -0,0 +1,102 @@
+/**
+ * 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
+ * to the next; nothing here throws for those.
+ */
+
+import { MESSAGE_OVERHEAD_TOKENS, charsForTokens, contentText, fitText } from './budget.js';
+import type { HandoffMessage, HandoffPackInput, TokenEstimator } from './types.js';
+
+/** The hand-off line, or '' when either ref is missing or they are the same model. */
+export function handoffLine(from?: string, to?: string): string {
+  return from && to && from !== to ? `Handed off from ${from} to ${to}.` : '';
+}
+
+/** The marker for `n` messages that were dropped with nothing to stand in for them. */
+export function elisionMarker(n: number): string {
+  return `[${n} earlier messages omitted]`;
+}
+
+/** Header + body as one note text. */
+export function composeNote(header: string, body: string): string {
+  return header ? `${header}\n${body}` : body;
+}
+
+/** Tokens the note message costs, framing included. */
+export function noteTokens(text: string, estimate: TokenEstimator): number {
+  return estimate(text) + MESSAGE_OVERHEAD_TOKENS;
+}
+
+export interface NoteRequest {
+  header: string;
+  dropped: readonly HandoffMessage[];
+  directive: HandoffMessage | undefined;
+  /** Tokens the note message may cost, framing included. */
+  room: number;
+  estimate: TokenEstimator;
+  summarize?: HandoffPackInput['summarize'];
+  recall?: HandoffPackInput['recall'];
+  timeoutMs?: number;
+}
+
+export interface NoteResult {
+  text: string;
+  summarized: boolean;
+  recalled: boolean;
+}
+
+/** Settle `run()` to its trimmed string, or '' on throw, rejection, timeout or non-string. */
+async function attempt(run: () => Promise<string>, timeoutMs?: number): Promise<string> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const work = Promise.resolve().then(run);
+    const raced = timeoutMs && timeoutMs > 0
+      ? Promise.race([work, new Promise<string>((resolve) => { timer = setTimeout(() => resolve(''), timeoutMs); })])
+      : work;
+    const out = await raced;
+    return typeof out === 'string' ? out.trim() : '';
+  } catch {
+    return '';
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+/** `body` cut so header + body fits `room`; '' when nothing of it fits. */
+function fitBody(req: NoteRequest, body: string): string {
+  const headerTokens = req.header ? req.estimate(`${req.header}\n`) : 0;
+  let max = req.room - MESSAGE_OVERHEAD_TOKENS - headerTokens;
+  // The estimator need not be additive; shrink until the composed note really fits.
+  for (let tries = 0; tries < 16 && max > 0; tries++, max--) {
+    const fitted = fitText(body, max, req.estimate);
+    if (!fitted) return '';
+    if (noteTokens(composeNote(req.header, fitted), req.estimate) <= req.room) return fitted;
+  }
+  return '';
+}
+
+/** Build the note, or null when not even the elision marker fits `room`. */
+export async function buildNote(req: NoteRequest): Promise<NoteResult | null> {
+  if (req.summarize) {
+    const summarize = req.summarize;
+    const summary = fitBody(req, await attempt(() => summarize(req.dropped), req.timeoutMs));
+    if (summary) return { text: composeNote(req.header, summary), summarized: true, recalled: false };
+  }
+
+  if (req.recall && req.directive) {
+    const recall = req.recall;
+    const headerTokens = req.header ? req.estimate(`${req.header}\n`) : 0;
+    const budgetChars = charsForTokens(req.room - MESSAGE_OVERHEAD_TOKENS - headerTokens, req.estimate);
+    if (budgetChars > 0) {
+      const query = contentText(req.directive.content);
+      const block = fitBody(req, await attempt(() => recall(query, budgetChars), req.timeoutMs));
+      if (block) return { text: composeNote(req.header, block), summarized: false, recalled: true };
+    }
+  }
+
+  const marker = composeNote(req.header, elisionMarker(req.dropped.length));
+  if (noteTokens(marker, req.estimate) <= req.room) return { text: marker, summarized: false, recalled: false };
+  return null;
+}