@git-stunts/git-warp 10.8.0 → 11.2.1

package/src/domain/trust/schemas.js

@@ -0,0 +1,160 @@
+/**
+ * Trust V1 Zod schemas.
+ *
+ * Schemas for trust record envelope, per-type subjects, policy config,
+ * and assessment output contract. These are the canonical validation
+ * boundary — all trust data passes through these schemas.
+ *
+ * @module domain/trust/schemas
+ * @see docs/specs/TRUST_V1_CRYPTO.md Sections 8–10, 14
+ */
+
+import { z } from 'zod';
+
+// ── Primitives ──────────────────────────────────────────────────────────
+
+export const KeyIdSchema = z.string().regex(
+  /^ed25519:[a-f0-9]{64}$/,
+  'keyId must be "ed25519:" followed by 64 hex chars',
+);
+
+export const RecordIdSchema = z.string().regex(
+  /^[a-f0-9]{64}$/,
+  'recordId must be 64 lowercase hex chars',
+);
+
+export const RecordTypeSchema = z.enum([
+  'KEY_ADD',
+  'KEY_REVOKE',
+  'WRITER_BIND_ADD',
+  'WRITER_BIND_REVOKE',
+]);
+
+// ── Signature ───────────────────────────────────────────────────────────
+
+export const TrustSignatureSchema = z.object({
+  alg: z.literal('ed25519'),
+  sig: z.string().min(1, 'signature must not be empty'),
+});
+
+// ── Per-type subject schemas ────────────────────────────────────────────
+
+export const KeyAddSubjectSchema = z.object({
+  keyId: KeyIdSchema,
+  publicKey: z.string().min(1, 'publicKey must not be empty'),
+});
+
+export const KeyRevokeSubjectSchema = z.object({
+  keyId: KeyIdSchema,
+  reasonCode: z.enum(['KEY_COMPROMISE', 'KEY_ROLLOVER', 'OPERATOR_REQUEST']),
+});
+
+export const WriterBindAddSubjectSchema = z.object({
+  writerId: z.string().trim().min(1),
+  keyId: KeyIdSchema,
+});
+
+export const WriterBindRevokeSubjectSchema = z.object({
+  writerId: z.string().trim().min(1),
+  keyId: KeyIdSchema,
+  reasonCode: z.enum(['ACCESS_REMOVED', 'ROTATION', 'KEY_REVOKED']),
+});
+
+// ── Trust record envelope ───────────────────────────────────────────────
+
+export const TrustRecordSchema = z.object({
+  schemaVersion: z.literal(1),
+  recordType: RecordTypeSchema,
+  recordId: RecordIdSchema,
+  issuerKeyId: KeyIdSchema,
+  issuedAt: z.string().datetime({ offset: false }),
+  prev: RecordIdSchema.nullable(),
+  subject: z.record(z.unknown()),
+  meta: z.record(z.unknown()).optional().default({}),
+  signature: TrustSignatureSchema,
+}).superRefine((record, ctx) => {
+  /** @param {string} message */
+  const addIssue = (message) =>
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message });
+
+  switch (record.recordType) {
+    case 'KEY_ADD': {
+      const r = KeyAddSubjectSchema.safeParse(record.subject);
+      if (!r.success) {
+        addIssue(`Invalid KEY_ADD subject: ${r.error.message}`);
+      } else {
+        record.subject = r.data;
+      }
+      break;
+    }
+    case 'KEY_REVOKE': {
+      const r = KeyRevokeSubjectSchema.safeParse(record.subject);
+      if (!r.success) {
+        addIssue(`Invalid KEY_REVOKE subject: ${r.error.message}`);
+      } else {
+        record.subject = r.data;
+      }
+      break;
+    }
+    case 'WRITER_BIND_ADD': {
+      const r = WriterBindAddSubjectSchema.safeParse(record.subject);
+      if (!r.success) {
+        addIssue(`Invalid WRITER_BIND_ADD subject: ${r.error.message}`);
+      } else {
+        record.subject = r.data;
+      }
+      break;
+    }
+    case 'WRITER_BIND_REVOKE': {
+      const r = WriterBindRevokeSubjectSchema.safeParse(record.subject);
+      if (!r.success) {
+        addIssue(`Invalid WRITER_BIND_REVOKE subject: ${r.error.message}`);
+      } else {
+        record.subject = r.data;
+      }
+      break;
+    }
+    default:
+      addIssue(`Unsupported recordType: ${/** @type {string} */ (record.recordType)}`);
+  }
+});
+
+// ── Policy config ───────────────────────────────────────────────────────
+
+export const TrustPolicySchema = z.object({
+  schemaVersion: z.literal(1),
+  mode: z.enum(['warn', 'enforce']),
+  writerPolicy: z.literal('all_writers_must_be_trusted'),
+});
+
+// ── Assessment output contract ──────────────────────────────────────────
+
+export const TrustExplanationSchema = z.object({
+  writerId: z.string().min(1),
+  trusted: z.boolean(),
+  reasonCode: z.string().min(1),
+  reason: z.string().min(1),
+});
+
+export const EvidenceSummarySchema = z.object({
+  recordsScanned: z.number().int().nonnegative(),
+  activeKeys: z.number().int().nonnegative(),
+  revokedKeys: z.number().int().nonnegative(),
+  activeBindings: z.number().int().nonnegative(),
+  revokedBindings: z.number().int().nonnegative(),
+});
+
+export const TrustAssessmentSchema = z.object({
+  trustSchemaVersion: z.literal(1),
+  mode: z.literal('signed_evidence_v1'),
+  trustVerdict: z.enum(['pass', 'fail', 'not_configured']),
+  trust: z.object({
+    status: z.enum(['configured', 'pinned', 'error', 'not_configured']),
+    source: z.enum(['ref', 'cli_pin', 'env_pin', 'none']),
+    sourceDetail: z.string().nullable(),
+    evaluatedWriters: z.array(z.string()),
+    untrustedWriters: z.array(z.string()),
+    explanations: z.array(TrustExplanationSchema),
+    evidenceSummary: EvidenceSummarySchema,
+  }),
+});

