@coderifts/agent-guard 6.2.0 → 6.4.0

package/README.md

@@ -67,23 +67,40 @@ requireExecutionStateMatch?: boolean | 'warn';
 | Mode | Value | Behavior |
 |---|---|---|
 | **OFF** (default) | `false` / absent | No recheck. Residual execution-state race as described under “TOCTOU is unclosed.” |
-| **Warn** (report-only) | `'warn'` | Rechecks. On **drift**, emits `execution_state_drift_observed` via **`onEvent`**, then **proceeds** (does not block). On match, silent (drift-only telemetry). Use this to gather production drift data without changing who executes. |
-| **Enforce** | `true` | Rechecks. On drift, **blocks** with integrity cause `EXECUTION_STATE_DRIFT` (factory never runs). Byte-identical to the original enforce path. |
+| **Warn** (report-only) | `'warn'` | Rechecks. On **real drift**, emits loud `execution_state_drift_observed` via **`onEvent`**, then **proceeds**. On **unmeasurable** state (nothing to compare), emits quiet `execution_state_unmeasurable` (not drift, not safety), then **proceeds**. On match, silent. |
+| **Enforce** | `true` | Rechecks. On mismatch, **blocks** with integrity cause `EXECUTION_STATE_DRIFT` (factory never runs). Byte-identical to the original enforce path. |
 
-Recommended adoption path: **off → `'warn'` (observe) → `true` (enforce)** once your own
-telemetry shows drift is rare and real. A default flip to enforce is a later, versioned
-product decision — not this mode’s job.
+**Two warn signals (noise-fix for a future default flip):**
 
-Warn-mode event (host-side only; the guard does **not** phone home), on `GuardConfig.onEvent`:
+| Event | When | Meaning |
+|---|---|---|
+| `execution_state_drift_observed` (loud) | `reason === fingerprint_stale_at_execute` | Authorized fp ≠ current artifacts hash — real T1→T2 content drift. |
+| `execution_state_unmeasurable` (quiet) | `missing_artifacts` or `missing_authorized_fingerprint` | Nothing to measure — **not** evidence of drift and **not** evidence of safety. |
+
+A future default flip to warn (step3b, guard@7) will ride on the **loud** signal only; quiet unmeasurable must not page as drift. Recommended adoption: **off → `'warn'` (observe loud only) → `true` (enforce)**.
+
+Warn-mode events (host-side only; the guard does **not** phone home), on `GuardConfig.onEvent`:
 
 ```ts
+// Loud — real drift (shape frozen; regression-locked)
 {
   type: 'execution_state_drift_observed';
   at: string;                         // ISO timestamp
   decisionId?: string;
   current_fingerprint: string | null;
   authorized_fingerprint: string | null;
-  reason: string;
+  reason: string;                     // fingerprint_stale_at_execute
+}
+
+// Quiet — unmeasurable (additive)
+{
+  type: 'execution_state_unmeasurable';
+  at: string;
+  decisionId?: string;
+  current_fingerprint: string | null;
+  authorized_fingerprint: string | null;
+  reason: string;                     // missing_artifacts | missing_authorized_fingerprint
+  note: 'nothing to measure — not evidence of drift, not evidence of safety';
 }
 ```
 
@@ -94,9 +111,10 @@ const outcome = await guardToolCall(call, executeFactory, {
   requireExecutionStateMatch: 'warn', // opt-in telemetry; still proceeds on drift
   onEvent: (e) => {
     if (e.type === 'execution_state_drift_observed') {
-      // host metrics / log — you own retention; nothing is sent to CodeRifts from here
+      // host metrics / log — real drift only; nothing is sent to CodeRifts from here
       console.warn('execution-state drift', e.decisionId, e.reason, e.current_fingerprint);
     }
+    // optional: e.type === 'execution_state_unmeasurable' → debug-only, do not page
   },
 });
 ```
@@ -147,6 +165,13 @@ const { tools, registry_report, composition_assurance } = withCodeRifts({
 // the guard — the composition can only protect the table it returns.
 ```
 
+Optional guard-policy fields on the same input are forwarded **unchanged** onto `GuardConfig` when
+present (absent = today’s defaults — no behavior change): `onEvent`, `monitoringSinkWired`,
+`resolvePriorContent`, `requireFreshness`, `allowStaleContext`, `requireConditionalWrite`, and
+**`requireExecutionStateMatch`** (`boolean | 'warn'`, default off). The last is plumbing for the
+ID842 T2 recheck so one-call hosts can opt into warn/true; it is **not** TOCTOU closure and does
+not flip the package default (see **`requireExecutionStateMatch`** above).
+
 ### Final-answer proof block (ID645)
 
 When a call produces a machine `GuardExecutionProof` (`outcome.proof`), you can embed a
