@git-stunts/git-warp 11.3.3 → 11.5.1

package/README.md

@@ -55,6 +55,10 @@ const result = await graph.query()
 
 ## How It Works
 
+<p align="center">
+  <img src="docs/diagrams/fig-data-storage.svg" alt="WARP data storage — invisible to normal Git workflows" width="700">
+</p>
+
 ### The Multi-Writer Problem (and How It's Solved)
 
 Multiple people (or machines, or processes) can write to the same graph **simultaneously, without any coordination**. There's no central server, no locking, no "wait your turn."
@@ -73,6 +77,10 @@ Every operation gets a unique **EventId** — `(lamport, writerId, patchSha, opI
 
 ## Multi-Writer Collaboration
 
+<p align="center">
+  <img src="docs/diagrams/fig-multi-writer.svg" alt="Multi-writer convergence — independent chains, deterministic merge" width="700">
+</p>
+
 Writers operate independently on the same Git repository. Sync happens through standard Git transport (push/pull) or the built-in HTTP sync protocol.
 
 ```javascript
@@ -328,6 +336,29 @@ const sha = await (await graph.createPatch())
 
 Each `commit()` creates one Git commit containing all the operations, advances the writer's Lamport clock, and updates the writer's ref via compare-and-swap.
 
+### Content Attachment
+
+Attach content-addressed blobs to nodes and edges as first-class payloads (Paper I `Atom(p)`). Blobs are stored in the Git object store, referenced by SHA, and inherit CRDT merge, time-travel, and observer scoping automatically.
+
+```javascript
+const patch = await graph.createPatch();
+patch.addNode('adr:0007');                                    // sync — queues a NodeAdd op
+await patch.attachContent('adr:0007', '# ADR 0007\n\nDecision text...'); // async — writes blob
+await patch.commit();
+
+// Read content back
+const buffer = await graph.getContent('adr:0007');   // Buffer | null
+const oid    = await graph.getContentOid('adr:0007'); // hex SHA or null
+
+// Edge content works the same way (assumes nodes and edge already exist)
+const patch2 = await graph.createPatch();
+await patch2.attachEdgeContent('a', 'b', 'rel', 'edge payload');
+await patch2.commit();
+const edgeBuf = await graph.getEdgeContent('a', 'b', 'rel');
+```
+
+Content blobs survive `git gc` — their OIDs are embedded in the patch commit tree and checkpoint tree, keeping them reachable.
+
 ### Writer API
 
 For repeated writes, the Writer API is more convenient:
@@ -434,6 +465,10 @@ When a seek cursor is active, `query`, `info`, `materialize`, and `history` auto
 
 ## Architecture
 
+<p align="center">
+  <img src="docs/diagrams/fig-architecture.svg" alt="Hexagonal architecture — dependency rule: arrows point inward only" width="700">
+</p>
+
 The codebase follows hexagonal architecture with ports and adapters:
 
 **Ports** define abstract interfaces for infrastructure:
@@ -508,7 +543,7 @@ npm run test:matrix     # All runtimes in parallel
 ## When NOT to Use It
 
 - **High-throughput transactional workloads.** If you need thousands of writes per second with immediate consistency, use Postgres or Redis.
-- **Large binary or blob storage.** Data lives in Git commit messages (default cap 1 MB). Use object storage for images or videos.
+- **Large binary or blob storage.** Properties live in Git commit messages; content blobs live in the Git object store. Neither is optimized for large media files. Use object storage for images or videos.
 - **Sub-millisecond read latency.** Materialization has overhead. Use an in-memory database for real-time gaming physics or HFT.
 - **Simple key-value storage.** If you don't have relationships or need traversals, a graph database is overkill.
 - **Non-Git environments.** The value proposition depends on Git infrastructure (push/pull, content-addressing).

package/index.d.ts