package/src/domain/trust/verdict.js

@@ -0,0 +1,42 @@
+/**
+ * Trust V1 verdict derivation.
+ *
+ * Deterministic mapping from TrustAssessment to verdict string.
+ * This is the single source of truth for verdict logic.
+ *
+ * @module domain/trust/verdict
+ * @see docs/specs/TRUST_V1_CRYPTO.md Section 13
+ */
+
+/**
+ * @typedef {Object} TrustAssessmentV1
+ * @property {'not_configured'|'configured'|'pinned'|'error'} status
+ * @property {string[]} untrustedWriters
+ */
+
+/**
+ * Derives the trust verdict from a V1 trust assessment.
+ *
+ * Mapping (evaluated in order):
+ * - status 'not_configured' → 'not_configured'
+ * - status 'error'          → 'fail'
+ * - untrustedWriters.length > 0 → 'fail'
+ * - otherwise               → 'pass'
+ *
+ * V1 has no 'degraded' verdict — untrusted writers are a hard failure.
+ *
+ * @param {TrustAssessmentV1} trust
+ * @returns {'pass'|'fail'|'not_configured'}
+ */
+export function deriveTrustVerdict(trust) {
+  if (trust.status === 'not_configured') {
+    return 'not_configured';
+  }
+  if (trust.status === 'error') {
+    return 'fail';
+  }
+  if (Array.isArray(trust.untrustedWriters) && trust.untrustedWriters.length > 0) {
+    return 'fail';
+  }
+  return 'pass';
+}