@@ -739,8 +764,9 @@ Pass both on `withCodeRifts({ …, onEvent, monitoringSinkWired: true })`, or on
   host commits. Closing that needs a host-side conditional write (compare-and-swap on a version
   token) — this package never writes, and reports `conditional_write` as a host assertion it
   cannot verify. Opt-in **`requireExecutionStateMatch`** (`false` / `'warn'` / `true`) can
-  recheck the execution-time fingerprint before the factory (warn = telemetry via
-  `execution_state_drift_observed`; true = block with `EXECUTION_STATE_DRIFT`) — a detection or
+  recheck the execution-time fingerprint before the factory (warn = loud
+  `execution_state_drift_observed` on real drift / quiet `execution_state_unmeasurable` when
+  nothing to measure; true = block with `EXECUTION_STATE_DRIFT`) — a detection or
   enforcement aid, **not** a full TOCTOU closure. See the subsection above.
 - **Retry-safe** — `executionAttempted` is the only safe-to-retry signal; a post-authorization throw
   is `executionAttempted:true` (the remote side effect may have landed).

package/dist/cjs/cas-adapters/api.d.ts

@@ -0,0 +1,94 @@
+/**
+ * HTTP/API CAS adapter — ETag (If-Match) token discipline over host-injected I/O.
+ *
+ * Uses executeIfUnchanged (conditional-write.ts). Does not invent a parallel outcome shape.
+ * Token format is opaque to the guard (string equality only).
+ *
+ * Token encoding (this adapter only; not interpreted by the core):
+ *   api:v1:<raw_etag_or_version_header_value>
+ * Missing / empty ETag → API_ABSENT_TOKEN.
+ *
+ * HONESTY: this adapter does NOT perform HTTP. The host callback MUST send If-Match (or
+ * equivalent) itself. The adapter only normalizes tokens and maps the host-reported
+ * {committed|precondition_failed} onto ExecuteIfUnchangedOutcome. Same class as
+ * conditional_write_is_host_asserted_not_cas_verified — the package never claims it sent
+ * the header.
+ *
+ * No fetch/undici — all I/O is host-injected.
+ */
+import { tokensEqual, type ExecuteIfUnchangedOutcome, type VersionToken } from '../conditional-write.js';
+/** Prefix for this adapter's opaque tokens (equality-only outside this module). */
+export declare const API_VERSION_TOKEN_PREFIX = "api:v1:";
+/**
+ * Token used when the resource has no ETag / version header yet (or host reported null).
+ * Hosts that measured absence should pass this as expected_token for create-if-absent CAS.
+ */
+export declare const API_ABSENT_TOKEN: VersionToken;
+/**
+ * Build a VersionToken from a host-supplied ETag or version-header value.
+ * null / undefined / empty / whitespace-only → API_ABSENT_TOKEN.
+ * Surrounding weak/strong quote marks are stripped once for stable equality.
+ */
+export declare function createApiVersionToken(etag: string | null | undefined): VersionToken;
+/** Raw value embedded in an api:v1: token (for host If-Match headers). Absent → null. */
+export declare function apiTokenRaw(token: VersionToken | null | undefined): string | null;
+/**
+ * Host report after attempting a conditional write.
+ * The host is responsible for sending If-Match / If-None-Match / equivalent.
+ */
+export type ApiHostWriteReport<T = unknown> = {
+    status: 'committed';
+    /** New ETag after write when the server returned one; null/omit when unknown. */
+    new_etag?: string | null;
+    result?: T;
+} | {
+    status: 'precondition_failed';
+    /** Current ETag if the host observed one (e.g. from 412 body / re-GET); omit → null. */
+    current_etag?: string | null;
+};
+export type WriteApiIfUnchangedArgs<T = unknown> = {
+    /** Token measured before the host decided to write (from createApiVersionToken). */
+    expected_token: VersionToken;
+    /**
+     * Re-read the resource ETag (or equivalent version header).
+     * Called by executeIfUnchanged before write and again after write when detect is on.
+     */
+    current_etag: () => string | null | Promise<string | null>;
+    /**
+     * Host performs the conditional HTTP write.
+     * `if_match` is the raw expected ETag for the If-Match header (null when ABSENT).
+     * Adapter does not send the request — host must.
+     */
+    write: (ctx: {
+        if_match: string | null;
+        expected_token: VersionToken;
+    }) => ApiHostWriteReport<T> | Promise<ApiHostWriteReport<T>>;
+    /**
+     * Opt-in post-commit detection (default false — byte-identical when off).
+     * Requires a meaningful intended post-ETag: when the host omits new_etag on success,
+     * detection is a no-op (cannot know intended post state without inventing tokens).
+     */
+    detect_stale_during_commit?: boolean;
+};
+export type ApiWriteResult<T = unknown> = {
+    new_etag: string | null;
+    result: T | undefined;
+};
+/**
+ * Conditional API write: re-read ETag; if token matches expected → host write with If-Match context.
+ *
+ * Mapping (host report → ExecuteIfUnchangedOutcome):
+ *   committed (+ optional new_etag)     → committed (version_token = expected; result carries new_etag)
+ *   precondition_failed (412 class)     → refused / stale_version_token
+ *                                         current_token from current_etag when host supplied it,
+ *                                         else null (no invented token)
+ *
+ * Missing new_etag on success: stored as null on result; detect_stale_during_commit is a no-op
+ * unless new_etag is a non-empty string (honest — no ABSENT fabrication as "expected after").
+ *
+ * Wired through executeIfUnchanged — not a parallel path.
+ */
+export declare function writeApiIfUnchanged<T = unknown>(args: WriteApiIfUnchangedArgs<T>): Promise<ExecuteIfUnchangedOutcome<ApiWriteResult<T>>>;
+/** Re-export equality helper for hosts comparing tokens without importing core module. */
+export { tokensEqual };
+//# sourceMappingURL=api.d.ts.map

