@mnemonik/shared 7.68.0 → 7.72.0

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export { AST_LANGUAGE_IDS, QUERY_CHAIN, VENDORED_ARTIFACT_DIR, astArtifactReport
 export { MAX_AST_PARSE_BYTES, chunkWithAst, type AstChunk, type AstChunkResult, } from './ast/astChunker.js';
 export { SECRET_PATTERNS, SECRET_REDACTION_PLACEHOLDER, scrubSecrets, redactHighEntropyTokens, } from './secretPatterns.js';
 export { FETCH_TIMEOUT_MS, TELEMETRY_TIMEOUT_MS, POST_TOOL_TIMEOUT_MS, MCP_PRECHECK_TIMEOUT_MS, withHookTimeout, } from './hookTimeouts.js';
+export { persistJitDeliveryRef, readPendingJitDeliveryRefs, acknowledgeJitDeliveryRefs, } from './jitDeliveryAck.js';
 export * from './settingsIo.js';
 export * from './claudeProxySettings.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,EACpB,KAAK,SAAS,EACd,KAAK,WAAW,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,EACvB,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,wBAAwB,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,KAAK,QAAQ,EACb,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,eAAe,EACf,4BAA4B,EAC5B,YAAY,EACZ,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,uBAAuB,EACvB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,EACpB,KAAK,SAAS,EACd,KAAK,WAAW,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,EACvB,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,wBAAwB,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,KAAK,QAAQ,EACb,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,eAAe,EACf,4BAA4B,EAC5B,YAAY,EACZ,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,uBAAuB,EACvB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -11,6 +11,7 @@ export { AST_LANGUAGE_IDS, QUERY_CHAIN, VENDORED_ARTIFACT_DIR, astArtifactReport
 export { MAX_AST_PARSE_BYTES, chunkWithAst, } from './ast/astChunker.js';
 export { SECRET_PATTERNS, SECRET_REDACTION_PLACEHOLDER, scrubSecrets, redactHighEntropyTokens, } from './secretPatterns.js';
 export { FETCH_TIMEOUT_MS, TELEMETRY_TIMEOUT_MS, POST_TOOL_TIMEOUT_MS, MCP_PRECHECK_TIMEOUT_MS, withHookTimeout, } from './hookTimeouts.js';
+export { persistJitDeliveryRef, readPendingJitDeliveryRefs, acknowledgeJitDeliveryRefs, } from './jitDeliveryAck.js';
 export * from './settingsIo.js';
 export * from './claudeProxySettings.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,GAGrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,EACvB,WAAW,EACX,gBAAgB,EAChB,kBAAkB,GAKnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,mBAAmB,EACnB,YAAY,GAGb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,eAAe,EACf,4BAA4B,EAC5B,YAAY,EACZ,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,uBAAuB,EACvB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,GAGrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,EACvB,WAAW,EACX,gBAAgB,EAChB,kBAAkB,GAKnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,mBAAmB,EACnB,YAAY,GAGb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,eAAe,EACf,4BAA4B,EAC5B,YAAY,EACZ,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,uBAAuB,EACvB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC"}

package/dist/jitDeliveryAck.d.ts

@@ -0,0 +1,6 @@
+/** Persist only after the final host-visible payload contains this JIT result. */
+export declare function persistJitDeliveryRef(directory: string, deliveryRef: string): boolean;
+export declare function readPendingJitDeliveryRefs(directory: string): string[];
+/** Remove only references the server says were valid or safe duplicates. */
+export declare function acknowledgeJitDeliveryRefs(directory: string, deliveryRefs: string[]): void;
+//# sourceMappingURL=jitDeliveryAck.d.ts.map

package/dist/jitDeliveryAck.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jitDeliveryAck.d.ts","sourceRoot":"","sources":["../src/jitDeliveryAck.ts"],"names":[],"mappings":"AA6BA,kFAAkF;AAClF,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CA2BrF;AAED,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAuCtE;AAED,4EAA4E;AAC5E,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,IAAI,CAS1F"}

package/dist/jitDeliveryAck.js

@@ -0,0 +1,106 @@
+import { chmodSync, closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readdirSync, unlinkSync, } from 'node:fs';
+import { join } from 'node:path';
+const DELIVERY_REF_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const MAX_PENDING_REFS = 8;
+const DELIVERY_REF_RETENTION_MS = 240_000;
+function ensurePrivateDirectory(path) {
+    if (!path)
+        return false;
+    try {
+        if (existsSync(path) && lstatSync(path).isSymbolicLink())
+            return false;
+        mkdirSync(path, { recursive: true, mode: 0o700 });
+        chmodSync(path, 0o700);
+        return lstatSync(path).isDirectory() && !lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/** Persist only after the final host-visible payload contains this JIT result. */
+export function persistJitDeliveryRef(directory, deliveryRef) {
+    if (!DELIVERY_REF_RE.test(deliveryRef) || !ensurePrivateDirectory(directory))
+        return false;
+    let fd = null;
+    try {
+        fd = openSync(join(directory, deliveryRef), constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | (constants.O_NOFOLLOW ?? 0), 0o600);
+        return true;
+    }
+    catch {
+        // An existing marker is already the desired idempotent state.
+        try {
+            const stat = lstatSync(join(directory, deliveryRef));
+            return stat.isFile() && !stat.isSymbolicLink() && (stat.mode & 0o077) === 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // Receipt persistence is fail-open for the host turn.
+            }
+        }
+    }
+}
+export function readPendingJitDeliveryRefs(directory) {
+    if (!directory)
+        return [];
+    try {
+        if (!existsSync(directory))
+            return [];
+        const stat = lstatSync(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            return [];
+        const now = Date.now();
+        const live = [];
+        for (const deliveryRef of readdirSync(directory)) {
+            if (!DELIVERY_REF_RE.test(deliveryRef))
+                continue;
+            const markerPath = join(directory, deliveryRef);
+            try {
+                const marker = lstatSync(markerPath);
+                if (!marker.isFile() || marker.isSymbolicLink())
+                    continue;
+                if (now - marker.mtimeMs >= DELIVERY_REF_RETENTION_MS) {
+                    try {
+                        unlinkSync(markerPath);
+                    }
+                    catch {
+                        // Keep expired markers out of the send window even if cleanup races or fails.
+                    }
+                    continue;
+                }
+                live.push({ deliveryRef, modifiedAt: marker.mtimeMs });
+            }
+            catch {
+                // A marker removed concurrently is already in the desired state.
+            }
+        }
+        return live
+            .sort((left, right) => right.modifiedAt - left.modifiedAt || right.deliveryRef.localeCompare(left.deliveryRef))
+            .slice(0, MAX_PENDING_REFS)
+            .map(({ deliveryRef }) => deliveryRef);
+    }
+    catch {
+        return [];
+    }
+}
+/** Remove only references the server says were valid or safe duplicates. */
+export function acknowledgeJitDeliveryRefs(directory, deliveryRefs) {
+    for (const deliveryRef of new Set(deliveryRefs)) {
+        if (!DELIVERY_REF_RE.test(deliveryRef))
+            continue;
+        try {
+            unlinkSync(join(directory, deliveryRef));
+        }
+        catch {
+            // Missing/locked marker: retrying is harmless and bounded by server TTL.
+        }
+    }
+}
+//# sourceMappingURL=jitDeliveryAck.js.map

package/dist/jitDeliveryAck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jitDeliveryAck.js","sourceRoot":"","sources":["../src/jitDeliveryAck.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemonik/shared",
-  "version": "7.68.0",
+  "version": "7.72.0",
   "description": "Shared constants and utilities for Mnemonik packages",
   "repository": {
     "type": "git",
@@ -34,6 +34,10 @@
     "./git-edit-detector": {
       "import": "./dist/gitEditDetector.js",
       "types": "./dist/gitEditDetector.d.ts"
+    },
+    "./jit-delivery-ack": {
+      "import": "./dist/jitDeliveryAck.js",
+      "types": "./dist/jitDeliveryAck.d.ts"
     }
   },
   "scripts": {

package/src/index.ts

@@ -58,5 +58,10 @@ export {
   MCP_PRECHECK_TIMEOUT_MS,
   withHookTimeout,
 } from './hookTimeouts.js';
+export {
+  persistJitDeliveryRef,
+  readPendingJitDeliveryRefs,
+  acknowledgeJitDeliveryRefs,
+} from './jitDeliveryAck.js';
 export * from './settingsIo.js';
 export * from './claudeProxySettings.js';

package/src/jitDeliveryAck.ts

@@ -0,0 +1,111 @@
+import {
+  chmodSync,
+  closeSync,
+  constants,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  unlinkSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+const DELIVERY_REF_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const MAX_PENDING_REFS = 8;
+const DELIVERY_REF_RETENTION_MS = 240_000;
+
+function ensurePrivateDirectory(path: string): boolean {
+  if (!path) return false;
+  try {
+    if (existsSync(path) && lstatSync(path).isSymbolicLink()) return false;
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+    chmodSync(path, 0o700);
+    return lstatSync(path).isDirectory() && !lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/** Persist only after the final host-visible payload contains this JIT result. */
+export function persistJitDeliveryRef(directory: string, deliveryRef: string): boolean {
+  if (!DELIVERY_REF_RE.test(deliveryRef) || !ensurePrivateDirectory(directory)) return false;
+  let fd: number | null = null;
+  try {
+    fd = openSync(
+      join(directory, deliveryRef),
+      constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | (constants.O_NOFOLLOW ?? 0),
+      0o600
+    );
+    return true;
+  } catch {
+    // An existing marker is already the desired idempotent state.
+    try {
+      const stat = lstatSync(join(directory, deliveryRef));
+      return stat.isFile() && !stat.isSymbolicLink() && (stat.mode & 0o077) === 0;
+    } catch {
+      return false;
+    }
+  } finally {
+    if (fd !== null) {
+      try {
+        closeSync(fd);
+      } catch {
+        // Receipt persistence is fail-open for the host turn.
+      }
+    }
+  }
+}
+
+export function readPendingJitDeliveryRefs(directory: string): string[] {
+  if (!directory) return [];
+  try {
+    if (!existsSync(directory)) return [];
+    const stat = lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) return [];
+    const now = Date.now();
+    const live: Array<{ deliveryRef: string; modifiedAt: number }> = [];
+
+    for (const deliveryRef of readdirSync(directory)) {
+      if (!DELIVERY_REF_RE.test(deliveryRef)) continue;
+      const markerPath = join(directory, deliveryRef);
+      try {
+        const marker = lstatSync(markerPath);
+        if (!marker.isFile() || marker.isSymbolicLink()) continue;
+        if (now - marker.mtimeMs >= DELIVERY_REF_RETENTION_MS) {
+          try {
+            unlinkSync(markerPath);
+          } catch {
+            // Keep expired markers out of the send window even if cleanup races or fails.
+          }
+          continue;
+        }
+        live.push({ deliveryRef, modifiedAt: marker.mtimeMs });
+      } catch {
+        // A marker removed concurrently is already in the desired state.
+      }
+    }
+
+    return live
+      .sort(
+        (left, right) =>
+          right.modifiedAt - left.modifiedAt || right.deliveryRef.localeCompare(left.deliveryRef)
+      )
+      .slice(0, MAX_PENDING_REFS)
+      .map(({ deliveryRef }) => deliveryRef);
+  } catch {
+    return [];
+  }
+}
+
+/** Remove only references the server says were valid or safe duplicates. */
+export function acknowledgeJitDeliveryRefs(directory: string, deliveryRefs: string[]): void {
+  for (const deliveryRef of new Set(deliveryRefs)) {
+    if (!DELIVERY_REF_RE.test(deliveryRef)) continue;
+    try {
+      unlinkSync(join(directory, deliveryRef));
+    } catch {
+      // Missing/locked marker: retrying is harmless and bounded by server TTL.
+    }
+  }
+}