package/src/domain/types/git-cas.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Type stub for @git-stunts/git-cas.
+ *
+ * Provides just enough shape for CasSeekCacheAdapter to typecheck.
+ */
+declare module '@git-stunts/git-cas' {
+  interface CasStore {
+    put(key: string, value: Uint8Array): Promise<string>;
+    get(key: string): Promise<Uint8Array | null>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+  }
+
+  interface ContentAddressableStore {
+    createCbor(opts: { plumbing: unknown }): CasStore;
+  }
+
+  const ContentAddressableStore: ContentAddressableStore;
+  export default ContentAddressableStore;
+}

package/src/domain/utils/RefLayout.js

@@ -10,6 +10,8 @@
  * - refs/warp/<graph>/coverage/head
  * - refs/warp/<graph>/cursor/active
  * - refs/warp/<graph>/cursor/saved/<name>
+ * - refs/warp/<graph>/audit/<writer_id>
+ * - refs/warp/<graph>/trust/records
  *
  * @module domain/utils/RefLayout
  */
@@ -291,6 +293,43 @@ export function buildCursorSavedPrefix(graphName) {
   return `${REF_PREFIX}/${graphName}/cursor/saved/`;
 }
 
+/**
+ * Builds the audit ref path for the given graph and writer ID.
+ *
+ * Audit refs track the latest audit commit for each writer, forming
+ * an independent chain of tamper-evident receipts per writer.
+ *
+ * @param {string} graphName - The name of the graph
+ * @param {string} writerId - The writer's unique identifier
+ * @returns {string} The full ref path, e.g. `refs/warp/<graphName>/audit/<writerId>`
+ * @throws {Error} If graphName or writerId is invalid
+ *
+ * @example
+ * buildAuditRef('events', 'alice');
+ * // => 'refs/warp/events/audit/alice'
+ */
+export function buildAuditRef(graphName, writerId) {
+  validateGraphName(graphName);
+  validateWriterId(writerId);
+  return `${REF_PREFIX}/${graphName}/audit/${writerId}`;
+}
+
+/**
+ * Builds the audit ref prefix for listing all audit writers of a graph.
+ *
+ * @param {string} graphName - The name of the graph
+ * @returns {string} The ref prefix, e.g. `refs/warp/<graphName>/audit/`
+ * @throws {Error} If graphName is invalid
+ *
+ * @example
+ * buildAuditPrefix('events');
+ * // => 'refs/warp/events/audit/'
+ */
+export function buildAuditPrefix(graphName) {
+  validateGraphName(graphName);
+  return `${REF_PREFIX}/${graphName}/audit/`;
+}
+
 /**
  * Builds the seek cache ref path for the given graph.
  *
@@ -310,6 +349,26 @@ export function buildSeekCacheRef(graphName) {
   return `${REF_PREFIX}/${graphName}/seek-cache`;
 }
 
+/**
+ * Builds the trust record chain ref path for the given graph.
+ *
+ * The trust record ref points to the tip commit of the trust record
+ * chain — an append-only sequence of signed trust records (key adds,
+ * key revokes, writer bindings).
+ *
+ * @param {string} graphName - The name of the graph
+ * @returns {string} The full ref path, e.g. `refs/warp/<graphName>/trust/records`
+ * @throws {Error} If graphName is invalid
+ *
+ * @example
+ * buildTrustRecordRef('events');
+ * // => 'refs/warp/events/trust/records'
+ */
+export function buildTrustRecordRef(graphName) {
+  validateGraphName(graphName);
+  return `${REF_PREFIX}/${graphName}/trust/records`;
+}
+
 // -----------------------------------------------------------------------------
 // Parsers
 // -----------------------------------------------------------------------------

package/src/domain/warp/PatchSession.js

@@ -130,6 +130,24 @@ export class PatchSession {
     return this;
   }
 