package/dist/cjs/cas-adapters/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/cas-adapters/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,EAGL,WAAW,EACX,KAAK,yBAAyB,EAC9B,KAAK,YAAY,EAClB,MAAM,yBAAyB,CAAC;AAEjC,mFAAmF;AACnF,eAAO,MAAM,wBAAwB,YAAY,CAAC;AAElD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,YAA8B,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC9B,YAAY,CAWd;AAED,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAKjF;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,GAAG,OAAO,IACtC;IACE,MAAM,EAAE,WAAW,CAAC;IACpB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,EAAE,CAAC,CAAC;CACZ,GACD;IACE,MAAM,EAAE,qBAAqB,CAAC;IAC9B,wFAAwF;IACxF,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,CAAC;AAEN,MAAM,MAAM,uBAAuB,CAAC,CAAC,GAAG,OAAO,IAAI;IACjD,oFAAoF;IACpF,cAAc,EAAE,YAAY,CAAC;IAC7B;;;OAGG;IACH,YAAY,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC3D;;;;OAIG;IACH,KAAK,EAAE,CAAC,GAAG,EAAE;QACX,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,cAAc,EAAE,YAAY,CAAC;KAC9B,KAAK,kBAAkB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D;;;;OAIG;IACH,0BAA0B,CAAC,EAAE,OAAO,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,OAAO,IAAI;IACxC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,CAAC,GAAG,SAAS,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EACnD,IAAI,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAC/B,OAAO,CAAC,yBAAyB,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CA8CvD;AAED,0FAA0F;AAC1F,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/cjs/cas-adapters/api.js

