@coderifts/agent-guard 6.1.0 → 6.3.0

package/README.md

@@ -22,7 +22,11 @@ stays free of git/fs. Production PR artifact derivation:
 
 **TOCTOU is unclosed.** Resolving content proves what was true *at measurement time*;
 a host that then writes unconditionally still races. Neither the example nor this
-package supplies a version token or conditional write.
+package supplies a version token or conditional write. An **opt-in** execution-state
+recheck can *detect* (or enforce against) drift between the authorized change set and
+the artifacts still held at execute time — see **`requireExecutionStateMatch`** below.
+That is a detection/enforcement aid for the residual race, **not** a full TOCTOU
+closure (hosts that write unconditionally still race; conditional write remains host-side).
 
 ```typescript
 import { guardToolCall } from '@coderifts/agent-guard';
@@ -49,6 +53,58 @@ if (!outcome.executed) console.error('blocked:', outcome.verdict);
 // Retry ONLY when outcome.executionAttempted === false (the safe-to-retry signal).
 ```
 
+#### `requireExecutionStateMatch` — opt-in execution-state recheck (ID842)
+
+After a fully enforceable ALLOW/MONITOR decision and **immediately before** `executeFactory`,
+the guard can recompute the execution-time change-set fingerprint (crbundle.v1 over the
+**current** `artifacts[]` the guard already holds) and compare it to what the receipt
+authorized. Config field on `GuardConfig` (tri-state):
+
+```ts
+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. |
+
+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.
+
+Warn-mode event (host-side only; the guard does **not** phone home), on `GuardConfig.onEvent`:
+
+```ts
+{
+  type: 'execution_state_drift_observed';
+  at: string;                         // ISO timestamp
+  decisionId?: string;
+  current_fingerprint: string | null;
+  authorized_fingerprint: string | null;
+  reason: string;
+}
+```
+
+```typescript
+const outcome = await guardToolCall(call, executeFactory, {
+  client,
+  operation: 'merge',
+  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
+      console.warn('execution-state drift', e.decisionId, e.reason, e.current_fingerprint);
+    }
+  },
+});
+```
+
+Honesty: this aids **detection** (warn) or **hard stop** (enforce) for execution-state
+mismatch at the guard boundary. It does **not** close TOCTOU proper — measurement-to-commit
+and host-side unconditional writes remain; see Guarantees.
+
 > **Supply `artifacts[]` with content.** If the guard detects a contract change (e.g. from
 > `filesTouched`/`diff`) but you did **not** supply `artifacts[]` with `before`/`after`, it fails
 > closed **locally** with `outcome.verdict.cause === 'MISSING_ARTIFACT_CONTENT'` — the tool does not
@@ -91,6 +147,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
@@ -682,7 +745,10 @@ Pass both on `withCodeRifts({ …, onEvent, monitoringSinkWired: true })`, or on
   measurement-to-commit race remains: content resolved at measurement time can change before the
   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.
+  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
+  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).
 - **`enforced:true` only on a LIVE, receipt-verified `ALLOW`/`MONITOR`** — never on cached/LKG,

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/fs.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Filesystem CAS adapter — mtime + content-hash VersionToken and atomic-rename write.
+ *
+ * Uses the host contract helper 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):
+ *   fs:v1:<mtime_ms>:<sha256_hex_of_file_bytes>
+ * Missing file → createFsVersionToken still works for "absent" via a dedicated absent token
+ * only if we choose; for create we require the file to exist (ENOENT throws) so hosts
+ * measure an existing prior. For write of new files, expected_token may be ABSENT_TOKEN.
+ */
+import { tokensEqual, type ExecuteIfUnchangedOutcome, type VersionToken, type VersionedContent } from '../conditional-write.js';
+import type { PriorContentResolver } from '../freshness.js';
+/** Prefix for this adapter's opaque tokens (equality-only outside this module). */
+export declare const FS_VERSION_TOKEN_PREFIX = "fs:v1:";
+/**
+ * Token used when the path does not exist yet (create-if-absent CAS).
+ * Hosts that measured absence should pass this as expected_token for first write.
+ */
+export declare const FS_ABSENT_TOKEN: VersionToken;
+/** Extract content-hash segment from an fs:v1 token (null if absent/malformed). */
+export declare function fsTokenContentHash(token: VersionToken | null | undefined): string | null;
+/**
+ * Build a VersionToken from path: mtime (ms) + sha256 of file bytes.
+ * Throws on I/O errors other than callers may catch. ENOENT → returns FS_ABSENT_TOKEN
+ * so hosts can CAS create vs create-raced.
+ */
+export declare function createFsVersionToken(filePath: string): Promise<VersionToken>;
+/**
+ * Read file content + version token for VersionedContent (host reporting / preflight prior).
+ * ENOENT → content '' and FS_ABSENT_TOKEN.
+ */
+export declare function readVersionedFile(filePath: string): Promise<VersionedContent>;
+export type WriteFileIfUnchangedArgs = {
+    path: string;
+    /** Token measured before the host decided to write (from createFsVersionToken). */
+    expected_token: VersionToken;
+    /** Full new file contents (utf8 string or Buffer). */
+    content: string | Buffer;
+};
+/**
+ * Conditional write: re-stat+re-hash; if token matches expected → temp file + atomic rename.
+ *
+ * MEASURED windows (pre-fix, 2fcd74e-era):
+ *   1. executeIfUnchanged: current_token() then await write() — no re-check in between.
+ *   2. write(): writeFile(tmp) then rename(tmp,target) with NO re-stat of target before rename
+ *      (fs.ts former lines 106–108) — concurrent mutation of target is clobbered by rename.
+ *
+ * Closures:
+ *   - Pre-rename: re-createFsVersionToken(target); on mismatch abort rename, unlink tmp,
+ *     throw StaleVersionTokenAbort → refused/stale_version_token (write did not land).
+ *   - Post-rename: detect_stale_during_commit — content-hash of path must match sha256(body);
+ *     mismatch → committed_stale_detected (write landed; someone overwrote after rename).
+ *
+ * Wired through executeIfUnchanged — not a parallel path.
+ */
+export declare function writeFileIfUnchanged(args: WriteFileIfUnchangedArgs): Promise<ExecuteIfUnchangedOutcome<{
+    path: string;
+    bytes: number;
+    written_content_hash: string;
+}>>;
+/**
+ * Opt-in PriorContentResolver that reads a file path from tool arguments.
+ * Returns file utf8 content for freshness measurement (string only — tokens travel separately
+ * via versioned_content / conditioned_on_token on the call context).
+ *
+ * Plug-in: pass as GuardConfig.resolvePriorContent / withCodeRifts({ resolvePriorContent }).
+ */
+export declare function createFsPriorContentResolver(options?: {
+    /**
+     * Map artifactId → absolute or relative file path.
+     * If omitted, uses req.path or arguments-style path when provided on the resolve request.
+     */
+    pathForArtifact?: (artifactId: string) => string | null | undefined;
+}): PriorContentResolver;
+/** Re-export equality helper for hosts comparing tokens without importing core module. */
+export { tokensEqual };
+//# sourceMappingURL=fs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../../src/cas-adapters/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,OAAO,EAGL,WAAW,EACX,KAAK,yBAAyB,EAC9B,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,mFAAmF;AACnF,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,YAA6B,CAAC;AAM5D,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAQxF;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAmBlF;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAOnF;AAED,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,cAAc,EAAE,YAAY,CAAC;IAC7B,sDAAsD;IACtD,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,yBAAyB,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,oBAAoB,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAsDnG;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,CAAC,EAAE;IACrD;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACrE,GAAG,oBAAoB,CAoBvB;AAED,0FAA0F;AAC1F,OAAO,EAAE,WAAW,EAAE,CAAC"}