@mnemonik/shared 7.69.0 → 7.72.1

package/dist/index.d.ts

@@ -11,7 +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 { persistJitDeliveryRef, readPendingJitDeliveryRefs, reportJitDeliveryRefsAttached, acknowledgeJitDeliveryRefs, pruneExpiredJitDeliveryRefs, applyJitDeliveryReceiptResponse, normalizeJitHookVersion, type JitReceiptClientEvent, type JitReceiptClientEventName, type JitReceiptEventContext, } 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,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,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,6BAA6B,EAC7B,0BAA0B,EAC1B,2BAA2B,EAC3B,+BAA+B,EAC/B,uBAAuB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,GAC5B,MAAM,qBAAqB,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -11,7 +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 { persistJitDeliveryRef, readPendingJitDeliveryRefs, reportJitDeliveryRefsAttached, acknowledgeJitDeliveryRefs, pruneExpiredJitDeliveryRefs, applyJitDeliveryReceiptResponse, normalizeJitHookVersion, } 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,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,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,6BAA6B,EAC7B,0BAA0B,EAC1B,2BAA2B,EAC3B,+BAA+B,EAC/B,uBAAuB,GAIxB,MAAM,qBAAqB,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC"}

package/dist/jitDeliveryAck.d.ts

@@ -1,6 +1,30 @@
+export declare function normalizeJitHookVersion(hookVersion: unknown): string;
+export type JitReceiptClientEventName = 'marker_persisted' | 'marker_read' | 'attached_to_request' | 'marker_confirmed' | 'pruned_expired';
+export interface JitReceiptClientEvent {
+    mnemonik_marker: 'jit_receipt_client';
+    event: JitReceiptClientEventName;
+    deliveryRefHash: string;
+    sessionFingerprint: string;
+    hookVersion: string;
+    reason?: 'client_retention' | 'server_unknown_or_expired';
+}
+export interface JitReceiptEventContext {
+    sessionId: string;
+    hookVersion: string;
+    /** Test seam; production writes one JSON event per line to hook stderr. */
+    emit?: (event: JitReceiptClientEvent) => void;
+}
 /** 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[];
+export declare function persistJitDeliveryRef(directory: string, deliveryRef: string, context?: JitReceiptEventContext): boolean;
+export declare function readPendingJitDeliveryRefs(directory: string, context?: JitReceiptEventContext): string[];
+export declare function reportJitDeliveryRefsAttached(deliveryRefs: string[], context?: JitReceiptEventContext): void;
 /** Remove only references the server says were valid or safe duplicates. */
-export declare function acknowledgeJitDeliveryRefs(directory: string, deliveryRefs: string[]): void;
+export declare function acknowledgeJitDeliveryRefs(directory: string, deliveryRefs: string[], context?: JitReceiptEventContext): void;
+/** Remove references the server can no longer accept instead of retrying forever. */
+export declare function pruneExpiredJitDeliveryRefs(directory: string, deliveryRefs: string[], context?: JitReceiptEventContext): void;
+/** Apply only receipt outcomes correlated to the exact refs on this request. */
+export declare function applyJitDeliveryReceiptResponse(directory: string, attachedDeliveryRefs: string[], response: {
+    confirmedDeliveryRefs?: string[];
+    discardedDeliveryRefs?: string[];
+}, context?: JitReceiptEventContext): void;
 //# sourceMappingURL=jitDeliveryAck.d.ts.map

package/dist/jitDeliveryAck.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"jitDeliveryAck.d.ts","sourceRoot":"","sources":["../src/jitDeliveryAck.ts"],"names":[],"mappings":"AAoBA,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,OAAO,GAAG,MAAM,CAOpE;AAED,MAAM,MAAM,yBAAyB,GACjC,kBAAkB,GAClB,aAAa,GACb,qBAAqB,GACrB,kBAAkB,GAClB,gBAAgB,CAAC;AAErB,MAAM,WAAW,qBAAqB;IACpC,eAAe,EAAE,oBAAoB,CAAC;IACtC,KAAK,EAAE,yBAAyB,CAAC;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,kBAAkB,GAAG,2BAA2B,CAAC;CAC3D;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;CAC/C;AAyCD,kFAAkF;AAClF,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CA8BT;AAED,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,MAAM,EAAE,CAyCV;AAED,wBAAgB,6BAA6B,CAC3C,YAAY,EAAE,MAAM,EAAE,EACtB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,IAAI,CAMN;AAED,4EAA4E;AAC5E,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EAAE,EACtB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,IAAI,CAUN;AAED,qFAAqF;AACrF,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EAAE,EACtB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,IAAI,CAUN;AAED,gFAAgF;AAChF,wBAAgB,+BAA+B,CAC7C,SAAS,EAAE,MAAM,EACjB,oBAAoB,EAAE,MAAM,EAAE,EAC9B,QAAQ,EAAE;IAAE,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,EAChF,OAAO,CAAC,EAAE,sBAAsB,GAC/B,IAAI,CAYN"}