@@ -0,0 +1,120 @@
+/**
+ * HTTP/API CAS adapter — ETag (If-Match) token discipline over host-injected I/O.
+ *
+ * Uses executeIfUnchanged (conditional-write.ts). Does not invent a parallel outcome shape.
+ * Token format is opaque to the guard (string equality only).
+ *
+ * Token encoding (this adapter only; not interpreted by the core):
+ *   api:v1:<raw_etag_or_version_header_value>
+ * Missing / empty ETag → API_ABSENT_TOKEN.
+ *
+ * HONESTY: this adapter does NOT perform HTTP. The host callback MUST send If-Match (or
+ * equivalent) itself. The adapter only normalizes tokens and maps the host-reported
+ * {committed|precondition_failed} onto ExecuteIfUnchangedOutcome. Same class as
+ * conditional_write_is_host_asserted_not_cas_verified — the package never claims it sent
+ * the header.
+ *
+ * No fetch/undici — all I/O is host-injected.
+ */
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tokensEqual = exports.API_ABSENT_TOKEN = exports.API_VERSION_TOKEN_PREFIX = void 0;
+exports.createApiVersionToken = createApiVersionToken;
+exports.apiTokenRaw = apiTokenRaw;
+exports.writeApiIfUnchanged = writeApiIfUnchanged;
+const conditional_write_js_1 = require("../conditional-write.js");
+Object.defineProperty(exports, "tokensEqual", { enumerable: true, get: function () { return conditional_write_js_1.tokensEqual; } });
+/** Prefix for this adapter's opaque tokens (equality-only outside this module). */
+exports.API_VERSION_TOKEN_PREFIX = 'api:v1:';
+/**
+ * Token used when the resource has no ETag / version header yet (or host reported null).
+ * Hosts that measured absence should pass this as expected_token for create-if-absent CAS.
+ */
+exports.API_ABSENT_TOKEN = 'api:v1:absent';
+/**
+ * Build a VersionToken from a host-supplied ETag or version-header value.
+ * null / undefined / empty / whitespace-only → API_ABSENT_TOKEN.
+ * Surrounding weak/strong quote marks are stripped once for stable equality.
+ */
+function createApiVersionToken(etag) {
+    if (etag == null)
+        return exports.API_ABSENT_TOKEN;
+    let s = String(etag).trim();
+    if (s.length === 0)
+        return exports.API_ABSENT_TOKEN;
+    // Strip one layer of optional W/ and quotes: W/"abc" → abc, "abc" → abc
+    if (s.startsWith('W/') || s.startsWith('w/'))
+        s = s.slice(2).trim();
+    if (s.length >= 2 && s.startsWith('"') && s.endsWith('"')) {
+        s = s.slice(1, -1);
+    }
+    if (s.length === 0)
+        return exports.API_ABSENT_TOKEN;
+    return `${exports.API_VERSION_TOKEN_PREFIX}${s}`;
+}
+/** Raw value embedded in an api:v1: token (for host If-Match headers). Absent → null. */
+function apiTokenRaw(token) {
+    if (typeof token !== 'string' || !token.startsWith(exports.API_VERSION_TOKEN_PREFIX))
+        return null;
+    if (token === exports.API_ABSENT_TOKEN)
+        return null;
+    const raw = token.slice(exports.API_VERSION_TOKEN_PREFIX.length);
+    return raw.length > 0 ? raw : null;
+}
+/**
+ * Conditional API write: re-read ETag; if token matches expected → host write with If-Match context.
+ *
+ * Mapping (host report → ExecuteIfUnchangedOutcome):
+ *   committed (+ optional new_etag)     → committed (version_token = expected; result carries new_etag)
+ *   precondition_failed (412 class)     → refused / stale_version_token
+ *                                         current_token from current_etag when host supplied it,
+ *                                         else null (no invented token)
+ *
+ * Missing new_etag on success: stored as null on result; detect_stale_during_commit is a no-op
+ * unless new_etag is a non-empty string (honest — no ABSENT fabrication as "expected after").
+ *
+ * Wired through executeIfUnchanged — not a parallel path.
+ */
+async function writeApiIfUnchanged(args) {
+    const detect = args.detect_stale_during_commit === true;
+    return (0, conditional_write_js_1.executeIfUnchanged)({
+        expected_token: args.expected_token,
+        current_token: async () => createApiVersionToken(await args.current_etag()),
+        detect_stale_during_commit: detect,
+        expected_after_commit: detect
+            ? async (written) => {
+                if (typeof written.new_etag === 'string' && written.new_etag.trim().length > 0) {
+                    return createApiVersionToken(written.new_etag);
+                }
+                // No intended post-ETag: return live re-read so tokensEqual is tautological (detect no-op).
+                return createApiVersionToken(await args.current_etag());
+            }
+            : undefined,
+        write: async () => {
+            const report = await args.write({
+                if_match: apiTokenRaw(args.expected_token),
+                expected_token: args.expected_token,
+            });
+            if (!report || typeof report !== 'object') {
+                throw new Error('writeApiIfUnchanged: host write must return ApiHostWriteReport');
+            }
+            if (report.status === 'precondition_failed') {
+                const cur = report.current_etag !== undefined
+                    ? createApiVersionToken(report.current_etag)
+                    : null;
+                throw new conditional_write_js_1.StaleVersionTokenAbort(cur);
+            }
+            if (report.status !== 'committed') {
+                throw new Error(`writeApiIfUnchanged: unknown host report status ${String(report.status)}`);
+            }
+            const new_etag = report.new_etag === undefined || report.new_etag === null
+                ? null
+                : String(report.new_etag);
+            return {
+                new_etag,
+                result: report.result,
+            };
+        },
+    });
+}
+//# sourceMappingURL=api.js.map

package/dist/cjs/cas-adapters/api.js.map

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

