@git-stunts/git-warp 11.3.3 → 11.5.0

package/README.md

@@ -328,6 +328,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:
@@ -508,7 +531,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.0",
   "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/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

@@ -328,6 +328,19 @@ function propSetOutcome(propMap, op, eventId) {
   return { target, result: 'redundant' };
 }
 
+/**
+ * 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);
+  }
+}
+
 /**
  * Joins a patch into state, applying all operations in order.
  *
@@ -366,6 +379,7 @@ export function join(state, patch, patchSha, collectReceipts) {
       ? patch.context
       : vvDeserialize(patch.context);
     state.observedFrontier = vvMerge(state.observedFrontier, contextVV);
+    foldPatchDot(state.observedFrontier, patch.writer, patch.lamport);
     return state;
   }
 
@@ -423,6 +437,7 @@ export function join(state, patch, patchSha, collectReceipts) {
     ? patch.context
     : vvDeserialize(patch.context);
   state.observedFrontier = vvMerge(state.observedFrontier, contextVV);
+  foldPatchDot(state.observedFrontier, patch.writer, patch.lamport);
 
   const receipt = createTickReceipt({
     patchSha,

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({

package/src/domain/warp/PatchSession.js

@@ -148,6 +148,37 @@ export class PatchSession {
     return this;
   }
 
+  /**
+   * Attaches content to a node.
+   *
+   * @param {string} nodeId - The node ID to attach content to
+   * @param {Buffer|string} content - The content to attach
+   * @returns {Promise<this>} This session for chaining
+   * @throws {Error} If this session has already been committed
+   */
+  async attachContent(nodeId, content) {
+    this._ensureNotCommitted();
+    await this._builder.attachContent(nodeId, content);
+    return this;
+  }
+
+  /**
+   * Attaches content to an edge.
+   *
+   * @param {string} from - Source node ID
+   * @param {string} to - Target node ID
+   * @param {string} label - Edge label/type
+   * @param {Buffer|string} content - The content to attach
+   * @returns {Promise<this>} This session for chaining
+   * @throws {Error} If this session has already been committed
+   */
+  // eslint-disable-next-line max-params -- direct delegate matching PatchBuilderV2 signature
+  async attachEdgeContent(from, to, label, content) {
+    this._ensureNotCommitted();
+    await this._builder.attachEdgeContent(from, to, label, content);
+    return this;
+  }
+
   /**
    * Builds the PatchV2 object without committing.
    *

package/src/domain/warp/query.methods.js

@@ -8,7 +8,7 @@
  */
 
 import { orsetContains, orsetElements } from '../crdt/ORSet.js';
-import { decodePropKey, isEdgePropKey, decodeEdgePropKey, encodeEdgeKey, decodeEdgeKey } from '../services/KeyCodec.js';
+import { decodePropKey, isEdgePropKey, decodeEdgePropKey, encodeEdgeKey, decodeEdgeKey, CONTENT_PROPERTY_KEY } from '../services/KeyCodec.js';
 import { compareEventIds } from '../utils/EventId.js';
 import { cloneStateV5 } from '../services/JoinReducer.js';
 import QueryBuilder from '../services/QueryBuilder.js';
@@ -278,3 +278,85 @@ export async function translationCost(configA, configB) {
   const s = /** @type {import('../services/JoinReducer.js').WarpStateV5} */ (this._cachedState);
   return computeTranslationCost(configA, configB, s);
 }
+
+/**
+ * Gets the content blob OID for a node, or null if none is attached.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string} nodeId - The node ID to check
+ * @returns {Promise<string|null>} Hex blob OID or null
+ * @throws {import('../errors/QueryError.js').default} If no cached state exists (code: `E_NO_STATE`)
+ */
+export async function getContentOid(nodeId) {
+  const props = await getNodeProps.call(this, nodeId);
+  if (!props) {
+    return null;
+  }
+  // getNodeProps returns a Map — use .get() for property access
+  const oid = props.get(CONTENT_PROPERTY_KEY);
+  return (typeof oid === 'string') ? oid : null;
+}
+
+/**
+ * Gets the content blob for a node, or null if none is attached.
+ *
+ * Returns the raw Buffer from `readBlob()`. Consumers wanting text
+ * should call `.toString('utf8')` on the result.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string} nodeId - The node ID to get content for
+ * @returns {Promise<Buffer|null>} Content buffer or null
+ * @throws {Error} If the referenced blob OID is not in the object store
+ *   (e.g., garbage-collected despite anchoring). Callers should handle this
+ *   if operating on repos with aggressive GC or partial clones.
+ */
+export async function getContent(nodeId) {
+  const oid = await getContentOid.call(this, nodeId);
+  if (!oid) {
+    return null;
+  }
+  return await this._persistence.readBlob(oid);
+}
+
+/**
+ * Gets the content blob OID for an edge, or null if none is attached.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string} from - Source node ID
+ * @param {string} to - Target node ID
+ * @param {string} label - Edge label
+ * @returns {Promise<string|null>} Hex blob OID or null
+ * @throws {import('../errors/QueryError.js').default} If no cached state exists (code: `E_NO_STATE`)
+ */
+export async function getEdgeContentOid(from, to, label) {
+  const props = await getEdgeProps.call(this, from, to, label);
+  if (!props) {
+    return null;
+  }
+  // getEdgeProps returns a plain object — use bracket access
+  const oid = props[CONTENT_PROPERTY_KEY];
+  return (typeof oid === 'string') ? oid : null;
+}
+
+/**
+ * Gets the content blob for an edge, or null if none is attached.
+ *
+ * Returns the raw Buffer from `readBlob()`. Consumers wanting text
+ * should call `.toString('utf8')` on the result.
+ *
+ * @this {import('../WarpGraph.js').default}
+ * @param {string} from - Source node ID
+ * @param {string} to - Target node ID
+ * @param {string} label - Edge label
+ * @returns {Promise<Buffer|null>} Content buffer or null
+ * @throws {Error} If the referenced blob OID is not in the object store
+ *   (e.g., garbage-collected despite anchoring). Callers should handle this
+ *   if operating on repos with aggressive GC or partial clones.
+ */
+export async function getEdgeContent(from, to, label) {
+  const oid = await getEdgeContentOid.call(this, from, to, label);
+  if (!oid) {
+    return null;
+  }
+  return await this._persistence.readBlob(oid);
+}

package/src/infrastructure/adapters/GitGraphAdapter.js

@@ -43,6 +43,7 @@
  * @see {@link https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain} for Git plumbing concepts
  */
 
+import { Buffer } from 'node:buffer';
 import { retry } from '@git-stunts/alfred';
 import GraphPersistencePort from '../../ports/GraphPersistencePort.js';
 import { validateOid, validateRef, validateLimit, validateConfigKey } from './adapterValidation.js';
@@ -510,7 +511,9 @@ export default class GitGraphAdapter extends GraphPersistencePort {
     const stream = await this.plumbing.executeStream({
       args: ['cat-file', 'blob', oid]
     });
-    return await stream.collect({ asString: false });
+    const raw = await stream.collect({ asString: false });
+    // Ensure a real Node Buffer (plumbing may return Uint8Array)
+    return Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
   }
 
   /**