package/dist/jitDeliveryAck.js

@@ -1,8 +1,44 @@
+import { createHash } from 'node:crypto';
 import { chmodSync, closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readdirSync, unlinkSync, } from 'node:fs';
 import { join } from 'node:path';
+import { stderr } from 'node:process';
 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 HOOK_VERSION_RE = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
 const MAX_PENDING_REFS = 8;
 const DELIVERY_REF_RETENTION_MS = 240_000;
+export function normalizeJitHookVersion(hookVersion) {
+    if (hookVersion === undefined || hookVersion === null)
+        return 'unknown';
+    return typeof hookVersion === 'string' &&
+        hookVersion.length <= 64 &&
+        HOOK_VERSION_RE.test(hookVersion)
+        ? hookVersion
+        : 'unrecognized';
+}
+function hash(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function emitReceiptEvent(context, event, deliveryRef, reason) {
+    if (!context)
+        return;
+    const record = {
+        mnemonik_marker: 'jit_receipt_client',
+        event,
+        deliveryRefHash: hash(deliveryRef),
+        sessionFingerprint: hash(context.sessionId).slice(0, 16),
+        hookVersion: normalizeJitHookVersion(context.hookVersion),
+        ...(reason ? { reason } : {}),
+    };
+    try {
+        if (context.emit)
+            context.emit(record);
+        else
+            stderr.write(`${JSON.stringify(record)}\n`);
+    }
+    catch {
+        // Receipt instrumentation must never interfere with the host turn.
+    }
+}
 function ensurePrivateDirectory(path) {
     if (!path)
         return false;
@@ -18,19 +54,23 @@ function ensurePrivateDirectory(path) {
     }
 }
 /** Persist only after the final host-visible payload contains this JIT result. */
-export function persistJitDeliveryRef(directory, deliveryRef) {
+export function persistJitDeliveryRef(directory, deliveryRef, context) {
     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);
+        emitReceiptEvent(context, 'marker_persisted', deliveryRef);
         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;
+            const persisted = stat.isFile() && !stat.isSymbolicLink() && (stat.mode & 0o077) === 0;
+            if (persisted)
+                emitReceiptEvent(context, 'marker_persisted', deliveryRef);
+            return persisted;
         }
         catch {
             return false;
@@ -47,7 +87,7 @@ export function persistJitDeliveryRef(directory, deliveryRef) {
         }
     }
 }