package/dist/cjs/cas-adapters/db.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Database optimistic-lock CAS adapter — version-column / rowversion discipline over host-injected I/O.
+ *
+ * Uses executeIfUnchanged (conditional-write.ts). Does not invent a parallel outcome shape.
+ * Token format is opaque to the guard (string equality only).
+ *
+ * Token encoding (this adapter only; not interpreted by the core):
+ *   db:v1:<version_column_value>
+ * Missing / empty version → DB_ABSENT_TOKEN.
+ *
+ * HONESTY: this adapter never composes SQL and never opens a connection. The host callback
+ * performs the UPDATE … WHERE version = $expected (or equivalent) and reports rows_affected
+ * or an explicit committed/conflict shape. Same honesty class as host-asserted conditional write.
+ *
+ * No pg/mysql/sqlite drivers — all I/O is host-injected.
+ */
+import { tokensEqual, type ExecuteIfUnchangedOutcome, type VersionToken } from '../conditional-write.js';
+/** Prefix for this adapter's opaque tokens (equality-only outside this module). */
+export declare const DB_VERSION_TOKEN_PREFIX = "db:v1:";
+/**
+ * Token used when the row has no version yet (insert path) or host reported null.
+ * Hosts that measured absence should pass this as expected_token for first write.
+ */
+export declare const DB_ABSENT_TOKEN: VersionToken;
+/**
+ * Build a VersionToken from a host-read version column / rowversion / xmin-style value.
+ * null / undefined / empty → DB_ABSENT_TOKEN. Numbers are stringified (no format invention).
+ */
+export declare function createDbVersionToken(version: string | number | bigint | null | undefined): VersionToken;
+/** Raw version embedded in a db:v1: token (for host SQL bind params). Absent → null. */
+export declare function dbTokenRaw(token: VersionToken | null | undefined): string | null;
+/**
+ * Host report after attempting an optimistic-lock write.
+ * Prefer rows_affected (UPDATE … WHERE version = $expected) or explicit committed/conflict.
+ */
+export type DbHostWriteReport<T = unknown> = {
+    status: 'committed';
+    /** Version after write when the host can report it; null/omit when unknown. */
+    new_version?: string | number | bigint | null;
+    result?: T;
+} | {
+    /** Optimistic lock lost — zero rows updated. */
+    status: 'conflict';
+    /** Current version if the host re-read it; omit → null (no invented token). */
+    current_version?: string | number | bigint | null;
+} | {
+    /**
+     * Alternate committed shape: rows_affected > 0 means committed.
+     * rows_affected === 0 means conflict (mapped to refused).
+     */
+    rows_affected: number;
+    new_version?: string | number | bigint | null;
+    result?: T;
+};
+export type WriteDbIfUnchangedArgs<T = unknown> = {
+    /** Token measured before the host decided to write (from createDbVersionToken). */
+    expected_token: VersionToken;
+    /** Re-read the row version column. Called pre-write and post-write when detect is on. */
+    current_version: () => string | number | bigint | null | Promise<string | number | bigint | null>;
+    /**
+     * Host performs the optimistic-lock mutation (SQL/query builder — never composed here).
+     * Receives the raw expected version for the WHERE clause bind.
+     */
+    write: (ctx: {
+        expected_version: string | null;
+        expected_token: VersionToken;
+    }) => DbHostWriteReport<T> | Promise<DbHostWriteReport<T>>;
+    /**
+     * Opt-in post-commit detection (default false).
+     * When host omits new_version on success, detection is a no-op (cannot know intended post state).
+     */
+    detect_stale_during_commit?: boolean;
+};
+export type DbWriteResult<T = unknown> = {
+    new_version: string | null;
+    result: T | undefined;
+    rows_affected?: number;
+};
+/**
+ * Conditional DB write: re-read version; if token matches → host optimistic-lock write.
+ *
+ * Mapping (host report → ExecuteIfUnchangedOutcome):
+ *   committed / rows_affected > 0     → committed
+ *   conflict / rows_affected === 0    → refused / stale_version_token
+ *                                       current_token from current_version when supplied,
+ *                                       else null (no invented token)
+ *
+ * Wired through executeIfUnchanged — not a parallel path. Never composes SQL.
+ */
+export declare function writeDbIfUnchanged<T = unknown>(args: WriteDbIfUnchangedArgs<T>): Promise<ExecuteIfUnchangedOutcome<DbWriteResult<T>>>;
+/** Re-export equality helper for hosts comparing tokens without importing core module. */
+export { tokensEqual };
+//# sourceMappingURL=db.d.ts.map