+  /**
+   * Sets a property on an edge.
+   *
+   * @param {string} from - Source node ID
+   * @param {string} to - Target node ID
+   * @param {string} label - Edge label/type
+   * @param {string} key - Property key
+   * @param {*} value - Property value (must be JSON-serializable)
+   * @returns {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
+  setEdgeProperty(from, to, label, key, value) {
+    this._ensureNotCommitted();
+    this._builder.setEdgeProperty(from, to, label, key, value);
+    return this;
+  }
+
   /**
    * Builds the PatchV2 object without committing.
    *

package/src/domain/warp/Writer.js

@@ -71,6 +71,9 @@ export class Writer {
 
     /** @type {import('../../ports/CodecPort.js').default|undefined} */
     this._codec = codec || defaultCodec;
+
+    /** @type {boolean} */
+    this._commitInProgress = false;
   }
 
   /**
@@ -163,6 +166,7 @@ export class Writer {
    *
    * @param {(p: PatchSession) => void | Promise<void>} build - Function to build the patch
    * @returns {Promise<string>} The commit SHA of the new patch
+   * @throws {WriterError} COMMIT_IN_PROGRESS if called while another commitPatch() is in progress (not reentrant)
    * @throws {WriterError} EMPTY_PATCH if no operations were added
    * @throws {WriterError} WRITER_REF_ADVANCED if CAS fails (ref moved since beginPatch)
    * @throws {WriterError} PERSIST_WRITE_FAILED if git operations fail
@@ -174,8 +178,19 @@ export class Writer {
    * });
    */
   async commitPatch(build) {
-    const patch = await this.beginPatch();
-    await build(patch);
-    return await patch.commit();
+    if (this._commitInProgress) {
+      throw new WriterError(
+        'COMMIT_IN_PROGRESS',
+        'commitPatch() is not reentrant. Use beginPatch() for nested or concurrent patches.',
+      );
+    }
+    this._commitInProgress = true;
+    try {
+      const patch = await this.beginPatch();
+      await build(patch);
+      return await patch.commit();
+    } finally {
+      this._commitInProgress = false;
+    }
   }
 }

package/src/domain/warp/_internal.js

@@ -0,0 +1,26 @@
+/**
+ * Shared constants and re-exports for WarpGraph method files.
+ *
+ * Method files (`*.methods.js`) import from here to avoid
+ * brittle relative paths back into the domain root.
+ *
+ * @module domain/warp/_internal
+ */
+
+// ── Error constructors ──────────────────────────────────────────────────────
+export { default as QueryError } from '../errors/QueryError.js';
+export { default as ForkError } from '../errors/ForkError.js';
+export { default as SyncError } from '../errors/SyncError.js';
+export { default as OperationAbortedError } from '../errors/OperationAbortedError.js';
+
+// ── Shared constants ────────────────────────────────────────────────────────
+export const DEFAULT_ADJACENCY_CACHE_SIZE = 3;
+export const E_NO_STATE_MSG = 'No materialized state. Call materialize() before querying, or use autoMaterialize: true (the default). See https://github.com/git-stunts/git-warp#materialization';
+export const E_STALE_STATE_MSG = 'State is stale (patches written since last materialize). Call materialize() to refresh. See https://github.com/git-stunts/git-warp#materialization';
+
+// ── Sync constants ──────────────────────────────────────────────────────────
+export const DEFAULT_SYNC_SERVER_MAX_BYTES = 4 * 1024 * 1024;
+export const DEFAULT_SYNC_WITH_RETRIES = 3;
+export const DEFAULT_SYNC_WITH_BASE_DELAY_MS = 250;
+export const DEFAULT_SYNC_WITH_MAX_DELAY_MS = 2000;
+export const DEFAULT_SYNC_WITH_TIMEOUT_MS = 10_000;

package/src/domain/warp/_wire.js