-export function readPendingJitDeliveryRefs(directory) {
+export function readPendingJitDeliveryRefs(directory, context) {
     if (!directory)
         return [];
     try {
@@ -73,8 +113,10 @@ export function readPendingJitDeliveryRefs(directory) {
                     catch {
                         // Keep expired markers out of the send window even if cleanup races or fails.
                     }
+                    emitReceiptEvent(context, 'pruned_expired', deliveryRef, 'client_retention');
                     continue;
                 }
+                emitReceiptEvent(context, 'marker_read', deliveryRef);
                 live.push({ deliveryRef, modifiedAt: marker.mtimeMs });
             }
             catch {
@@ -90,11 +132,19 @@ export function readPendingJitDeliveryRefs(directory) {
         return [];
     }
 }
+export function reportJitDeliveryRefsAttached(deliveryRefs, context) {
+    for (const deliveryRef of new Set(deliveryRefs)) {
+        if (DELIVERY_REF_RE.test(deliveryRef)) {
+            emitReceiptEvent(context, 'attached_to_request', deliveryRef);
+        }
+    }
+}
 /** Remove only references the server says were valid or safe duplicates. */
-export function acknowledgeJitDeliveryRefs(directory, deliveryRefs) {
+export function acknowledgeJitDeliveryRefs(directory, deliveryRefs, context) {
     for (const deliveryRef of new Set(deliveryRefs)) {
         if (!DELIVERY_REF_RE.test(deliveryRef))
             continue;
+        emitReceiptEvent(context, 'marker_confirmed', deliveryRef);
         try {
             unlinkSync(join(directory, deliveryRef));
         }
@@ -103,4 +153,24 @@ export function acknowledgeJitDeliveryRefs(directory, deliveryRefs) {
         }
     }
 }
+/** Remove references the server can no longer accept instead of retrying forever. */
+export function pruneExpiredJitDeliveryRefs(directory, deliveryRefs, context) {
+    for (const deliveryRef of new Set(deliveryRefs)) {
+        if (!DELIVERY_REF_RE.test(deliveryRef))
+            continue;
+        try {
+            unlinkSync(join(directory, deliveryRef));
+        }
+        catch {
+            // Missing/locked marker: the ordinary client-retention sweep remains a backstop.
+        }
+        emitReceiptEvent(context, 'pruned_expired', deliveryRef, 'server_unknown_or_expired');
+    }
+}
+/** Apply only receipt outcomes correlated to the exact refs on this request. */
+export function applyJitDeliveryReceiptResponse(directory, attachedDeliveryRefs, response, context) {
+    const attached = new Set(attachedDeliveryRefs);
+    acknowledgeJitDeliveryRefs(directory, (response.confirmedDeliveryRefs ?? []).filter((deliveryRef) => attached.has(deliveryRef)), context);
+    pruneExpiredJitDeliveryRefs(directory, (response.discardedDeliveryRefs ?? []).filter((deliveryRef) => attached.has(deliveryRef)), context);
+}
 //# sourceMappingURL=jitDeliveryAck.js.map

package/dist/jitDeliveryAck.js.map

@@ -1 +1 @@
-{"version":3,"file":"jitDeliveryAck.js","sourceRoot":"","sources":["../src/jitDeliveryAck.ts"],"names":[],"mappings":"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"}
+{"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.69.0",
+  "version": "7.72.1",
   "description": "Shared constants and utilities for Mnemonik packages",
   "repository": {
     "type": "git",

package/src/index.ts

@@ -61,7 +61,14 @@ export {
 export {
   persistJitDeliveryRef,
   readPendingJitDeliveryRefs,
+  reportJitDeliveryRefsAttached,
   acknowledgeJitDeliveryRefs,
+  pruneExpiredJitDeliveryRefs,
+  applyJitDeliveryReceiptResponse,
+  normalizeJitHookVersion,
+  type JitReceiptClientEvent,
+  type JitReceiptClientEventName,
+  type JitReceiptEventContext,
 } from './jitDeliveryAck.js';
 export * from './settingsIo.js';
 export * from './claudeProxySettings.js';

package/src/jitDeliveryAck.ts

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import {
   chmodSync,
   closeSync,
@@ -10,11 +11,72 @@ import {
   unlinkSync,
 } from 'node:fs';
 import { join } from 'node:path';
+import { stderr } from 'node:process';
 
 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 HOOK_VERSION_RE = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
 const MAX_PENDING_REFS = 8;
 const DELIVERY_REF_RETENTION_MS = 240_000;
 
+export function normalizeJitHookVersion(hookVersion: unknown): string {
+  if (hookVersion === undefined || hookVersion === null) return 'unknown';
+  return typeof hookVersion === 'string' &&
+    hookVersion.length <= 64 &&
+    HOOK_VERSION_RE.test(hookVersion)
+    ? hookVersion
+    : 'unrecognized';
+}
+
+export type JitReceiptClientEventName =
+  | 'marker_persisted'
+  | 'marker_read'
+  | 'attached_to_request'
+  | 'marker_confirmed'
+  | 'pruned_expired';
+
+export interface JitReceiptClientEvent {
+  mnemonik_marker: 'jit_receipt_client';
+  event: JitReceiptClientEventName;
+  deliveryRefHash: string;
+  sessionFingerprint: string;
+  hookVersion: string;
+  reason?: 'client_retention' | 'server_unknown_or_expired';
+}
+
+export interface JitReceiptEventContext {
+  sessionId: string;
+  hookVersion: string;
+  /** Test seam; production writes one JSON event per line to hook stderr. */
+  emit?: (event: JitReceiptClientEvent) => void;
+}
+
+function hash(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function emitReceiptEvent(
+  context: JitReceiptEventContext | undefined,
+  event: JitReceiptClientEventName,
+  deliveryRef: string,
+  reason?: JitReceiptClientEvent['reason']
+): void {
+  if (!context) return;
+  const record: JitReceiptClientEvent = {
+    mnemonik_marker: 'jit_receipt_client',
+    event,
+    deliveryRefHash: hash(deliveryRef),
+    sessionFingerprint: hash(context.sessionId).slice(0, 16),
+    hookVersion: normalizeJitHookVersion(context.hookVersion),
+    ...(reason ? { reason } : {}),
+  };
+  try {
+    if (context.emit) context.emit(record);
+    else stderr.write(`${JSON.stringify(record)}\n`);
+  } catch {
+    // Receipt instrumentation must never interfere with the host turn.
+  }
+}
+
 function ensurePrivateDirectory(path: string): boolean {
   if (!path) return false;
   try {
@@ -28,7 +90,11 @@ function ensurePrivateDirectory(path: string): boolean {
 }
 
 /** Persist only after the final host-visible payload contains this JIT result. */
-export function persistJitDeliveryRef(directory: string, deliveryRef: string): boolean {
+export function persistJitDeliveryRef(
+  directory: string,
+  deliveryRef: string,
+  context?: JitReceiptEventContext
+): boolean {
   if (!DELIVERY_REF_RE.test(deliveryRef) || !ensurePrivateDirectory(directory)) return false;
   let fd: number | null = null;
   try {
@@ -37,12 +103,15 @@ export function persistJitDeliveryRef(directory: string, deliveryRef: string): b
       constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | (constants.O_NOFOLLOW ?? 0),
       0o600
     );
+    emitReceiptEvent(context, 'marker_persisted', deliveryRef);
     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;
+      const persisted = stat.isFile() && !stat.isSymbolicLink() && (stat.mode & 0o077) === 0;
+      if (persisted) emitReceiptEvent(context, 'marker_persisted', deliveryRef);
+      return persisted;
     } catch {
       return false;
     }
@@ -57,7 +126,10 @@ export function persistJitDeliveryRef(directory: string, deliveryRef: string): b
   }
 }
 
-export function readPendingJitDeliveryRefs(directory: string): string[] {
+export function readPendingJitDeliveryRefs(
+  directory: string,
+  context?: JitReceiptEventContext
+): string[] {
   if (!directory) return [];
   try {
     if (!existsSync(directory)) return [];
@@ -78,8 +150,10 @@ export function readPendingJitDeliveryRefs(directory: string): string[] {
           } catch {
             // Keep expired markers out of the send window even if cleanup races or fails.
           }
+          emitReceiptEvent(context, 'pruned_expired', deliveryRef, 'client_retention');
           continue;
         }
+        emitReceiptEvent(context, 'marker_read', deliveryRef);
         live.push({ deliveryRef, modifiedAt: marker.mtimeMs });
       } catch {
         // A marker removed concurrently is already in the desired state.
@@ -98,10 +172,26 @@ export function readPendingJitDeliveryRefs(directory: string): string[] {
   }
 }
 
+export function reportJitDeliveryRefsAttached(
+  deliveryRefs: string[],
+  context?: JitReceiptEventContext
+): void {
+  for (const deliveryRef of new Set(deliveryRefs)) {
+    if (DELIVERY_REF_RE.test(deliveryRef)) {
+      emitReceiptEvent(context, 'attached_to_request', deliveryRef);
+    }
+  }
+}
+
 /** Remove only references the server says were valid or safe duplicates. */
-export function acknowledgeJitDeliveryRefs(directory: string, deliveryRefs: string[]): void {
+export function acknowledgeJitDeliveryRefs(
+  directory: string,
+  deliveryRefs: string[],
+  context?: JitReceiptEventContext
+): void {
   for (const deliveryRef of new Set(deliveryRefs)) {
     if (!DELIVERY_REF_RE.test(deliveryRef)) continue;
+    emitReceiptEvent(context, 'marker_confirmed', deliveryRef);
     try {
       unlinkSync(join(directory, deliveryRef));
     } catch {
@@ -109,3 +199,40 @@ export function acknowledgeJitDeliveryRefs(directory: string, deliveryRefs: stri
     }
   }
 }
+
+/** Remove references the server can no longer accept instead of retrying forever. */
+export function pruneExpiredJitDeliveryRefs(
+  directory: string,
+  deliveryRefs: string[],
+  context?: JitReceiptEventContext
+): void {
+  for (const deliveryRef of new Set(deliveryRefs)) {
+    if (!DELIVERY_REF_RE.test(deliveryRef)) continue;
+    try {
+      unlinkSync(join(directory, deliveryRef));
+    } catch {
+      // Missing/locked marker: the ordinary client-retention sweep remains a backstop.
+    }
+    emitReceiptEvent(context, 'pruned_expired', deliveryRef, 'server_unknown_or_expired');
+  }
+}
+
+/** Apply only receipt outcomes correlated to the exact refs on this request. */
+export function applyJitDeliveryReceiptResponse(
+  directory: string,
+  attachedDeliveryRefs: string[],
+  response: { confirmedDeliveryRefs?: string[]; discardedDeliveryRefs?: string[] },
+  context?: JitReceiptEventContext
+): void {
+  const attached = new Set(attachedDeliveryRefs);
+  acknowledgeJitDeliveryRefs(
+    directory,
+    (response.confirmedDeliveryRefs ?? []).filter((deliveryRef) => attached.has(deliveryRef)),
+    context
+  );
+  pruneExpiredJitDeliveryRefs(
+    directory,
+    (response.discardedDeliveryRefs ?? []).filter((deliveryRef) => attached.has(deliveryRef)),
+    context
+  );
+}