package/dist/cjs/cas-adapters/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../../src/cas-adapters/db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAGL,WAAW,EACX,KAAK,yBAAyB,EAC9B,KAAK,YAAY,EAClB,MAAM,yBAAyB,CAAC;AAEjC,mFAAmF;AACnF,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,YAA6B,CAAC;AAE5D;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GACnD,YAAY,CAMd;AAED,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAKhF;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,GAAG,OAAO,IACrC;IACE,MAAM,EAAE,WAAW,CAAC;IACpB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC9C,MAAM,CAAC,EAAE,CAAC,CAAC;CACZ,GACD;IACE,gDAAgD;IAChD,MAAM,EAAE,UAAU,CAAC;IACnB,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACnD,GACD;IACE;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC9C,MAAM,CAAC,EAAE,CAAC,CAAC;CACZ,CAAC;AAEN,MAAM,MAAM,sBAAsB,CAAC,CAAC,GAAG,OAAO,IAAI;IAChD,mFAAmF;IACnF,cAAc,EAAE,YAAY,CAAC;IAC7B,yFAAyF;IACzF,eAAe,EAAE,MACb,MAAM,GACN,MAAM,GACN,MAAM,GACN,IAAI,GACJ,OAAO,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7C;;;OAGG;IACH,KAAK,EAAE,CAAC,GAAG,EAAE;QACX,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,cAAc,EAAE,YAAY,CAAC;KAC9B,KAAK,iBAAiB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D;;;OAGG;IACH,0BAA0B,CAAC,EAAE,OAAO,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,OAAO,IAAI;IACvC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,CAAC,GAAG,SAAS,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAwDF;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAClD,IAAI,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAC9B,OAAO,CAAC,yBAAyB,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAuCtD;AAED,0FAA0F;AAC1F,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/cjs/cas-adapters/db.js

@@ -0,0 +1,139 @@
+/**
+ * Database optimistic-lock CAS adapter — version-column / rowversion discipline over host-injected I/O.
+ *
+ * Uses executeIfUnchanged (conditional-write.ts). Does not invent a parallel outcome shape.
+ * Token format is opaque to the guard (string equality only).
+ *
+ * Token encoding (this adapter only; not interpreted by the core):
+ *   db:v1:<version_column_value>
+ * Missing / empty version → DB_ABSENT_TOKEN.
+ *
+ * HONESTY: this adapter never composes SQL and never opens a connection. The host callback
+ * performs the UPDATE … WHERE version = $expected (or equivalent) and reports rows_affected
+ * or an explicit committed/conflict shape. Same honesty class as host-asserted conditional write.
+ *
+ * No pg/mysql/sqlite drivers — all I/O is host-injected.
+ */
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tokensEqual = exports.DB_ABSENT_TOKEN = exports.DB_VERSION_TOKEN_PREFIX = void 0;
+exports.createDbVersionToken = createDbVersionToken;
+exports.dbTokenRaw = dbTokenRaw;
+exports.writeDbIfUnchanged = writeDbIfUnchanged;
+const conditional_write_js_1 = require("../conditional-write.js");
+Object.defineProperty(exports, "tokensEqual", { enumerable: true, get: function () { return conditional_write_js_1.tokensEqual; } });
+/** Prefix for this adapter's opaque tokens (equality-only outside this module). */
+exports.DB_VERSION_TOKEN_PREFIX = 'db:v1:';
+/**
+ * Token used when the row has no version yet (insert path) or host reported null.
+ * Hosts that measured absence should pass this as expected_token for first write.
+ */
+exports.DB_ABSENT_TOKEN = 'db:v1:absent';
+/**
+ * Build a VersionToken from a host-read version column / rowversion / xmin-style value.
+ * null / undefined / empty → DB_ABSENT_TOKEN. Numbers are stringified (no format invention).
+ */
+function createDbVersionToken(version) {
+    if (version == null)
+        return exports.DB_ABSENT_TOKEN;
+    if (typeof version === 'number' && !Number.isFinite(version))
+        return exports.DB_ABSENT_TOKEN;
+    const s = String(version).trim();
+    if (s.length === 0)
+        return exports.DB_ABSENT_TOKEN;
+    return `${exports.DB_VERSION_TOKEN_PREFIX}${s}`;
+}
+/** Raw version embedded in a db:v1: token (for host SQL bind params). Absent → null. */
+function dbTokenRaw(token) {
+    if (typeof token !== 'string' || !token.startsWith(exports.DB_VERSION_TOKEN_PREFIX))
+        return null;
+    if (token === exports.DB_ABSENT_TOKEN)
+        return null;
+    const raw = token.slice(exports.DB_VERSION_TOKEN_PREFIX.length);
+    return raw.length > 0 ? raw : null;
+}
+function normalizeDbReport(report) {
+    if ('rows_affected' in report && typeof report.rows_affected === 'number') {
+        const r = report;
+        if (r.rows_affected === 0) {
+            return {
+                kind: 'conflict',
+                new_version: undefined,
+                current_version: undefined,
+                rows_affected: 0,
+            };
+        }
+        return {
+            kind: 'committed',
+            new_version: r.new_version,
+            result: r.result,
+            rows_affected: r.rows_affected,
+        };
+    }
+    if ('status' in report && report.status === 'conflict') {
+        const r = report;
+        return {
+            kind: 'conflict',
+            new_version: undefined,
+            current_version: r.current_version,
+        };
+    }
+    if ('status' in report && report.status === 'committed') {
+        const r = report;
+        return {
+            kind: 'committed',
+            new_version: r.new_version,
+            result: r.result,
+        };
+    }
+    throw new Error('writeDbIfUnchanged: host write must return DbHostWriteReport');
+}
+/**
+ * Conditional DB write: re-read version; if token matches → host optimistic-lock write.
+ *
+ * Mapping (host report → ExecuteIfUnchangedOutcome):
+ *   committed / rows_affected > 0     → committed
+ *   conflict / rows_affected === 0    → refused / stale_version_token
+ *                                       current_token from current_version when supplied,
+ *                                       else null (no invented token)
+ *
+ * Wired through executeIfUnchanged — not a parallel path. Never composes SQL.
+ */
+async function writeDbIfUnchanged(args) {
+    const detect = args.detect_stale_during_commit === true;
+    return (0, conditional_write_js_1.executeIfUnchanged)({
+        expected_token: args.expected_token,
+        current_token: async () => createDbVersionToken(await args.current_version()),
+        detect_stale_during_commit: detect,
+        expected_after_commit: detect
+            ? async (written) => {
+                if (typeof written.new_version === 'string' && written.new_version.trim().length > 0) {
+                    return createDbVersionToken(written.new_version);
+                }
+                return createDbVersionToken(await args.current_version());
+            }
+            : undefined,
+        write: async () => {
+            const report = await args.write({
+                expected_version: dbTokenRaw(args.expected_token),
+                expected_token: args.expected_token,
+            });
+            const norm = normalizeDbReport(report);
+            if (norm.kind === 'conflict') {
+                const cur = norm.current_version !== undefined
+                    ? createDbVersionToken(norm.current_version)
+                    : null;
+                throw new conditional_write_js_1.StaleVersionTokenAbort(cur);
+            }
+            const new_version = norm.new_version === undefined || norm.new_version === null
+                ? null
+                : String(norm.new_version);
+            return {
+                new_version,
+                result: norm.result,
+                rows_affected: norm.rows_affected,
+            };
+        },
+    });
+}
+//# sourceMappingURL=db.js.map