@@ -0,0 +1,58 @@
+/**
+ * Prototype wiring helper for WarpGraph method extraction.
+ *
+ * Assigns exported functions from `*.methods.js` modules onto a class
+ * prototype, with duplicate-name detection at import time.
+ *
+ * @module domain/warp/_wire
+ */
+
+/**
+ * Wires exported functions from method modules onto a class prototype.
+ *
+ * Each module is expected to export named functions. The function names
+ * become method names on the prototype. Duplicates across modules are
+ * detected eagerly and throw at import time (not at call time).
+ *
+ * @param {Function} Class - The class constructor whose prototype to extend
+ * @param {Array<Record<string, Function>>} methodModules - Array of method module namespace objects
+ * @throws {Error} If a method name appears in more than one module
+ */
+export function wireWarpMethods(Class, methodModules) {
+  /** @type {Map<string, string>} name → source module index (for error messages) */
+  const seen = new Map();
+  const existing = new Set(Object.getOwnPropertyNames(Class.prototype));
+
+  for (let i = 0; i < methodModules.length; i++) {
+    const mod = methodModules[i];
+    for (const [name, fn] of Object.entries(mod)) {
+      if (typeof fn !== 'function') {
+        continue;
+      }
+
+      if (existing.has(name)) {
+        throw new Error(
+          `wireWarpMethods: method "${name}" already exists on ${Class.name}.prototype — ` +
+          `attempted to overwrite from module index ${i}`
+        );
+      }
+
+      if (seen.has(name)) {
+        throw new Error(
+          `wireWarpMethods: duplicate method "${name}" — ` +
+          `already defined in module index ${seen.get(name)}, ` +
+          `attempted again in module index ${i}`
+        );
+      }
+
+      seen.set(name, String(i));
+
+      Object.defineProperty(Class.prototype, name, {
+        value: fn,
+        writable: true,
+        configurable: true,
+        enumerable: false,
+      });
+    }
+  }
+}

package/src/domain/warp/_wiredMethods.d.ts

