feat: expose verified diff capabilities

Author: sunnylqm

README.md

@@ -60,6 +60,14 @@ returns `outDiffPath`; async callback signature is `(err, outDiffPath)`.
 a larger window catches longer-distance content moves at roughly linear
 additional memory.
 
+### capabilities
+
+`capabilities.diffStreamVerifiesOutput`,
+`capabilities.diffSingleStreamVerifiesOutput`, and
+`capabilities.diffWindowVerifiesOutput` are `true`. Each native diff function
+applies and compares the generated patch before it returns, so orchestration
+layers can avoid running a redundant second round-trip check.
+
 ### patchSingleStream(oldPath, diffPath, outNewPath[, cb])
 
 Apply a single-compressed hpatch payload created by `diff` or

index.d.ts

@@ -61,6 +61,15 @@ export interface NativeAddon {
 
 export const native: NativeAddon;
 
+export interface HdiffpatchCapabilities {
+  readonly diffStreamVerifiesOutput: true;
+  readonly diffSingleStreamVerifiesOutput: true;
+  readonly diffWindowVerifiesOutput: true;
+}
+
+/** Native diff functions apply and compare their output before returning. */
+export const capabilities: HdiffpatchCapabilities;
+
 export function diff(oldBuf: BinaryLike, newBuf: BinaryLike): Buffer;
 export function diff(
   oldBuf: BinaryLike,
@@ -147,6 +156,7 @@ export function diffWindow(
 
 declare const hdiffpatch: {
   native: NativeAddon;
+  capabilities: HdiffpatchCapabilities;
   diff: typeof diff;
   patch: typeof patch;
   diffStream: typeof diffStream;

index.js

@@ -38,3 +38,12 @@ exports.patchStream = native.patchStream;
 exports.diffSingleStream = native.diffSingleStream;
 exports.patchSingleStream = native.patchSingleStream;
 exports.diffWindow = native.diffWindow;
+
+// Every native diff entry point performs a complete apply-and-compare check
+// before returning. Consumers that would otherwise repeat the same round trip
+// can use these explicit capabilities to safely avoid duplicate work.
+exports.capabilities = Object.freeze({
+  diffStreamVerifiesOutput: true,
+  diffSingleStreamVerifiesOutput: true,
+  diffWindowVerifiesOutput: true,
+});

test/test.js

@@ -22,6 +22,13 @@ function assertHeaderPrefix(diffData, prefix) {
   assert.deepStrictEqual(diffData.subarray(0, expected.length), expected);
 }
 
+assert.deepStrictEqual(hdiffpatch.capabilities, {
+  diffStreamVerifiesOutput: true,
+  diffSingleStreamVerifiesOutput: true,
+  diffWindowVerifiesOutput: true
+});
+assert(Object.isFrozen(hdiffpatch.capabilities));
+
 console.log("Test 1: diff + patch = original (sync)...");
 var oldData = crypto.randomBytes(40960);
 var newData = Buffer.concat([