@git-stunts/git-warp 10.8.0 → 11.3.3

package/src/domain/crdt/ORSet.js

@@ -91,7 +91,7 @@ import { vvContains } from './VersionVector.js';
  * An element is present if it has at least one non-tombstoned dot.
  *
  * @typedef {Object} ORSet
- * @property {Map<*, Set<string>>} entries - element -> dots that added it
+ * @property {Map<string, Set<string>>} entries - element -> dots that added it
  * @property {Set<string>} tombstones - global tombstones
  */
 
@@ -112,7 +112,7 @@ export function createORSet() {
  * Mutates the set.
  *
  * @param {ORSet} set - The ORSet to mutate
- * @param {*} element - The element to add
+ * @param {string} element - The element to add
  * @param {import('./Dot.js').Dot} dot - The dot representing this add operation
  */
 export function orsetAdd(set, element, dot) {
@@ -145,7 +145,7 @@ export function orsetRemove(set, observedDots) {
  * An element is present if it has at least one non-tombstoned dot.
  *
  * @param {ORSet} set - The ORSet to check
- * @param {*} element - The element to check
+ * @param {string} element - The element to check
  * @returns {boolean}
  */
 export function orsetContains(set, element) {
@@ -168,7 +168,7 @@ export function orsetContains(set, element) {
  * Only returns elements that have at least one non-tombstoned dot.
  *
  * @param {ORSet} set - The ORSet
- * @returns {Array<*>} Array of present elements
+ * @returns {string[]} Array of present elements
  */
 export function orsetElements(set) {
   const result = [];
@@ -186,7 +186,7 @@ export function orsetElements(set) {
  * Returns the non-tombstoned dots for an element.
  *
  * @param {ORSet} set - The ORSet
- * @param {*} element - The element
+ * @param {string} element - The element
  * @returns {Set<string>} Set of encoded dots that are not tombstoned
  */
 export function orsetGetDots(set, element) {
@@ -311,11 +311,11 @@ export function orsetCompact(set, includedVV) {
  * Tombstones are sorted.
  *
  * @param {ORSet} set
- * @returns {{entries: Array<[*, string[]]>, tombstones: string[]}}
+ * @returns {{entries: Array<[string, string[]]>, tombstones: string[]}}
  */
 export function orsetSerialize(set) {
   // Serialize entries: convert Map to array of [element, sortedDots]
-  /** @type {Array<[any, string[]]>} */
+  /** @type {Array<[string, string[]]>} */
   const entriesArray = [];
   for (const [element, dots] of set.entries) {
     const sortedDots = [...dots].sort((a, b) => {
@@ -349,7 +349,7 @@ export function orsetSerialize(set) {
 /**
  * Deserializes a plain object back to an ORSet.
  *
- * @param {{entries?: Array<[*, string[]]>, tombstones?: string[]}} obj
+ * @param {{entries?: Array<[string, string[]]>, tombstones?: string[]}} obj
  * @returns {ORSet}
  */
 export function orsetDeserialize(obj) {

package/src/domain/errors/EmptyMessageError.js

@@ -12,7 +12,7 @@ import IndexError from './IndexError.js';
  * @property {string} name - The error name ('EmptyMessageError')
  * @property {string} code - Error code ('EMPTY_MESSAGE')
  * @property {string} operation - The operation that failed due to empty message
- * @property {Record<string, *>} context - Serializable context object for debugging
+ * @property {Record<string, unknown>} context - Serializable context object for debugging
  *
  * @example
  * if (!message || message.trim() === '') {
@@ -27,7 +27,7 @@ export default class EmptyMessageError extends IndexError {
    * Creates a new EmptyMessageError.
    *
    * @param {string} message - Human-readable error message
-   * @param {{ operation?: string, context?: Record<string, *> }} [options={}] - Error options
+   * @param {{ operation?: string, context?: Record<string, unknown> }} [options={}] - Error options
    */
   constructor(message, options = {}) {
     const context = {

package/src/domain/errors/ForkError.js

@@ -26,7 +26,7 @@ import WarpError from './WarpError.js';
 export default class ForkError extends WarpError {
   /**
    * @param {string} message
-   * @param {{ code?: string, context?: Object }} [options={}]
+   * @param {{ code?: string, context?: Record<string, unknown> }} [options={}]
    */
   constructor(message, options = {}) {
     super(message, 'FORK_ERROR', options);

package/src/domain/errors/IndexError.js

@@ -19,7 +19,7 @@ import WarpError from './WarpError.js';
 export default class IndexError extends WarpError {
   /**
    * @param {string} message
-   * @param {{ code?: string, context?: Object }} [options={}]
+   * @param {{ code?: string, context?: Record<string, unknown> }} [options={}]
    */
   constructor(message, options = {}) {
     super(message, 'INDEX_ERROR', options);

package/src/domain/errors/OperationAbortedError.js

@@ -15,7 +15,7 @@ import WarpError from './WarpError.js';
 export default class OperationAbortedError extends WarpError {
   /**
    * @param {string} operation
-   * @param {{ code?: string, context?: Object, reason?: string }} [options={}]
+   * @param {{ code?: string, context?: Record<string, unknown>, reason?: string }} [options={}]
    */
   constructor(operation, options = {}) {
     const reason = options.reason || 'Operation was aborted';

package/src/domain/errors/QueryError.js

@@ -11,8 +11,8 @@ import WarpError from './WarpError.js';
  *
  * | Code | Description |
  * |------|-------------|
- * | `E_NO_STATE` | No cached state available; call `materialize()` first |
- * | `E_STALE_STATE` | Cached state is outdated; call `materialize()` to refresh |
+ * | `E_NO_STATE` | No materialized state available; call `materialize()` or use `autoMaterialize: true` |
+ * | `E_STALE_STATE` | State is stale; call `materialize()` to refresh |
  * | `E_QUERY_MATCH_TYPE` | Invalid type passed to `match()` (expected string) |
  * | `E_QUERY_WHERE_TYPE` | Invalid type passed to `where()` (expected function or object) |
  * | `E_QUERY_WHERE_VALUE` | Non-primitive value in where() object shorthand |
@@ -35,7 +35,7 @@ import WarpError from './WarpError.js';
 export default class QueryError extends WarpError {
   /**
    * @param {string} message
-   * @param {{ code?: string, context?: Object }} [options={}]
+   * @param {{ code?: string, context?: Record<string, unknown> }} [options={}]
    */
   constructor(message, options = {}) {
     super(message, 'QUERY_ERROR', options);

package/src/domain/errors/SchemaUnsupportedError.js

@@ -13,7 +13,7 @@ import WarpError from './WarpError.js';
 export default class SchemaUnsupportedError extends WarpError {
   /**
    * @param {string} message
-   * @param {{ code?: string, context?: Object }} [options={}]
+   * @param {{ code?: string, context?: Record<string, unknown> }} [options={}]
    */
   constructor(message, options = {}) {
     super(message, 'E_SCHEMA_UNSUPPORTED', options);

package/src/domain/errors/ShardCorruptionError.js

@@ -14,7 +14,7 @@ import IndexError from './IndexError.js';
  * @property {string} shardPath - Path to the corrupted shard file
  * @property {string} oid - Object ID associated with the shard
  * @property {string} reason - Reason for corruption (e.g., 'invalid_checksum', 'invalid_version', 'parse_error')
- * @property {Record<string, *>} context - Serializable context object for debugging
+ * @property {Record<string, unknown>} context - Serializable context object for debugging
  *
  * @example
  * if (!validateChecksum(data)) {
@@ -30,7 +30,7 @@ export default class ShardCorruptionError extends IndexError {
    * Creates a new ShardCorruptionError.
    *
    * @param {string} message - Human-readable error message
-   * @param {{ shardPath?: string, oid?: string, reason?: string, context?: Record<string, *> }} [options={}] - Error options
+   * @param {{ shardPath?: string, oid?: string, reason?: string, context?: Record<string, unknown> }} [options={}] - Error options
    */
   constructor(message, options = {}) {
     const context = {

package/src/domain/errors/ShardLoadError.js

@@ -14,7 +14,7 @@ import IndexError from './IndexError.js';
  * @property {string} shardPath - Path to the shard file that failed to load
  * @property {string} oid - Object ID associated with the shard
  * @property {Error} cause - The original error that caused the load failure
- * @property {Record<string, *>} context - Serializable context object for debugging
+ * @property {Record<string, unknown>} context - Serializable context object for debugging
  *
  * @example
  * try {
@@ -32,7 +32,7 @@ export default class ShardLoadError extends IndexError {
    * Creates a new ShardLoadError.
    *
    * @param {string} message - Human-readable error message
-   * @param {{ shardPath?: string, oid?: string, cause?: Error, context?: Record<string, *> }} [options={}] - Error options
+   * @param {{ shardPath?: string, oid?: string, cause?: Error, context?: Record<string, unknown> }} [options={}] - Error options
    */
   constructor(message, options = {}) {
     const context = {

package/src/domain/errors/ShardValidationError.js

@@ -12,10 +12,10 @@ import IndexError from './IndexError.js';
  * @property {string} name - The error name ('ShardValidationError')
  * @property {string} code - Error code ('SHARD_VALIDATION_ERROR')
  * @property {string} shardPath - Path to the shard file that failed validation
- * @property {*} expected - The expected value for the field
- * @property {*} actual - The actual value found in the shard
+ * @property {unknown} expected - The expected value for the field
+ * @property {unknown} actual - The actual value found in the shard
  * @property {string} field - The field that failed validation (e.g., 'checksum', 'version')
- * @property {Record<string, *>} context - Serializable context object for debugging
+ * @property {Record<string, unknown>} context - Serializable context object for debugging
  *
  * @example
  * if (shard.version !== EXPECTED_VERSION) {
@@ -32,7 +32,7 @@ export default class ShardValidationError extends IndexError {
    * Creates a new ShardValidationError.
    *
    * @param {string} message - Human-readable error message
-   * @param {{ shardPath?: string, expected?: *, actual?: *, field?: string, context?: Record<string, *> }} [options={}] - Error options
+   * @param {{ shardPath?: string, expected?: unknown, actual?: unknown, field?: string, context?: Record<string, unknown> }} [options={}] - Error options
    */
   constructor(message, options = {}) {
     const context = {

package/src/domain/errors/StorageError.js

@@ -14,7 +14,7 @@ import IndexError from './IndexError.js';
  * @property {string} operation - The operation that failed ('read' or 'write')
  * @property {string} oid - Object ID associated with the operation
  * @property {Error} cause - The original error that caused the failure
- * @property {Record<string, *>} context - Serializable context object for debugging
+ * @property {Record<string, unknown>} context - Serializable context object for debugging
  *
  * @example
  * try {
@@ -32,7 +32,7 @@ export default class StorageError extends IndexError {
    * Creates a new StorageError.
    *
    * @param {string} message - Human-readable error message
-   * @param {{ operation?: string, oid?: string, cause?: Error, context?: Record<string, *> }} [options={}] - Error options
+   * @param {{ operation?: string, oid?: string, cause?: Error, context?: Record<string, unknown> }} [options={}] - Error options
    */
   constructor(message, options = {}) {
     const context = {

package/src/domain/errors/SyncError.js

@@ -26,7 +26,7 @@ import WarpError from './WarpError.js';
 export default class SyncError extends WarpError {
   /**
    * @param {string} message
-   * @param {{ code?: string, context?: Object }} [options={}]
+   * @param {{ code?: string, context?: Record<string, unknown> }} [options={}]
    */
   constructor(message, options = {}) {
     super(message, 'SYNC_ERROR', options);

package/src/domain/errors/TraversalError.js

@@ -19,7 +19,7 @@ import WarpError from './WarpError.js';
 export default class TraversalError extends WarpError {
   /**
    * @param {string} message
-   * @param {{ code?: string, context?: Object }} [options={}]
+   * @param {{ code?: string, context?: Record<string, unknown> }} [options={}]
    */
   constructor(message, options = {}) {
     super(message, 'TRAVERSAL_ERROR', options);

package/src/domain/errors/TrustError.js

@@ -0,0 +1,29 @@
+import WarpError from './WarpError.js';
+
+/**
+ * Error class for trust operations.
+ *
+ * ## Error Codes
+ *
+ * | Code | Description |
+ * |------|-------------|
+ * | `E_TRUST_UNSUPPORTED_ALGORITHM` | Algorithm is not `ed25519` |
+ * | `E_TRUST_INVALID_KEY` | Public key is malformed (wrong length or bad base64) |
+ * | `TRUST_ERROR` | Generic/default trust error |
+ *
+ * @class TrustError
+ * @extends WarpError
+ *
+ * @property {string} name - Always 'TrustError' for instanceof checks
+ * @property {string} code - Machine-readable error code for programmatic handling
+ * @property {Object} context - Serializable context object with error details
+ */
+export default class TrustError extends WarpError {
+  /**
+   * @param {string} message
+   * @param {{ code?: string, context?: Record<string, unknown> }} [options={}]
+   */
+  constructor(message, options = {}) {
+    super(message, 'TRUST_ERROR', options);
+  }
+}

package/src/domain/errors/WarpError.js

@@ -10,13 +10,13 @@
  *
  * @property {string} name - Error name (set from constructor.name)
  * @property {string} code - Machine-readable error code
- * @property {Record<string, *>} context - Serializable context for debugging
+ * @property {Record<string, unknown>} context - Serializable context for debugging
  */
 export default class WarpError extends Error {
   /**
    * @param {string} message - Human-readable error message
    * @param {string} defaultCode - Default error code if not overridden by options
-   * @param {{ code?: string, context?: Record<string, *> }} [options={}] - Error options
+   * @param {{ code?: string, context?: Record<string, unknown> }} [options={}] - Error options
    */
   constructor(message, defaultCode, options = {}) {
     super(message);

package/src/domain/errors/WormholeError.js

@@ -24,7 +24,7 @@ import WarpError from './WarpError.js';
 export default class WormholeError extends WarpError {
   /**
    * @param {string} message
-   * @param {{ code?: string, context?: Object }} [options={}]
+   * @param {{ code?: string, context?: Record<string, unknown> }} [options={}]
    */
   constructor(message, options = {}) {
     super(message, 'WORMHOLE_ERROR', options);

package/src/domain/errors/index.js

@@ -17,5 +17,6 @@ export { default as ShardValidationError } from './ShardValidationError.js';
 export { default as StorageError } from './StorageError.js';
 export { default as SchemaUnsupportedError } from './SchemaUnsupportedError.js';
 export { default as TraversalError } from './TraversalError.js';
+export { default as TrustError } from './TrustError.js';
 export { default as WriterError } from './WriterError.js';
 export { default as WormholeError } from './WormholeError.js';

package/src/domain/services/AuditMessageCodec.js

@@ -0,0 +1,137 @@
+/**
+ * Audit message encoding and decoding for WARP audit commit messages.
+ *
+ * Handles the 'audit' message type which records the outcome of materializing
+ * a data commit. See {@link module:domain/services/WarpMessageCodec} for the
+ * facade that re-exports all codec functions.
+ *
+ * @module domain/services/AuditMessageCodec
+ */
+
+import { validateGraphName, validateWriterId } from '../utils/RefLayout.js';
+import {
+  getCodec,
+  MESSAGE_TITLES,
+  TRAILER_KEYS,
+  validateOid,
+  validateSha256,
+} from './MessageCodecInternal.js';
+
+// -----------------------------------------------------------------------------
+// Encoder
+// -----------------------------------------------------------------------------
+
+/**
+ * Encodes an audit commit message with trailers.
+ *
+ * @param {Object} options
+ * @param {string} options.graph - The graph name
+ * @param {string} options.writer - The writer ID
+ * @param {string} options.dataCommit - The OID of the data commit being audited
+ * @param {string} options.opsDigest - SHA-256 hex digest of the canonical ops JSON
+ * @returns {string} The encoded commit message
+ * @throws {Error} If any validation fails
+ */
+export function encodeAuditMessage({ graph, writer, dataCommit, opsDigest }) {
+  validateGraphName(graph);
+  validateWriterId(writer);
+  validateOid(dataCommit, 'dataCommit');
+  validateSha256(opsDigest, 'opsDigest');
+
+  const codec = getCodec();
+  return codec.encode({
+    title: MESSAGE_TITLES.audit,
+    trailers: {
+      [TRAILER_KEYS.dataCommit]: dataCommit,
+      [TRAILER_KEYS.graph]: graph,
+      [TRAILER_KEYS.kind]: 'audit',
+      [TRAILER_KEYS.opsDigest]: opsDigest,
+      [TRAILER_KEYS.schema]: '1',
+      [TRAILER_KEYS.writer]: writer,
+    },
+  });
+}
+
+// -----------------------------------------------------------------------------
+// Decoder
+// -----------------------------------------------------------------------------
+
+/**
+ * Decodes an audit commit message.
+ *
+ * @param {string} message - The raw commit message
+ * @returns {{ kind: 'audit', graph: string, writer: string, dataCommit: string, opsDigest: string, schema: number }}
+ * @throws {Error} If the message is not a valid audit message
+ */
+export function decodeAuditMessage(message) {
+  const codec = getCodec();
+  const decoded = codec.decode(message);
+  const { trailers } = decoded;
+
+  // Check for duplicate trailers (strict decode)
+  const keys = Object.keys(trailers);
+  const seen = new Set();
+  for (const key of keys) {
+    if (seen.has(key)) {
+      throw new Error(`Duplicate trailer rejected: ${key}`);
+    }
+    seen.add(key);
+  }
+
+  // Validate kind discriminator
+  const kind = trailers[TRAILER_KEYS.kind];
+  if (kind !== 'audit') {
+    throw new Error(`Invalid audit message: eg-kind must be 'audit', got '${kind}'`);
+  }
+
+  // Extract and validate required fields
+  const graph = trailers[TRAILER_KEYS.graph];
+  if (!graph) {
+    throw new Error('Invalid audit message: missing required trailer eg-graph');
+  }
+  validateGraphName(graph);
+
+  const writer = trailers[TRAILER_KEYS.writer];
+  if (!writer) {
+    throw new Error('Invalid audit message: missing required trailer eg-writer');
+  }
+  validateWriterId(writer);
+
+  const dataCommit = trailers[TRAILER_KEYS.dataCommit];
+  if (!dataCommit) {
+    throw new Error('Invalid audit message: missing required trailer eg-data-commit');
+  }
+  validateOid(dataCommit, 'dataCommit');
+
+  const opsDigest = trailers[TRAILER_KEYS.opsDigest];
+  if (!opsDigest) {
+    throw new Error('Invalid audit message: missing required trailer eg-ops-digest');
+  }
+  validateSha256(opsDigest, 'opsDigest');
+
+  const schemaStr = trailers[TRAILER_KEYS.schema];
+  if (!schemaStr) {
+    throw new Error('Invalid audit message: missing required trailer eg-schema');
+  }
+  if (!/^\d+$/.test(schemaStr)) {
+    throw new Error(
+      `Invalid audit message: eg-schema must be a positive integer, got '${schemaStr}'`,
+    );
+  }
+  const schema = Number(schemaStr);
+  if (!Number.isInteger(schema) || schema < 1) {
+    throw new Error(`Invalid audit message: eg-schema must be a positive integer, got '${schemaStr}'`);
+  }
+  if (schema > 1) {
+    throw new Error(`Unsupported audit schema version: ${schema}`);
+  }
+
+  return {
+    kind: 'audit',
+    graph,
+    writer,
+    dataCommit,
+    opsDigest,
+    schema,
+  };
+}