@git-stunts/git-warp 10.8.0 → 11.3.3

package/src/domain/services/PatchBuilderV2.js

@@ -24,7 +24,7 @@ import {
   createPatchV2,
 } from '../types/WarpTypesV2.js';
 import { encodeEdgeKey, EDGE_PROP_PREFIX } from './KeyCodec.js';
-import { encodePatchMessage, decodePatchMessage } from './WarpMessageCodec.js';
+import { encodePatchMessage, decodePatchMessage, detectMessageKind } from './WarpMessageCodec.js';
 import { buildWriterRef } from '../utils/RefLayout.js';
 import WriterError from '../errors/WriterError.js';
 
@@ -86,7 +86,7 @@ export class PatchBuilderV2 {
    */
   constructor({ persistence, graphName, writerId, lamport, versionVector, getCurrentState, expectedParentSha = null, onCommitSuccess = null, onDeleteWithData = 'warn', codec, logger }) {
     /** @type {import('../../ports/GraphPersistencePort.js').default & import('../../ports/RefPort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default} */
-    this._persistence = /** @type {*} */ (persistence); // TODO(ts-cleanup): narrow port type
+    this._persistence = /** @type {import('../../ports/GraphPersistencePort.js').default & import('../../ports/RefPort.js').default & import('../../ports/CommitPort.js').default & import('../../ports/BlobPort.js').default & import('../../ports/TreePort.js').default} */ (persistence);
 
     /** @type {string} */
     this._graphName = graphName;
@@ -346,7 +346,7 @@ export class PatchBuilderV2 {
    *
    * @param {string} nodeId - The node ID to set the property on
    * @param {string} key - Property key (should not contain null bytes)
-   * @param {*} value - Property value. Must be JSON-serializable (strings,
+   * @param {unknown} value - Property value. Must be JSON-serializable (strings,
    *   numbers, booleans, arrays, plain objects, or null). Use `null` to
    *   effectively delete a property (LWW semantics).
    * @returns {PatchBuilderV2} This builder instance for method chaining
@@ -389,7 +389,7 @@ export class PatchBuilderV2 {
    * @param {string} to - Target node ID (edge destination)
    * @param {string} label - Edge label/type identifying which edge to modify
    * @param {string} key - Property key (should not contain null bytes)
-   * @param {*} value - Property value. Must be JSON-serializable (strings,
+   * @param {unknown} value - Property value. Must be JSON-serializable (strings,
    *   numbers, booleans, arrays, plain objects, or null). Use `null` to
    *   effectively delete a property (LWW semantics).
    * @returns {PatchBuilderV2} This builder instance for method chaining
@@ -454,7 +454,7 @@ export class PatchBuilderV2 {
       schema,
       writer: this._writerId,
       lamport: this._lamport,
-      context: /** @type {*} */ (this._vv), // TODO(ts-cleanup): narrow port type
+      context: vvSerialize(this._vv),
       ops: this._ops,
       reads: [...this._reads].sort(),
       writes: [...this._writes].sort(),
@@ -468,11 +468,12 @@ export class PatchBuilderV2 {
    * 1. Validates the patch is non-empty
    * 2. Checks for concurrent modifications (compare-and-swap on writer ref)
    * 3. Calculates the next lamport timestamp from the parent commit
-   * 4. Encodes the patch as CBOR and writes it as a Git blob
-   * 5. Creates a Git tree containing the patch blob
-   * 6. Creates a commit with proper trailers linking to the parent
-   * 7. Updates the writer ref to point to the new commit
-   * 8. Invokes the success callback if provided (for eager re-materialization)
+   * 4. Builds the PatchV2 structure with the resolved lamport
+   * 5. Encodes the patch as CBOR and writes it as a Git blob
+   * 6. Creates a Git tree containing the patch blob
+   * 7. Creates a commit with proper trailers linking to the parent
+   * 8. Updates the writer ref to point to the new commit
+   * 9. Invokes the success callback if provided (for eager re-materialization)
    *
    * The commit is written to the writer's patch chain at:
    * `refs/warp/<graphName>/writers/<writerId>`
@@ -524,19 +525,39 @@ export class PatchBuilderV2 {
       throw err;
     }
 
-    // 3. Calculate lamport and parent from current ref state
-    let lamport = 1;
+    // 3. Calculate lamport and parent from current ref state.
+    // Start from this._lamport (set by _nextLamport() in createPatch()), which already
+    // incorporates the globally-observed max Lamport tick via _maxObservedLamport.
+    // This ensures a first-time writer whose own chain is empty still commits at a tick
+    // above any previously-observed writer, winning LWW tiebreakers correctly.
+    let lamport = this._lamport;
     let parentCommit = null;
 
     if (currentRefSha) {
-      // Read the current patch commit to get its lamport timestamp
-      const commitMessage = await this._persistence.showNode(currentRefSha);
-      const patchInfo = decodePatchMessage(commitMessage);
-      lamport = patchInfo.lamport + 1;
       parentCommit = currentRefSha;
+      // Read the current patch commit to get its lamport timestamp and take the max,
+      // so the chain stays monotonic even if the ref advanced since createPatch().
+      const commitMessage = await this._persistence.showNode(currentRefSha);
+      const kind = detectMessageKind(commitMessage);
+
+      if (kind === 'patch') {
+        let patchInfo;
+        try {
+          patchInfo = decodePatchMessage(commitMessage);
+        } catch (err) {
+          throw new Error(
+            `Failed to parse lamport from writer ref ${writerRef}: ` +
+            `commit ${currentRefSha} has invalid patch message format`,
+            { cause: err }
+          );
+        }
+        lamport = Math.max(this._lamport, patchInfo.lamport + 1);
+      }
+      // Non-patch ref (checkpoint, etc.): keep lamport from this._lamport
+      // (already incorporates _maxObservedLamport), matching _nextLamport() behavior.
     }
 
-    // 3. Build PatchV2 structure with correct lamport
+    // 4. Build PatchV2 structure with correct lamport
     // Note: Dots were assigned using constructor lamport, but commit lamport may differ.
     // For now, we use the calculated lamport for the patch metadata.
     // The dots themselves are independent of patch lamport (they use VV counters).
@@ -552,10 +573,8 @@ export class PatchBuilderV2 {
       writes: [...this._writes].sort(),
     });
 
-    // 4. Encode patch as CBOR
+    // 5. Encode patch as CBOR and write as a Git blob
     const patchCbor = this._codec.encode(patch);
-
-    // 5. Write patch.cbor blob
     const patchBlobOid = await this._persistence.writeBlob(/** @type {Buffer} */ (patchCbor));
 
     // 6. Create tree with the blob
@@ -563,7 +582,7 @@ export class PatchBuilderV2 {
     const treeEntry = `100644 blob ${patchBlobOid}\tpatch.cbor`;
     const treeOid = await this._persistence.writeTree([treeEntry]);
 
-    // 7. Create patch commit message with trailers (schema:2)
+    // 7. Create commit with proper trailers linking to the parent
     const commitMessage = encodePatchMessage({
       graph: this._graphName,
       writer: this._writerId,
@@ -571,8 +590,6 @@ export class PatchBuilderV2 {
       patchOid: patchBlobOid,
       schema,
     });
-
-    // 8. Create commit with tree, linking to previous patch as parent if exists
     const parents = parentCommit ? [parentCommit] : [];
     const newCommitSha = await this._persistence.commitNodeWithTree({
       treeOid,
@@ -580,10 +597,10 @@ export class PatchBuilderV2 {
       message: commitMessage,
     });
 
-    // 9. Update writer ref to point to new commit
+    // 8. Update writer ref to point to new commit
     await this._persistence.updateRef(writerRef, newCommitSha);
 
-    // 10. Notify success callback (updates graph's version vector + eager re-materialize)
+    // 9. Notify success callback (updates graph's version vector + eager re-materialize)
     if (this._onCommitSuccess) {
       try {
         await this._onCommitSuccess({ patch, sha: newCommitSha });
@@ -593,7 +610,6 @@ export class PatchBuilderV2 {
       }
     }
 
-    // 11. Return the new commit SHA
     return newCommitSha;
   }
 

package/src/domain/services/ProvenanceIndex.js

@@ -277,7 +277,7 @@ class ProvenanceIndex {
   static deserialize(buffer, { codec } = {}) {
     const c = codec || defaultCodec;
     /** @type {{ version?: number, entries?: Array<[string, string[]]> }} */
-    const obj = /** @type {any} */ (c.decode(buffer)); // TODO(ts-cleanup): narrow port type
+    const obj = /** @type {{ version?: number, entries?: Array<[string, string[]]> }} */ (c.decode(buffer));
 
     if (obj.version !== 1) {
       throw new Error(`Unsupported ProvenanceIndex version: ${obj.version}`);

package/src/domain/services/ProvenancePayload.js

@@ -172,7 +172,7 @@ class ProvenancePayload {
     // Use JoinReducer's reduceV5 for deterministic materialization.
     // Note: reduceV5 returns { state, receipts } when options.receipts is truthy,
     // but returns bare WarpStateV5 when no options passed (as here).
-    return /** @type {import('./JoinReducer.js').WarpStateV5} */ (reduceV5(/** @type {*} */ (this.#patches), initialState)); // TODO(ts-cleanup): type patch array
+    return /** @type {import('./JoinReducer.js').WarpStateV5} */ (reduceV5(/** @type {Parameters<typeof reduceV5>[0]} */ ([...this.#patches]), initialState));
   }
 
   /**

package/src/domain/services/QueryBuilder.js

@@ -675,7 +675,7 @@ export default class QueryBuilder {
    * @throws {QueryError} If an unknown select field is specified (code: E_QUERY_SELECT_FIELD)
    */
   async run() {
-    const materialized = await /** @type {any} */ (this._graph)._materializeGraph(); // TODO(ts-cleanup): narrow port type
+    const materialized = await /** @type {{ _materializeGraph: () => Promise<{adjacency: AdjacencyMaps, stateHash: string}> }} */ (this._graph)._materializeGraph();
     const { adjacency, stateHash } = materialized;
     const allNodes = sortIds(await this._graph.getNodes());
 
@@ -805,11 +805,11 @@ export default class QueryBuilder {
       for (const nodeId of workingSet) {
         const propsMap = (await this._graph.getNodeProps(nodeId)) || new Map();
         for (const { segments, values } of propsByAgg.values()) {
-          /** @type {*} */ // TODO(ts-cleanup): type deep property traversal
+          /** @type {unknown} */
           let value = propsMap.get(segments[0]);
           for (let i = 1; i < segments.length; i++) {
             if (value && typeof value === 'object') {
-              value = value[segments[i]];
+              value = /** @type {Record<string, unknown>} */ (value)[segments[i]];
             } else {
               value = undefined;
               break;

package/src/domain/services/StateDiff.js

@@ -24,8 +24,8 @@ import { decodeEdgeKey, decodePropKey, isEdgePropKey } from './KeyCodec.js';
  * @property {string} key - Encoded property key
  * @property {string} nodeId - Node ID (for node props)
  * @property {string} propKey - Property name
- * @property {*} oldValue - Previous value (undefined if new)
- * @property {*} newValue - New value
+ * @property {unknown} oldValue - Previous value (undefined if new)
+ * @property {unknown} newValue - New value
  */
 
 /**
@@ -33,7 +33,7 @@ import { decodeEdgeKey, decodePropKey, isEdgePropKey } from './KeyCodec.js';
  * @property {string} key - Encoded property key
  * @property {string} nodeId - Node ID (for node props)
  * @property {string} propKey - Property name
- * @property {*} oldValue - Previous value
+ * @property {unknown} oldValue - Previous value
  */
 
 /**
@@ -86,8 +86,8 @@ function compareProps(a, b) {
 
 /**
  * Checks if two arrays are deeply equal.
- * @param {Array<*>} a
- * @param {Array<*>} b
+ * @param {Array<unknown>} a
+ * @param {Array<unknown>} b
  * @returns {boolean}
  */
 function arraysEqual(a, b) {
@@ -104,8 +104,8 @@ function arraysEqual(a, b) {
 
 /**
  * Checks if two objects are deeply equal.
- * @param {Record<string, *>} a
- * @param {Record<string, *>} b
+ * @param {Record<string, unknown>} a
+ * @param {Record<string, unknown>} b
  * @returns {boolean}
  */
 function objectsEqual(a, b) {
@@ -127,8 +127,8 @@ function objectsEqual(a, b) {
 
 /**
  * Checks if two values are deeply equal (for property comparison).
- * @param {*} a
- * @param {*} b
+ * @param {unknown} a
+ * @param {unknown} b
  * @returns {boolean}
  */
 function deepEqual(a, b) {
@@ -148,9 +148,12 @@ function deepEqual(a, b) {
     return false;
   }
   if (Array.isArray(a)) {
-    return arraysEqual(a, b);
+    return arraysEqual(a, /** @type {unknown[]} */ (b));
   }
-  return objectsEqual(a, b);
+  return objectsEqual(
+    /** @type {Record<string, unknown>} */ (a),
+    /** @type {Record<string, unknown>} */ (b),
+  );
 }
 
 /**

package/src/domain/services/StateSerializerV5.js

@@ -139,11 +139,11 @@ export async function computeStateHashV5(state, { crypto, codec } = /** @type {{
  * @param {Buffer} buffer
  * @param {Object} [options]
  * @param {import('../../ports/CodecPort.js').default} [options.codec] - Codec for deserialization
- * @returns {{nodes: string[], edges: Array<{from: string, to: string, label: string}>, props: Array<{node: string, key: string, value: *}>}}
+ * @returns {{nodes: string[], edges: Array<{from: string, to: string, label: string}>, props: Array<{node: string, key: string, value: unknown}>}}
  */
 export function deserializeStateV5(buffer, { codec } = {}) {
   const c = codec || defaultCodec;
-  return /** @type {{nodes: string[], edges: Array<{from: string, to: string, label: string}>, props: Array<{node: string, key: string, value: *}>}} */ (c.decode(buffer));
+  return /** @type {{nodes: string[], edges: Array<{from: string, to: string, label: string}>, props: Array<{node: string, key: string, value: unknown}>}} */ (c.decode(buffer));
 }
 
 // ============================================================================

package/src/domain/services/StreamingBitmapIndexBuilder.js

@@ -8,6 +8,8 @@ import { getRoaringBitmap32 } from '../utils/roaring.js';
 import { canonicalStringify } from '../utils/canonicalStringify.js';
 import { SHARD_VERSION } from '../utils/shardVersion.js';
 
+/** @typedef {import('../types/WarpPersistence.js').IndexStorage} IndexStorage */
+
 // Re-export for backwards compatibility
 export { SHARD_VERSION };
 
@@ -81,7 +83,7 @@ export default class StreamingBitmapIndexBuilder {
    * Creates a new StreamingBitmapIndexBuilder instance.
    *
    * @param {Object} options - Configuration options
-   * @param {Object} options.storage - Storage adapter implementing IndexStoragePort.
+   * @param {import('../../ports/IndexStoragePort.js').default} options.storage - Storage adapter implementing IndexStoragePort.
    *   Required methods: writeBlob, writeTree, readBlob
    * @param {number} [options.maxMemoryBytes=52428800] - Maximum bitmap memory before flush (default 50MB).
    *   Note: SHA→ID mappings are not counted against this limit as they must remain in memory.
@@ -106,8 +108,8 @@ export default class StreamingBitmapIndexBuilder {
     /** @type {import('../../ports/CodecPort.js').default} */
     this._codec = codec || defaultCodec;
 
-    /** @type {Object} */
-    this.storage = storage;
+    /** @type {IndexStorage} */
+    this.storage = /** @type {IndexStorage} */ (storage);
 
     /** @type {number} */
     this.maxMemoryBytes = maxMemoryBytes;
@@ -124,7 +126,7 @@ export default class StreamingBitmapIndexBuilder {
     /** @type {string[]} ID → SHA reverse mapping (kept in memory) */
     this.idToSha = [];
 
-    /** @type {Map<string, any>} Current in-memory bitmaps */
+    /** @type {Map<string, import('../utils/roaring.js').RoaringBitmapSubset>} Current in-memory bitmaps */
     this.bitmaps = new Map();
 
     /** @type {number} Estimated bytes used by current bitmaps */
@@ -139,8 +141,8 @@ export default class StreamingBitmapIndexBuilder {
     /** @type {number} Number of flush operations performed */
     this.flushCount = 0;
 
-    /** @type {any} Cached Roaring bitmap constructor */ // TODO(ts-cleanup): type lazy singleton
-    this._RoaringBitmap32 = getRoaringBitmap32(); // TODO(ts-cleanup): type lazy singleton
+    /** @type {typeof import('roaring').RoaringBitmap32} Cached Roaring bitmap constructor */
+    this._RoaringBitmap32 = getRoaringBitmap32();
   }
 
   /**
@@ -206,7 +208,7 @@ export default class StreamingBitmapIndexBuilder {
       if (!bitmapShards[type][prefix]) {
         bitmapShards[type][prefix] = {};
       }
-      bitmapShards[type][prefix][sha] = bitmap.serialize(true).toString('base64');
+      bitmapShards[type][prefix][sha] = Buffer.from(bitmap.serialize(true)).toString('base64');
     }
     return bitmapShards;
   }
@@ -238,7 +240,7 @@ export default class StreamingBitmapIndexBuilder {
               data: shardData,
             };
             const buffer = Buffer.from(JSON.stringify(envelope));
-            const oid = await /** @type {any} */ (this.storage).writeBlob(buffer); // TODO(ts-cleanup): narrow port type
+            const oid = await this.storage.writeBlob(buffer);
             if (!this.flushedChunks.has(path)) {
               this.flushedChunks.set(path, []);
             }
@@ -348,7 +350,7 @@ export default class StreamingBitmapIndexBuilder {
           data: map,
         };
         const buffer = Buffer.from(JSON.stringify(envelope));
-        const oid = await /** @type {any} */ (this.storage).writeBlob(buffer); // TODO(ts-cleanup): narrow port type
+        const oid = await this.storage.writeBlob(buffer);
         return `100644 blob ${oid}\t${path}`;
       })
     );
@@ -410,8 +412,8 @@ export default class StreamingBitmapIndexBuilder {
    * @param {Object} [options] - Finalization options
    * @param {AbortSignal} [options.signal] - Optional AbortSignal for cancellation.
    *   If aborted, throws an error with code 'ABORT_ERR'.
-   * @param {Map<string, number>} [options.frontier] - Optional version vector frontier
-   *   (writerId → clock) for staleness detection. If provided, frontier.cbor and
+   * @param {Map<string, string>} [options.frontier] - Optional writer frontier
+   *   (writerId → tip SHA) for staleness detection. If provided, frontier.cbor and
    *   frontier.json files are included in the tree.
    * @returns {Promise<string>} OID of the created Git tree containing the complete index
    * @throws {Error} If the operation is aborted via signal
@@ -440,19 +442,19 @@ export default class StreamingBitmapIndexBuilder {
 
     // Store frontier metadata for staleness detection
     if (frontier) {
-      /** @type {Record<string, number|undefined>} */
+      /** @type {Record<string, string|undefined>} */
       const sorted = {};
       for (const key of Array.from(frontier.keys()).sort()) {
         sorted[key] = frontier.get(key);
       }
       const envelope = { version: 1, writerCount: frontier.size, frontier: sorted };
-      const cborOid = await /** @type {any} */ (this.storage).writeBlob(Buffer.from(/** @type {any} */ (this._codec).encode(envelope))); // TODO(ts-cleanup): narrow port type
+      const cborOid = await this.storage.writeBlob(Buffer.from(this._codec.encode(envelope)));
       flatEntries.push(`100644 blob ${cborOid}\tfrontier.cbor`);
-      const jsonOid = await /** @type {any} */ (this.storage).writeBlob(Buffer.from(canonicalStringify(envelope))); // TODO(ts-cleanup): narrow port type
+      const jsonOid = await this.storage.writeBlob(Buffer.from(canonicalStringify(envelope)));
       flatEntries.push(`100644 blob ${jsonOid}\tfrontier.json`);
     }
 
-    const treeOid = await /** @type {any} */ (this.storage).writeTree(flatEntries); // TODO(ts-cleanup): narrow port type
+    const treeOid = await this.storage.writeTree(flatEntries);
 
     this.logger.debug('Index finalized', {
       operation: 'finalize',
@@ -539,7 +541,7 @@ export default class StreamingBitmapIndexBuilder {
       this.estimatedBitmapBytes += BITMAP_BASE_OVERHEAD;
     }
 
-    const bitmap = this.bitmaps.get(key);
+    const bitmap = /** @type {import('../utils/roaring.js').RoaringBitmapSubset} */ (this.bitmaps.get(key));
     const sizeBefore = bitmap.size;
     bitmap.add(id);
     const sizeAfter = bitmap.size;
@@ -569,7 +571,7 @@ export default class StreamingBitmapIndexBuilder {
    * @private
    */
   async _loadAndValidateChunk(oid) {
-    const buffer = await /** @type {any} */ (this.storage).readBlob(oid); // TODO(ts-cleanup): narrow port type
+    const buffer = await this.storage.readBlob(oid);
     let envelope;
     try {
       envelope = JSON.parse(buffer.toString('utf-8'));
@@ -577,7 +579,7 @@ export default class StreamingBitmapIndexBuilder {
       throw new ShardCorruptionError('Failed to parse shard JSON', {
         oid,
         reason: 'invalid_format',
-        context: { originalError: /** @type {any} */ (err).message }, // TODO(ts-cleanup): type error
+        context: { originalError: err instanceof Error ? err.message : String(err) },
       });
     }
 
@@ -614,7 +616,7 @@ export default class StreamingBitmapIndexBuilder {
    * it using `orInPlace` to combine edge sets.
    *
    * @param {Object} opts - Options object
-   * @param {Record<string, any>} opts.merged - Object mapping SHA to
+   * @param {Record<string, import('../utils/roaring.js').RoaringBitmapSubset>} opts.merged - Object mapping SHA to
    *   RoaringBitmap32 instances (mutated in place)
    * @param {string} opts.sha - The SHA key for this bitmap (40-character hex string)
    * @param {string} opts.base64Bitmap - Base64-encoded serialized RoaringBitmap32 data
@@ -631,7 +633,7 @@ export default class StreamingBitmapIndexBuilder {
       throw new ShardCorruptionError('Failed to deserialize bitmap', {
         oid,
         reason: 'invalid_bitmap',
-        context: { originalError: /** @type {any} */ (err).message }, // TODO(ts-cleanup): type error
+        context: { originalError: err instanceof Error ? err.message : String(err) },
       });
     }
 
@@ -675,7 +677,7 @@ export default class StreamingBitmapIndexBuilder {
    */
   async _mergeChunks(oids, { signal } = {}) {
     // Load all chunks and merge bitmaps by SHA
-    /** @type {Record<string, any>} */
+    /** @type {Record<string, import('../utils/roaring.js').RoaringBitmapSubset>} */
     const merged = {};
 
     for (const oid of oids) {
@@ -691,7 +693,7 @@ export default class StreamingBitmapIndexBuilder {
     /** @type {Record<string, string>} */
     const result = {};
     for (const [sha, bitmap] of Object.entries(merged)) {
-      result[sha] = bitmap.serialize(true).toString('base64');
+      result[sha] = Buffer.from(bitmap.serialize(true)).toString('base64');
     }
 
     // Wrap merged result in envelope with version and checksum
@@ -707,9 +709,9 @@ export default class StreamingBitmapIndexBuilder {
     } catch (err) {
       throw new ShardCorruptionError('Failed to serialize merged shard', {
         reason: 'serialization_error',
-        context: { originalError: /** @type {any} */ (err).message }, // TODO(ts-cleanup): type error
+        context: { originalError: err instanceof Error ? err.message : String(err) },
       });
     }
-    return /** @type {any} */ (this.storage).writeBlob(serialized); // TODO(ts-cleanup): narrow port type
+    return await this.storage.writeBlob(serialized);
   }
 }

package/src/domain/services/SyncAuthService.js

@@ -12,6 +12,7 @@
 import LRUCache from '../utils/LRUCache.js';
 import defaultCrypto from '../utils/defaultCrypto.js';
 import nullLogger from '../utils/nullLogger.js';
+import { validateWriterId } from '../utils/RefLayout.js';
 
 const SIG_VERSION = '1';
 const SIG_PREFIX = 'warp-v1';
@@ -103,7 +104,7 @@ function fail(reason, status) {
 }
 
 /**
- * @returns {{ authFailCount: number, replayRejectCount: number, nonceEvictions: number, clockSkewRejects: number, malformedRejects: number, logOnlyPassthroughs: number }}
+ * @returns {{ authFailCount: number, replayRejectCount: number, nonceEvictions: number, clockSkewRejects: number, malformedRejects: number, logOnlyPassthroughs: number, forbiddenWriterRejects: number }}
  */
 function _freshMetrics() {
   return {
@@ -113,6 +114,7 @@ function _freshMetrics() {
     clockSkewRejects: 0,
     malformedRejects: 0,
     logOnlyPassthroughs: 0,
+    forbiddenWriterRejects: 0,
   };
 }
 
@@ -142,6 +144,7 @@ function _checkHeaderFormats(timestamp, nonce, signature) {
 
 /**
  * @param {Record<string, string>|undefined} keys
+ * @returns {asserts keys is Record<string, string>}
  */
 function _validateKeys(keys) {
   if (!keys || typeof keys !== 'object' || Object.keys(keys).length === 0) {
@@ -149,6 +152,23 @@ function _validateKeys(keys) {
   }
 }
 
+/**
+ * @param {string[]|undefined} allowedWriters
+ * @returns {Set<string>|null}
+ */
+function _validateAllowedWriters(allowedWriters) {
+  if (!allowedWriters) {
+    return null;
+  }
+  if (allowedWriters.length === 0) {
+    throw new Error('allowedWriters must be a non-empty array when provided');
+  }
+  for (const w of allowedWriters) {
+    validateWriterId(w);
+  }
+  return new Set(allowedWriters);
+}
+
 export default class SyncAuthService {
   /**
    * @param {Object} options
@@ -159,8 +179,9 @@ export default class SyncAuthService {
    * @param {import('../../ports/CryptoPort.js').default} [options.crypto] - Crypto port
    * @param {import('../../ports/LoggerPort.js').default} [options.logger] - Logger port
    * @param {() => number} [options.wallClockMs] - Wall clock function
+   * @param {string[]} [options.allowedWriters] - Optional whitelist of allowed writer IDs. If set, sync requests with unlisted writers are rejected with 403.
    */
-  constructor({ keys, mode = 'enforce', nonceCapacity, maxClockSkewMs, crypto, logger, wallClockMs } = /** @type {*} */ ({})) { // TODO(ts-cleanup): needs options type
+  constructor({ keys, mode = 'enforce', nonceCapacity, maxClockSkewMs, crypto, logger, wallClockMs, allowedWriters } = /** @type {{ keys: Record<string, string> }} */ ({})) {
     _validateKeys(keys);
     this._keys = keys;
     this._mode = mode;
@@ -170,6 +191,7 @@ export default class SyncAuthService {
     this._maxClockSkewMs = typeof maxClockSkewMs === 'number' ? maxClockSkewMs : MAX_CLOCK_SKEW_MS;
     this._nonceCache = new LRUCache(nonceCapacity || DEFAULT_NONCE_CAPACITY);
     this._metrics = _freshMetrics();
+    this._allowedWriters = _validateAllowedWriters(allowedWriters);
   }
 
   /** @returns {'enforce'|'log-only'} */
@@ -364,10 +386,55 @@ export default class SyncAuthService {
     return { ok: true };
   }
 
+  /**
+   * Validates that all writer IDs are in the allowed set.
+   * Call after verify() succeeds.
+   *
+   * This method is a pure validator — it always returns `{ ok: false }` for
+   * forbidden writers regardless of `this._mode`. Mode enforcement (enforce
+   * vs log-only) is the caller's responsibility, matching the same pattern
+   * used by `verify()` and `HttpSyncServer._checkAuth()`.
+   *
+   * @param {string[]} writerIds - Writer IDs from the sync request
+   * @returns {{ ok: true } | { ok: false, reason: string, status: number }}
+   */
+  verifyWriters(writerIds) {
+    if (!this._allowedWriters) {
+      return { ok: true };
+    }
+    const forbidden = writerIds.filter(id => !/** @type {Set<string>} */ (this._allowedWriters).has(id));
+    if (forbidden.length > 0) {
+      this._metrics.forbiddenWriterRejects += 1;
+      this._logger.warn('sync auth: forbidden writers rejected', { forbidden });
+      return fail('FORBIDDEN_WRITER', 403);
+    }
+    return { ok: true };
+  }
+
+  /**
+   * Mode-aware convenience wrapper around `verifyWriters()`.
+   *
+   * In `enforce` mode, returns the failure result from `verifyWriters()`.
+   * In `log-only` mode, records a passthrough and returns `{ ok: true }`.
+   * Callers that want simple single-call authorization can use this instead
+   * of calling `verifyWriters()` + checking mode manually.
+   *
+   * @param {string[]} writerIds - Writer IDs from the sync request
+   * @returns {{ ok: true } | { ok: false, reason: string, status: number }}
+   */
+  enforceWriters(writerIds) {
+    const result = this.verifyWriters(writerIds);
+    if (!result.ok && this._mode !== 'enforce') {
+      this._metrics.logOnlyPassthroughs += 1;
+      return { ok: true };
+    }
+    return result;
+  }
+
   /**
    * Records an auth failure and returns the result.
    * @param {string} message
-   * @param {Record<string, *>} context
+   * @param {Record<string, unknown>} context
    * @param {{ ok: false, reason: string, status: number }} result
    * @returns {{ ok: false, reason: string, status: number }}
    * @private
@@ -388,7 +455,7 @@ export default class SyncAuthService {
   /**
    * Returns a snapshot of auth metrics.
    *
-   * @returns {{ authFailCount: number, replayRejectCount: number, nonceEvictions: number, clockSkewRejects: number, malformedRejects: number, logOnlyPassthroughs: number }}
+   * @returns {{ authFailCount: number, replayRejectCount: number, nonceEvictions: number, clockSkewRejects: number, malformedRejects: number, logOnlyPassthroughs: number, forbiddenWriterRejects: number }}
    */
   getMetrics() {
     return { ...this._metrics };