@@ -0,0 +1,100 @@
+/**
+ * TypeScript augmentation for WarpGraph wired methods.
+ *
+ * Methods in *.methods.js are wired onto WarpGraph.prototype at runtime
+ * via wireWarpMethods(). This declaration file makes them visible to tsc.
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import type { PatchBuilderV2 } from '../services/PatchBuilderV2.js';
+import type { Writer } from './Writer.js';
+
+export {};
+
+declare module '../WarpGraph.js' {
+  export default interface WarpGraph {
+    // ── query.methods.js ──────────────────────────────────────────────────
+    hasNode(nodeId: string): Promise<boolean>;
+    getNodeProps(nodeId: string): Promise<Map<string, any> | null>;
+    getEdgeProps(from: string, to: string, label: string): Promise<Record<string, any> | null>;
+    neighbors(nodeId: string, direction?: 'outgoing' | 'incoming' | 'both', edgeLabel?: string): Promise<Array<{ nodeId: string; label: string; direction: 'outgoing' | 'incoming' }>>;
+    getStateSnapshot(): Promise<any>;
+    getNodes(): Promise<string[]>;
+    getEdges(): Promise<Array<{ from: string; to: string; label: string; props: Record<string, any> }>>;
+    getPropertyCount(): Promise<number>;
+    query(): any;
+    observer(name: string, config: any): Promise<any>;
+    translationCost(configA: any, configB: any): Promise<{ cost: number; breakdown: { nodeLoss: number; edgeLoss: number; propLoss: number } }>;
+
+    // ── subscribe.methods.js ──────────────────────────────────────────────
+    subscribe(options: { onChange: Function; onError?: Function; replay?: boolean }): { unsubscribe: () => void };
+    watch(pattern: string, options: { onChange: Function; onError?: Function; poll?: number }): { unsubscribe: () => void };
+    _notifySubscribers(diff: any, currentState: any): void;
+
+    // ── provenance.methods.js ─────────────────────────────────────────────
+    patchesFor(entityId: string): Promise<string[]>;
+    materializeSlice(nodeId: string, options?: any): Promise<any>;
+    _computeBackwardCone(nodeId: string): Promise<Map<string, any>>;
+    loadPatchBySha(sha: string): Promise<any>;
+    _loadPatchBySha(sha: string): Promise<any>;
+    _loadPatchesBySha(shas: string[]): Promise<Array<{ patch: any; sha: string }>>;
+    _sortPatchesCausally(patches: any[]): any[];
+
+    // ── fork.methods.js ───────────────────────────────────────────────────
+    fork(options: { from: string; at: string; forkName?: string; forkWriterId?: string }): Promise<WarpGraph>;
+    createWormhole(fromSha: string, toSha: string): Promise<{ fromSha: string; toSha: string; writerId: string; payload: any; patchCount: number }>;
+    _isAncestor(ancestorSha: string, descendantSha: string): Promise<boolean>;
+    _relationToCheckpointHead(ckHead: string, incomingSha: string): Promise<string>;
+    _validatePatchAgainstCheckpoint(writerId: string, incomingSha: string, checkpoint: any): Promise<void>;
+
+    // ── sync.methods.js ───────────────────────────────────────────────────
+    getFrontier(): Promise<Map<string, string>>;
+    hasFrontierChanged(): Promise<boolean>;
+    status(): Promise<any>;
+    createSyncRequest(): Promise<any>;
+    processSyncRequest(request: any): Promise<any>;
+    applySyncResponse(response: any): any;
+    syncNeeded(remoteFrontier: any): Promise<boolean>;
+    syncWith(remote: any, options?: any): Promise<any>;
+    serve(options?: any): Promise<any>;
+
+    // ── checkpoint.methods.js ─────────────────────────────────────────────
+    createCheckpoint(): Promise<string>;
+    syncCoverage(): Promise<void>;
+    _loadLatestCheckpoint(): Promise<any>;
+    _loadPatchesSince(checkpoint: any): Promise<any[]>;
+    _validateMigrationBoundary(): Promise<void>;
+    _hasSchema1Patches(): Promise<boolean>;
+    _maybeRunGC(state: any): any;
+    maybeRunGC(): any;
+    runGC(): any;
+    getGCMetrics(): any;
+
+    // ── patch.methods.js ──────────────────────────────────────────────────
+    createPatch(): Promise<PatchBuilderV2>;
+    patch(build: (p: PatchBuilderV2) => void | Promise<void>): Promise<string>;
+    _nextLamport(): Promise<{ lamport: number; parentSha: string | null }>;
+    _loadWriterPatches(writerId: string, stopAtSha?: string | null): Promise<Array<{ patch: import('../types/WarpTypesV2.js').PatchV2; sha: string }>>;
+    getWriterPatches(writerId: string, stopAtSha?: string | null): Promise<Array<{ patch: import('../types/WarpTypesV2.js').PatchV2; sha: string }>>;
+    _onPatchCommitted(writerId: string, opts?: { patch?: any; sha?: string }): Promise<void>;
+    writer(writerId?: string): Promise<Writer>;
+    createWriter(opts?: any): Promise<Writer>;
+    _ensureFreshState(): Promise<void>;
+    discoverWriters(): Promise<string[]>;
+    discoverTicks(): Promise<{ ticks: number[]; maxTick: number; perWriter: Map<string, { ticks: number[]; tipSha: string | null; tickShas: Record<number, string> }> }>;
+    join(otherState: any): any;
+    _frontierEquals(a: any, b: any): boolean;
+
+    // ── materialize.methods.js ────────────────────────────────────────────
+    materialize(options?: any): Promise<any>;
+    _materializeGraph(): Promise<any>;
+
+    // ── materializeAdvanced.methods.js ────────────────────────────────────
+    _resolveCeiling(options: any): any;
+    _buildAdjacency(state: any): any;
+    _setMaterializedState(state: any): Promise<{ state: any; stateHash: string; adjacency: any }>;
+    _materializeWithCeiling(ceiling: any, collectReceipts: boolean, t0: number): Promise<any>;
+    materializeAt(checkpointSha: string): Promise<any>;
+  }
+}