package/dist/cjs/cas-adapters/db.js.map

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

package/dist/cjs/cas-adapters/registry.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Registry compareAndSwap CAS adapter — opaque registry/version token discipline over host-injected I/O.
+ *
+ * Uses executeIfUnchanged (conditional-write.ts). Does not invent a parallel outcome shape.
+ * Token format is opaque to the guard (string equality only).
+ *
+ * Token encoding (this adapter only; not interpreted by the core):
+ *   registry:v1:<host_registry_token>
+ * Missing / empty token → REGISTRY_ABSENT_TOKEN.
+ *
+ * HONESTY: this adapter never talks to a registry client. The host callback performs
+ * compareAndSwap(expected, newValue) (or equivalent) and reports {swapped|conflict}.
+ * The adapter only normalizes tokens and maps the report onto ExecuteIfUnchangedOutcome.
+ *
+ * No registry SDKs — all I/O is host-injected.
+ */
+import { tokensEqual, type ExecuteIfUnchangedOutcome, type VersionToken } from '../conditional-write.js';
+/** Prefix for this adapter's opaque tokens (equality-only outside this module). */
+export declare const REGISTRY_VERSION_TOKEN_PREFIX = "registry:v1:";
+/**
+ * Token used when the registry key is absent / unversioned.
+ * Hosts that measured absence should pass this as expected_token for first put.
+ */
+export declare const REGISTRY_ABSENT_TOKEN: VersionToken;
+/**
+ * Build a VersionToken from a host registry revision / generation / etag-like value.
+ * null / undefined / empty → REGISTRY_ABSENT_TOKEN.
+ */
+export declare function createRegistryVersionToken(token: string | number | bigint | null | undefined): VersionToken;
+/** Raw value embedded in a registry:v1: token (for host CAS APIs). Absent → null. */
+export declare function registryTokenRaw(token: VersionToken | null | undefined): string | null;
+/**
+ * Host report after compareAndSwap (or equivalent).
+ */
+export type RegistryHostCasReport<T = unknown> = {
+    swapped: true;
+    /** New registry token after successful swap; null/omit when unknown. */
+    new_token?: string | number | bigint | null;
+    result?: T;
+} | {
+    swapped: false;
+    /** Current token if observed on conflict; omit → null (no invented token). */
+    current_token?: string | number | bigint | null;
+} | {
+    status: 'committed';
+    new_token?: string | number | bigint | null;
+    result?: T;
+} | {
+    status: 'conflict';
+    current_token?: string | number | bigint | null;
+};
+export type WriteRegistryIfUnchangedArgs<T = unknown> = {
+    /** Token measured before the host decided to write (from createRegistryVersionToken). */
+    expected_token: VersionToken;
+    /** Re-read the registry key's current token. Pre-write and post-write when detect is on. */
+    current_token: () => string | number | bigint | null | Promise<string | number | bigint | null>;
+    /**
+     * Host compareAndSwap. Receives the raw expected token for the CAS call.
+     * Adapter does not invoke any registry client.
+     */
+    compareAndSwap: (ctx: {
+        expected: string | null;
+        expected_token: VersionToken;
+    }) => RegistryHostCasReport<T> | Promise<RegistryHostCasReport<T>>;
+    /**
+     * Opt-in post-commit detection (default false).
+     * When host omits new_token on success, detection is a no-op.
+     */
+    detect_stale_during_commit?: boolean;
+};
+export type RegistryWriteResult<T = unknown> = {
+    new_token: string | null;
+    result: T | undefined;
+};
+/**
+ * Conditional registry write: re-read token; if matches → host compareAndSwap.
+ *
+ * Mapping (host report → ExecuteIfUnchangedOutcome):
+ *   swapped:true / status:committed   → committed
+ *   swapped:false / status:conflict   → refused / stale_version_token
+ *                                       current_token from host when supplied, else null
+ *
+ * Wired through executeIfUnchanged — not a parallel path.
+ */
+export declare function writeRegistryIfUnchanged<T = unknown>(args: WriteRegistryIfUnchangedArgs<T>): Promise<ExecuteIfUnchangedOutcome<RegistryWriteResult<T>>>;
+/** Re-export equality helper for hosts comparing tokens without importing core module. */
+export { tokensEqual };
+//# sourceMappingURL=registry.d.ts.map