@@ -1147,6 +1147,12 @@ export function decodeEdgePropKey(encoded: string): { from: string; to: string;
  */
 export function isEdgePropKey(key: string): boolean;
 
+/**
+ * Well-known property key for content attachment.
+ * Stores a content-addressed blob OID as the property value.
+ */
+export const CONTENT_PROPERTY_KEY: '_content';
+
 /**
  * Configuration for an observer view.
  */
@@ -1345,6 +1351,10 @@ export class PatchBuilderV2 {
   setProperty(nodeId: string, key: string, value: unknown): PatchBuilderV2;
   /** Sets a property on an edge. */
   setEdgeProperty(from: string, to: string, label: string, key: string, value: unknown): PatchBuilderV2;
+  /** Attaches content to a node (writes blob + sets _content property). */
+  attachContent(nodeId: string, content: Buffer | string): Promise<PatchBuilderV2>;
+  /** Attaches content to an edge (writes blob + sets _content edge property). */
+  attachEdgeContent(from: string, to: string, label: string, content: Buffer | string): Promise<PatchBuilderV2>;
   /** Builds the PatchV2 object without committing. */
   build(): PatchV2;
   /** Commits the patch to the graph and returns the commit SHA. */
@@ -1375,6 +1385,10 @@ export class PatchSession {
   setProperty(nodeId: string, key: string, value: unknown): this;
   /** Sets a property on an edge. */
   setEdgeProperty(from: string, to: string, label: string, key: string, value: unknown): this;
+  /** Attaches content to a node (writes blob + sets _content property). */
+  attachContent(nodeId: string, content: Buffer | string): Promise<this>;
+  /** Attaches content to an edge (writes blob + sets _content edge property). */
+  attachEdgeContent(from: string, to: string, label: string, content: Buffer | string): Promise<this>;
   /** Builds the PatchV2 object without committing. */
   build(): PatchV2;
   /** Commits the patch with CAS protection. */
@@ -1645,6 +1659,28 @@ export default class WarpGraph {
    */
   getEdgeProps(from: string, to: string, label: string): Promise<Record<string, unknown> | null>;
 
+  /**
+   * Gets the content blob OID for a node, or null if none is attached.
+   */
+  getContentOid(nodeId: string): Promise<string | null>;
+
+  /**
+   * Gets the content blob for a node, or null if none is attached.
+   * Returns raw Buffer; call `.toString('utf8')` for text.
+   */
+  getContent(nodeId: string): Promise<Buffer | null>;
+
+  /**
+   * Gets the content blob OID for an edge, or null if none is attached.
+   */
+  getEdgeContentOid(from: string, to: string, label: string): Promise<string | null>;
+
+  /**
+   * Gets the content blob for an edge, or null if none is attached.
+   * Returns raw Buffer; call `.toString('utf8')` for text.
+   */
+  getEdgeContent(from: string, to: string, label: string): Promise<Buffer | null>;
+
   /**
    * Checks if a node exists in the materialized state.
    */

package/index.js

@@ -75,6 +75,7 @@ import {
   encodeEdgePropKey,
   decodeEdgePropKey,
   isEdgePropKey,
+  CONTENT_PROPERTY_KEY,
 } from './src/domain/services/KeyCodec.js';
 import {
   createTickReceipt,
@@ -173,6 +174,7 @@ export {
   encodeEdgePropKey,
   decodeEdgePropKey,
   isEdgePropKey,
+  CONTENT_PROPERTY_KEY,
 
   // WARP migration
   migrateV4toV5,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/git-warp",
-  "version": "11.3.3",
+  "version": "11.5.1",
   "description": "Deterministic WARP graph over Git: graph-native storage, traversal, and tooling.",
   "type": "module",
   "license": "Apache-2.0",
@@ -90,7 +90,8 @@
     "typecheck:src": "tsc --noEmit -p tsconfig.src.json",
     "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
     "typecheck:consumer": "tsc --noEmit -p test/type-check/tsconfig.json",
-    "typecheck:policy": "node scripts/ts-policy-check.js"
+    "typecheck:policy": "node scripts/ts-policy-check.js",
+    "typecheck:surface": "node scripts/check-dts-surface.js"
   },
   "dependencies": {
     "@git-stunts/alfred": "^0.4.0",

package/src/domain/WarpGraph.js

@@ -18,12 +18,12 @@ import defaultCrypto from './utils/defaultCrypto.js';
 import defaultClock from './utils/defaultClock.js';
 import LogicalTraversal from './services/LogicalTraversal.js';
 import LRUCache from './utils/LRUCache.js';
+import SyncController from './services/SyncController.js';
 import { wireWarpMethods } from './warp/_wire.js';
 import * as queryMethods from './warp/query.methods.js';
 import * as subscribeMethods from './warp/subscribe.methods.js';
 import * as provenanceMethods from './warp/provenance.methods.js';
 import * as forkMethods from './warp/fork.methods.js';
-import * as syncMethods from './warp/sync.methods.js';
 import * as checkpointMethods from './warp/checkpoint.methods.js';
 import * as patchMethods from './warp/patch.methods.js';
 import * as materializeMethods from './warp/materialize.methods.js';
@@ -172,6 +172,9 @@ export default class WarpGraph {
 
     /** @type {number} */
     this._auditSkipCount = 0;
+
+    /** @type {SyncController} */
+    this._syncController = new SyncController(this);
   }
 
   /**
@@ -410,9 +413,26 @@ wireWarpMethods(WarpGraph, [
   subscribeMethods,
   provenanceMethods,
   forkMethods,
-  syncMethods,
   checkpointMethods,
   patchMethods,
   materializeMethods,
   materializeAdvancedMethods,
 ]);
+
+// ── Sync methods: direct delegation to SyncController (no stub file) ────────
+const syncDelegates = /** @type {const} */ ([
+  'getFrontier', 'hasFrontierChanged', 'status',
+  'createSyncRequest', 'processSyncRequest', 'applySyncResponse',
+  'syncNeeded', 'syncWith', 'serve',
+]);
+for (const method of syncDelegates) {
+  Object.defineProperty(WarpGraph.prototype, method, {
+    // eslint-disable-next-line object-shorthand -- function keyword needed for `this` binding
+    value: /** @this {WarpGraph} @param {*[]} args */ function (...args) {
+      return this._syncController[method](...args);
+    },
+    writable: true,
+    configurable: true,
+    enumerable: false,
+  });
+}

package/src/domain/services/BitmapIndexReader.js

@@ -4,6 +4,7 @@ import nullLogger from '../utils/nullLogger.js';
 import LRUCache from '../utils/LRUCache.js';
 import { getRoaringBitmap32 } from '../utils/roaring.js';
 import { canonicalStringify } from '../utils/canonicalStringify.js';
+import { isValidShardOid } from '../utils/validateShardOid.js';
 
 /** @typedef {import('../../ports/IndexStoragePort.js').default} IndexStoragePort */
 /** @typedef {import('../types/WarpPersistence.js').IndexStorage} IndexStorage */
@@ -50,24 +51,24 @@ const computeChecksum = async (data, version, crypto) => {
  * - {@link ShardCorruptionError} for invalid shard format
  * - {@link ShardValidationError} for version or checksum mismatches
  *
- * In non-strict mode (default), validation failures are logged as warnings
+ * In non-strict mode (strict: false), validation failures are logged as warnings
  * and an empty shard is returned for graceful degradation.
  *
  * **Note**: Storage errors (e.g., `storage.readBlob` failures) always throw
  * {@link ShardLoadError} regardless of strict mode.
  *
  * @example
- * // Non-strict mode (default) - graceful degradation on validation errors
+ * // Strict mode (default) - throws on any validation failure
  * const reader = new BitmapIndexReader({ storage });
  * reader.setup(shardOids);
  * const parents = await reader.getParents('abc123...');
  *
  * @example
- * // Strict mode - throws on any validation failure
- * const strictReader = new BitmapIndexReader({ storage, strict: true });
- * strictReader.setup(shardOids);
+ * // Non-strict mode - graceful degradation on validation errors
+ * const lenientReader = new BitmapIndexReader({ storage, strict: false });
+ * lenientReader.setup(shardOids);
  * try {
- *   const parents = await strictReader.getParents('abc123...');
+ *   const parents = await lenientReader.getParents('abc123...');
  * } catch (err) {
  *   if (err instanceof ShardValidationError) {
  *     console.error('Shard validation failed:', err.field, err.expected, err.actual);
@@ -83,14 +84,14 @@ export default class BitmapIndexReader {
    * Creates a BitmapIndexReader instance.
    * @param {Object} options
    * @param {IndexStoragePort} options.storage - Storage adapter for reading index data
-   * @param {boolean} [options.strict=false] - If true, throw errors on validation failures; if false, log warnings and return empty shards
+   * @param {boolean} [options.strict=true] - If true, throw errors on validation failures; if false, log warnings and return empty shards
    * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger for structured logging.
    *   Defaults to NoOpLogger (no logging).
    * @param {number} [options.maxCachedShards=100] - Maximum number of shards to keep in the LRU cache.
    *   When exceeded, least recently used shards are evicted to free memory.
    * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - CryptoPort instance for checksum verification.
    */
-  constructor({ storage, strict = false, logger = nullLogger, maxCachedShards = DEFAULT_MAX_CACHED_SHARDS, crypto } = /** @type {{ storage: IndexStoragePort, strict?: boolean, logger?: LoggerPort, maxCachedShards?: number, crypto?: CryptoPort }} */ ({})) {
+  constructor({ storage, strict = true, logger = nullLogger, maxCachedShards = DEFAULT_MAX_CACHED_SHARDS, crypto } = /** @type {{ storage: IndexStoragePort, strict?: boolean, logger?: LoggerPort, maxCachedShards?: number, crypto?: CryptoPort }} */ ({})) {
     if (!storage) {
       throw new Error('BitmapIndexReader requires a storage adapter');
     }
@@ -132,8 +133,29 @@ export default class BitmapIndexReader {
    * const parents = await reader.getParents('abcd1234...'); // loads meta_ab, shards_rev_ab
    */
   setup(shardOids) {
-    this.shardOids = new Map(Object.entries(shardOids));
-    this._idToShaCache = null; // Clear cache when shards change
+    const entries = Object.entries(shardOids);
+    /** @type {[string, string][]} */
+    const validEntries = [];
+    for (const [path, oid] of entries) {
+      if (isValidShardOid(oid)) {
+        validEntries.push([path, oid]);
+      } else if (this.strict) {
+        throw new ShardCorruptionError('Invalid shard OID', {
+          shardPath: path,
+          oid,
+          reason: 'invalid_oid',
+        });
+      } else {
+        this.logger.warn('Skipping shard with invalid OID', {
+          operation: 'setup',
+          shardPath: path,
+          oid,
+          reason: 'invalid_oid',
+        });
+      }
+    }
+    this.shardOids = new Map(validEntries);
+    this._idToShaCache = null;
     this.loadedShards.clear();
   }
 

package/src/domain/services/CheckpointService.js

@@ -25,7 +25,7 @@ import { createORSet, orsetAdd, orsetCompact } from '../crdt/ORSet.js';
 import { createDot } from '../crdt/Dot.js';
 import { createVersionVector } from '../crdt/VersionVector.js';
 import { cloneStateV5, reduceV5 } from './JoinReducer.js';
-import { encodeEdgeKey, encodePropKey } from './KeyCodec.js';
+import { encodeEdgeKey, encodePropKey, CONTENT_PROPERTY_KEY, decodePropKey, isEdgePropKey, decodeEdgePropKey } from './KeyCodec.js';
 import { ProvenanceIndex } from './ProvenanceIndex.js';
 
 // ============================================================================
@@ -132,6 +132,20 @@ export async function createV5({
     provenanceIndexBlobOid = await persistence.writeBlob(/** @type {Buffer} */ (provenanceIndexBuffer));
   }
 
+  // 6c. Collect content blob OIDs from state properties for GC anchoring.
+  // If patch commits are ever pruned, content blobs remain reachable via
+  // the checkpoint tree. Without this, git gc would nuke content blobs
+  // whose only anchor was the (now-pruned) patch commit tree.
+  const contentOids = new Set();
+  for (const [propKey, register] of checkpointState.prop) {
+    const { propKey: decodedKey } = isEdgePropKey(propKey)
+      ? decodeEdgePropKey(propKey)
+      : decodePropKey(propKey);
+    if (decodedKey === CONTENT_PROPERTY_KEY && typeof register.value === 'string') {
+      contentOids.add(register.value);
+    }
+  }
+
   // 7. Create tree with sorted entries
   const treeEntries = [
     `100644 blob ${appliedVVBlobOid}\tappliedVV.cbor`,
@@ -145,6 +159,11 @@ export async function createV5({
     treeEntries.push(`100644 blob ${provenanceIndexBlobOid}\tprovenanceIndex.cbor`);
   }
 
+  // Add content blob anchors
+  for (const oid of contentOids) {
+    treeEntries.push(`100644 blob ${oid}\t_content_${oid}`);
+  }
+
   // Sort entries by filename for deterministic tree (git requires sorted entries by path)
   treeEntries.sort((a, b) => {
     const filenameA = a.split('\t')[1];

package/src/domain/services/JoinReducer.js

@@ -329,47 +329,68 @@ function propSetOutcome(propMap, op, eventId) {
 }
 
 /**
- * Joins a patch into state, applying all operations in order.
- *
- * This is the primary function for incorporating a single patch into WARP state.
- * It iterates through all operations in the patch, creates EventIds for causality
- * tracking, and applies each operation using `applyOpV2`.
- *
- * **Receipt Collection Mode**:
- * When `collectReceipts` is true, this function also computes the outcome of each
- * operation (applied, redundant, or superseded) and returns a TickReceipt for
- * provenance tracking. This has a small performance cost, so it's disabled by default.
- *
- * **Warning**: This function mutates `state` in place. For immutable operations,
- * clone the state first using `cloneStateV5()`.
+ * Folds a patch's own dot into the observed frontier.
+ * @param {Map<string, number>} frontier
+ * @param {string} writer
+ * @param {number} lamport
+ */
+function foldPatchDot(frontier, writer, lamport) {
+  const current = frontier.get(writer) || 0;
+  if (lamport > current) {
+    frontier.set(writer, lamport);
+  }
+}
+
+/**
+ * Merges a patch's context into state and folds the patch dot.
+ * @param {WarpStateV5} state
+ * @param {Object} patch
+ * @param {string} patch.writer
+ * @param {number} patch.lamport
+ * @param {Map<string, number>|{[x: string]: number}} patch.context
+ */
+function updateFrontierFromPatch(state, patch) {
+  const contextVV = patch.context instanceof Map
+    ? patch.context
+    : vvDeserialize(patch.context || {});
+  state.observedFrontier = vvMerge(state.observedFrontier, contextVV);
+  foldPatchDot(state.observedFrontier, patch.writer, patch.lamport);
+}
+
+/**
+ * Applies a patch to state without receipt collection (zero overhead).
  *
- * @param {WarpStateV5} state - The state to mutate. Modified in place.
+ * @param {WarpStateV5} state - The state to mutate in place
  * @param {Object} patch - The patch to apply
- * @param {string} patch.writer - Writer ID who created this patch
- * @param {number} patch.lamport - Lamport timestamp of this patch
- * @param {Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, oid?: string}>} patch.ops - Array of operations to apply
- * @param {Map<string, number>|{[x: string]: number}} patch.context - Version vector context (Map or serialized form)
- * @param {string} patchSha - The Git SHA of the patch commit (used for EventId creation)
- * @param {boolean} [collectReceipts=false] - When true, computes and returns receipt data
- * @returns {WarpStateV5|{state: WarpStateV5, receipt: import('../types/TickReceipt.js').TickReceipt}}
- *          Returns mutated state directly when collectReceipts is false;
- *          returns {state, receipt} object when collectReceipts is true
+ * @param {string} patch.writer
+ * @param {number} patch.lamport
+ * @param {Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, oid?: string}>} patch.ops
+ * @param {Map<string, number>|{[x: string]: number}} patch.context
+ * @param {string} patchSha - Git SHA of the patch commit
+ * @returns {WarpStateV5} The mutated state
  */
-export function join(state, patch, patchSha, collectReceipts) {
-  // ZERO-COST: when collectReceipts is falsy, skip all receipt logic
-  if (!collectReceipts) {
-    for (let i = 0; i < patch.ops.length; i++) {
-      const eventId = createEventId(patch.lamport, patch.writer, patchSha, i);
-      applyOpV2(state, patch.ops[i], eventId);
-    }
-    const contextVV = patch.context instanceof Map
-      ? patch.context
-      : vvDeserialize(patch.context);
-    state.observedFrontier = vvMerge(state.observedFrontier, contextVV);
-    return state;
+export function applyFast(state, patch, patchSha) {
+  for (let i = 0; i < patch.ops.length; i++) {
+    const eventId = createEventId(patch.lamport, patch.writer, patchSha, i);
+    applyOpV2(state, patch.ops[i], eventId);
   }
+  updateFrontierFromPatch(state, patch);
+  return state;
+}
 
-  // Receipt-enabled path
+/**
+ * Applies a patch to state with receipt collection for provenance tracking.
+ *
+ * @param {WarpStateV5} state - The state to mutate in place
+ * @param {Object} patch - The patch to apply
+ * @param {string} patch.writer
+ * @param {number} patch.lamport
+ * @param {Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, oid?: string}>} patch.ops
+ * @param {Map<string, number>|{[x: string]: number}} patch.context
+ * @param {string} patchSha - Git SHA of the patch commit
+ * @returns {{state: WarpStateV5, receipt: import('../types/TickReceipt.js').TickReceipt}}
+ */
+export function applyWithReceipt(state, patch, patchSha) {
   /** @type {import('../types/TickReceipt.js').OpOutcome[]} */
   const opResults = [];
   for (let i = 0; i < patch.ops.length; i++) {
@@ -419,10 +440,7 @@ export function join(state, patch, patchSha, collectReceipts) {
     opResults.push(entry);
   }
 
-  const contextVV = patch.context instanceof Map
-    ? patch.context
-    : vvDeserialize(patch.context);
-  state.observedFrontier = vvMerge(state.observedFrontier, contextVV);
+  updateFrontierFromPatch(state, patch);
 
   const receipt = createTickReceipt({
     patchSha,
@@ -434,6 +452,39 @@ export function join(state, patch, patchSha, collectReceipts) {
   return { state, receipt };
 }
 
+/**
+ * Joins a patch into state, applying all operations in order.
+ *
+ * This is the primary function for incorporating a single patch into WARP state.
+ * It iterates through all operations in the patch, creates EventIds for causality
+ * tracking, and applies each operation using `applyOpV2`.
+ *
+ * **Receipt Collection Mode**:
+ * When `collectReceipts` is true, this function also computes the outcome of each
+ * operation (applied, redundant, or superseded) and returns a TickReceipt for
+ * provenance tracking. This has a small performance cost, so it's disabled by default.
+ *
+ * **Warning**: This function mutates `state` in place. For immutable operations,
+ * clone the state first using `cloneStateV5()`.
+ *
+ * @param {WarpStateV5} state - The state to mutate. Modified in place.
+ * @param {Object} patch - The patch to apply
+ * @param {string} patch.writer - Writer ID who created this patch
+ * @param {number} patch.lamport - Lamport timestamp of this patch
+ * @param {Array<{type: string, node?: string, dot?: import('../crdt/Dot.js').Dot, observedDots?: string[], from?: string, to?: string, label?: string, key?: string, value?: unknown, oid?: string}>} patch.ops - Array of operations to apply
+ * @param {Map<string, number>|{[x: string]: number}} patch.context - Version vector context (Map or serialized form)
+ * @param {string} patchSha - The Git SHA of the patch commit (used for EventId creation)
+ * @param {boolean} [collectReceipts=false] - When true, computes and returns receipt data
+ * @returns {WarpStateV5|{state: WarpStateV5, receipt: import('../types/TickReceipt.js').TickReceipt}}
+ *          Returns mutated state directly when collectReceipts is false;
+ *          returns {state, receipt} object when collectReceipts is true
+ */
+export function join(state, patch, patchSha, collectReceipts) {
+  return collectReceipts
+    ? applyWithReceipt(state, patch, patchSha)
+    : applyFast(state, patch, patchSha);
+}
+
 /**
  * Joins two V5 states together using CRDT merge semantics.
  *
@@ -545,14 +596,14 @@ export function reduceV5(patches, initialState, options) {
   if (options && options.receipts) {
     const receipts = [];
     for (const { patch, sha } of patches) {
-      const result = /** @type {{state: WarpStateV5, receipt: import('../types/TickReceipt.js').TickReceipt}} */ (join(state, patch, sha, true));
+      const result = applyWithReceipt(state, patch, sha);
       receipts.push(result.receipt);
     }
     return { state, receipts };
   }
 
   for (const { patch, sha } of patches) {
-    join(state, patch, sha);
+    applyFast(state, patch, sha);
   }
   return state;
 }

package/src/domain/services/KeyCodec.js

@@ -18,6 +18,13 @@ export const FIELD_SEPARATOR = '\0';
  */
 export const EDGE_PROP_PREFIX = '\x01';
 
+/**
+ * Well-known property key for content attachment.
+ * Stores a content-addressed blob OID as the property value.
+ * @const {string}
+ */
+export const CONTENT_PROPERTY_KEY = '_content';
+
 /**
  * Encodes an edge key to a string for Map storage.
  *

package/src/domain/services/PatchBuilderV2.js

@@ -23,7 +23,7 @@ import {
   createPropSetV2,
   createPatchV2,
 } from '../types/WarpTypesV2.js';
-import { encodeEdgeKey, EDGE_PROP_PREFIX } from './KeyCodec.js';
+import { encodeEdgeKey, EDGE_PROP_PREFIX, CONTENT_PROPERTY_KEY } from './KeyCodec.js';
 import { encodePatchMessage, decodePatchMessage, detectMessageKind } from './WarpMessageCodec.js';
 import { buildWriterRef } from '../utils/RefLayout.js';
 import WriterError from '../errors/WriterError.js';
@@ -124,6 +124,13 @@ export class PatchBuilderV2 {
     /** @type {{ warn: Function }} */
     this._logger = logger || nullLogger;
 
+    /**
+     * Content blob OIDs written during this patch via attachContent/attachEdgeContent.
+     * These are embedded in the commit tree for GC protection.
+     * @type {string[]}
+     */
+    this._contentBlobs = [];
+
     /**
      * Nodes/edges read by this patch (for provenance tracking).
      *
@@ -430,6 +437,45 @@ export class PatchBuilderV2 {
     return this;
   }
 
+  /**
+   * Attaches content to a node by writing the blob to the Git object store
+   * and storing the blob OID as the `_content` property.
+   *
+   * The blob OID is also tracked for embedding in the commit tree, which
+   * ensures content blobs survive `git gc` (GC protection via reachability).
+   *
+   * Note: The node must exist in the materialized state (or be added in
+   * this patch) for `getContent()` to find it later. `attachContent()`
+   * only sets the `_content` property — it does not create the node.
+   *
+   * @param {string} nodeId - The node ID to attach content to
+   * @param {Buffer|string} content - The content to attach
+   * @returns {Promise<PatchBuilderV2>} This builder instance for method chaining
+   */
+  async attachContent(nodeId, content) {
+    const oid = await this._persistence.writeBlob(content);
+    this.setProperty(nodeId, CONTENT_PROPERTY_KEY, oid);
+    this._contentBlobs.push(oid);
+    return this;
+  }
+
+  /**
+   * Attaches content to an edge by writing the blob to the Git object store
+   * and storing the blob OID as the `_content` edge property.
+   *
+   * @param {string} from - Source node ID
+   * @param {string} to - Target node ID
+   * @param {string} label - Edge label
+   * @param {Buffer|string} content - The content to attach
+   * @returns {Promise<PatchBuilderV2>} This builder instance for method chaining
+   */
+  async attachEdgeContent(from, to, label, content) {
+    const oid = await this._persistence.writeBlob(content);
+    this.setEdgeProperty(from, to, label, CONTENT_PROPERTY_KEY, oid);
+    this._contentBlobs.push(oid);
+    return this;
+  }
+
   /**
    * Builds the PatchV2 object without committing.
    *
@@ -577,10 +623,14 @@ export class PatchBuilderV2 {
     const patchCbor = this._codec.encode(patch);
     const patchBlobOid = await this._persistence.writeBlob(/** @type {Buffer} */ (patchCbor));
 
-    // 6. Create tree with the blob
+    // 6. Create tree with the patch blob + any content blobs (deduplicated)
     // Format for mktree: "mode type oid\tpath"
-    const treeEntry = `100644 blob ${patchBlobOid}\tpatch.cbor`;
-    const treeOid = await this._persistence.writeTree([treeEntry]);
+    const treeEntries = [`100644 blob ${patchBlobOid}\tpatch.cbor`];
+    const uniqueBlobs = [...new Set(this._contentBlobs)];
+    for (const blobOid of uniqueBlobs) {
+      treeEntries.push(`100644 blob ${blobOid}\t_content_${blobOid}`);
+    }
+    const treeOid = await this._persistence.writeTree(treeEntries);
 
     // 7. Create commit with proper trailers linking to the parent
     const commitMessage = encodePatchMessage({