@coderifts/agent-guard 6.1.0 → 6.3.0

package/dist/esm/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/esm/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/esm/cas-adapters/api.js

@@ -0,0 +1,116 @@
+/**
+ * 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';
+import { executeIfUnchanged, StaleVersionTokenAbort, tokensEqual, } from '../conditional-write.js';
+/** Prefix for this adapter's opaque tokens (equality-only outside this module). */
+export 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 const 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.
+ */
+export function createApiVersionToken(etag) {
+    if (etag == null)
+        return API_ABSENT_TOKEN;
+    let s = String(etag).trim();
+    if (s.length === 0)
+        return 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 API_ABSENT_TOKEN;
+    return `${API_VERSION_TOKEN_PREFIX}${s}`;
+}
+/** Raw value embedded in an api:v1: token (for host If-Match headers). Absent → null. */
+export function apiTokenRaw(token) {
+    if (typeof token !== 'string' || !token.startsWith(API_VERSION_TOKEN_PREFIX))
+        return null;
+    if (token === API_ABSENT_TOKEN)
+        return null;
+    const raw = token.slice(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.
+ */
+export async function writeApiIfUnchanged(args) {
+    const detect = args.detect_stale_during_commit === true;
+    return 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 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,
+            };
+        },
+    });
+}
+/** Re-export equality helper for hosts comparing tokens without importing core module. */
+export { tokensEqual };
+//# sourceMappingURL=api.js.map

package/dist/esm/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/esm/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/esm/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/esm/cas-adapters/db.js

@@ -0,0 +1,135 @@
+/**
+ * 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';
+import { executeIfUnchanged, StaleVersionTokenAbort, tokensEqual, } from '../conditional-write.js';
+/** Prefix for this adapter's opaque tokens (equality-only outside this module). */
+export 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 const 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).
+ */
+export function createDbVersionToken(version) {
+    if (version == null)
+        return DB_ABSENT_TOKEN;
+    if (typeof version === 'number' && !Number.isFinite(version))
+        return DB_ABSENT_TOKEN;
+    const s = String(version).trim();
+    if (s.length === 0)
+        return DB_ABSENT_TOKEN;
+    return `${DB_VERSION_TOKEN_PREFIX}${s}`;
+}
+/** Raw version embedded in a db:v1: token (for host SQL bind params). Absent → null. */
+export function dbTokenRaw(token) {
+    if (typeof token !== 'string' || !token.startsWith(DB_VERSION_TOKEN_PREFIX))
+        return null;
+    if (token === DB_ABSENT_TOKEN)
+        return null;
+    const raw = token.slice(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.
+ */
+export async function writeDbIfUnchanged(args) {
+    const detect = args.detect_stale_during_commit === true;
+    return 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 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,
+            };
+        },
+    });
+}
+/** Re-export equality helper for hosts comparing tokens without importing core module. */
+export { tokensEqual };
+//# sourceMappingURL=db.js.map

package/dist/esm/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/esm/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/esm/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"}