package/dist/cjs/cas-adapters/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/cas-adapters/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAGL,WAAW,EACX,KAAK,yBAAyB,EAC9B,KAAK,YAAY,EAClB,MAAM,yBAAyB,CAAC;AAEjC,mFAAmF;AACnF,eAAO,MAAM,6BAA6B,iBAAiB,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,YAAmC,CAAC;AAExE;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GACjD,YAAY,CAMd;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAOtF;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,CAAC,CAAC,GAAG,OAAO,IACzC;IACE,OAAO,EAAE,IAAI,CAAC;IACd,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5C,MAAM,CAAC,EAAE,CAAC,CAAC;CACZ,GACD;IACE,OAAO,EAAE,KAAK,CAAC;IACf,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACjD,GACD;IACE,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5C,MAAM,CAAC,EAAE,CAAC,CAAC;CACZ,GACD;IACE,MAAM,EAAE,UAAU,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACjD,CAAC;AAEN,MAAM,MAAM,4BAA4B,CAAC,CAAC,GAAG,OAAO,IAAI;IACtD,yFAAyF;IACzF,cAAc,EAAE,YAAY,CAAC;IAC7B,4FAA4F;IAC5F,aAAa,EAAE,MACX,MAAM,GACN,MAAM,GACN,MAAM,GACN,IAAI,GACJ,OAAO,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7C;;;OAGG;IACH,cAAc,EAAE,CAAC,GAAG,EAAE;QACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,cAAc,EAAE,YAAY,CAAC;KAC9B,KAAK,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC;IACnE;;;OAGG;IACH,0BAA0B,CAAC,EAAE,OAAO,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,mBAAmB,CAAC,CAAC,GAAG,OAAO,IAAI;IAC7C,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,CAAC,GAAG,SAAS,CAAC;CACvB,CAAC;AA0BF;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAAC,CAAC,GAAG,OAAO,EACxD,IAAI,EAAE,4BAA4B,CAAC,CAAC,CAAC,GACpC,OAAO,CAAC,yBAAyB,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,CAsC5D;AAED,0FAA0F;AAC1F,OAAO,EAAE,WAAW,EAAE,CAAC"}