hikoutei 0.2.0

package/dist/infrastructure/storage/sync/shared/syncRegistry.js

@@ -0,0 +1,272 @@
+/**
+ * SQLite registry/allowlist operations for the sync gateway.
+ *
+ * The local registry is the source of truth used to choose a gateway range.
+ * A caller cannot turn an arbitrary tab name into a sync target by merely
+ * passing it to the gateway client.
+ */
+import { withImmediateTransaction } from "../../sqlite/sqliteBridge.js";
+import { STORAGE_ERROR_CODES, StorageError } from "../../errors.js";
+import { withSqlSavepoint } from "../../sqlite/sqlTransaction.js";
+import { isFencingValid, isFencingValidWithSql, } from "./writerLease.js";
+const READ_LOGICAL_SHEET_REGISTRATION_SQL = `
+  SELECT schema_version, ownership_manifest_json, business_key_field, anchor_mode, enabled
+  FROM sheet_registry
+  WHERE sheet_id = ?
+`;
+const INSERT_LOGICAL_SHEET_REGISTRATION_SQL = `
+  INSERT INTO sheet_registry (
+    sheet_id, schema_version, ownership_manifest_json, business_key_field, anchor_mode, enabled
+  ) VALUES (?, ?, ?, ?, ?, 1)
+`;
+const READ_PHYSICAL_SHEET_REGISTRATION_SQL = `
+  SELECT logical_sheet_id, spreadsheet_id, tab_name, registered_range, projection,
+         schema_version, anchor_mode, enabled
+  FROM physical_sheet_registry
+  WHERE physical_sheet_id = ?
+`;
+const INSERT_PHYSICAL_SHEET_REGISTRATION_SQL = `
+  INSERT INTO physical_sheet_registry (
+    physical_sheet_id, logical_sheet_id, spreadsheet_id, tab_name,
+    registered_range, projection, schema_version, anchor_mode, enabled
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 1)
+`;
+const READ_REGISTERED_SYNC_SHEET_SQL = `
+  SELECT physical.logical_sheet_id, physical.physical_sheet_id, physical.spreadsheet_id,
+         physical.tab_name, physical.registered_range, physical.projection,
+         physical.schema_version, physical.anchor_mode, physical.enabled AS physical_enabled,
+         logical.ownership_manifest_json, logical.business_key_field, logical.enabled AS logical_enabled
+  FROM physical_sheet_registry AS physical
+  JOIN sheet_registry AS logical ON logical.sheet_id = physical.logical_sheet_id
+  WHERE physical.physical_sheet_id = ?
+`;
+/**
+ * Registers one logical sheet/projection pair under the current writer fence.
+ *
+ * Repeating an identical registration is idempotent.  Any attempt to reuse a
+ * logical or physical ID with different immutable routing data fails closed.
+ */
+export function registerSyncSheet(db, fence, input) {
+    const normalizedInput = normalizeRegistrationInput(input);
+    validateRegistration(normalizedInput);
+    if (!isFencingValid(db, fence))
+        return { kind: "fenced_out" };
+    return withImmediateTransaction(db, () => {
+        if (!isFencingValid(db, fence))
+            return { kind: "fenced_out" };
+        const logical = db.prepare(READ_LOGICAL_SHEET_REGISTRATION_SQL)
+            .get(normalizedInput.logicalSheetId);
+        if (logical === undefined) {
+            const inserted = db.prepare(INSERT_LOGICAL_SHEET_REGISTRATION_SQL).run(normalizedInput.logicalSheetId, normalizedInput.schemaVersion, normalizedInput.ownershipManifestJson, normalizedInput.businessKeyField, normalizedInput.anchorMode ?? "developer_metadata");
+            if (inserted.changes !== 1) {
+                throw new StorageError(STORAGE_ERROR_CODES.SYNC_REGISTRATION_WRITE_FAILED, "could not register logical sheet");
+            }
+        }
+        else if (!sameLogicalRegistration(logical, normalizedInput)) {
+            throw new StorageError(STORAGE_ERROR_CODES.SYNC_REGISTRATION_CONFLICT, "logical sync sheet registration does not match the existing allowlist");
+        }
+        const physical = db.prepare(READ_PHYSICAL_SHEET_REGISTRATION_SQL)
+            .get(normalizedInput.physicalSheetId);
+        if (physical === undefined) {
+            const inserted = db.prepare(INSERT_PHYSICAL_SHEET_REGISTRATION_SQL).run(normalizedInput.physicalSheetId, normalizedInput.logicalSheetId, normalizedInput.spreadsheetId, normalizedInput.tabName, normalizedInput.registeredRange, normalizedInput.projection, normalizedInput.schemaVersion, normalizedInput.anchorMode ?? "developer_metadata");
+            if (inserted.changes !== 1) {
+                throw new StorageError(STORAGE_ERROR_CODES.SYNC_REGISTRATION_WRITE_FAILED, "could not register physical sheet");
+            }
+        }
+        else if (!samePhysicalRegistration(physical, normalizedInput)) {
+            throw new StorageError(STORAGE_ERROR_CODES.SYNC_REGISTRATION_CONFLICT, "physical sync sheet registration does not match the existing allowlist");
+        }
+        return {
+            kind: "registered",
+            sheet: requireRegisteredSyncSheet(db, normalizedInput.physicalSheetId),
+        };
+    });
+}
+/**
+ * Registers one logical sheet/projection pair through an active async SQL context.
+ *
+ * Call this from the same MikroORM transaction as any related setup state. The
+ * registration and its writer-fence check then use the ORM-owned connection
+ * instead of opening a second SQLite connection.
+ */
+export async function registerSyncSheetWithSql(sql, fence, input) {
+    const normalizedInput = normalizeRegistrationInput(input);
+    validateRegistration(normalizedInput);
+    if (!(await isFencingValidWithSql(sql, fence)))
+        return { kind: "fenced_out" };
+    return withSqlSavepoint(sql, "register_sync_sheet", async () => {
+        if (!(await isFencingValidWithSql(sql, fence)))
+            return { kind: "fenced_out" };
+        const logical = await sql.get(READ_LOGICAL_SHEET_REGISTRATION_SQL, [
+            normalizedInput.logicalSheetId,
+        ]);
+        if (logical === undefined) {
+            const inserted = await sql.run(INSERT_LOGICAL_SHEET_REGISTRATION_SQL, [
+                normalizedInput.logicalSheetId,
+                normalizedInput.schemaVersion,
+                normalizedInput.ownershipManifestJson,
+                normalizedInput.businessKeyField,
+                normalizedInput.anchorMode ?? "developer_metadata",
+            ]);
+            if (inserted.changes !== 1) {
+                throw new StorageError(STORAGE_ERROR_CODES.SYNC_REGISTRATION_WRITE_FAILED, "could not register logical sheet");
+            }
+        }
+        else if (!sameLogicalRegistration(logical, normalizedInput)) {
+            throw new StorageError(STORAGE_ERROR_CODES.SYNC_REGISTRATION_CONFLICT, "logical sync sheet registration does not match the existing allowlist");
+        }
+        const physical = await sql.get(READ_PHYSICAL_SHEET_REGISTRATION_SQL, [
+            normalizedInput.physicalSheetId,
+        ]);
+        if (physical === undefined) {
+            const inserted = await sql.run(INSERT_PHYSICAL_SHEET_REGISTRATION_SQL, [
+                normalizedInput.physicalSheetId,
+                normalizedInput.logicalSheetId,
+                normalizedInput.spreadsheetId,
+                normalizedInput.tabName,
+                normalizedInput.registeredRange,
+                normalizedInput.projection,
+                normalizedInput.schemaVersion,
+                normalizedInput.anchorMode ?? "developer_metadata",
+            ]);
+            if (inserted.changes !== 1) {
+                throw new StorageError(STORAGE_ERROR_CODES.SYNC_REGISTRATION_WRITE_FAILED, "could not register physical sheet");
+            }
+        }
+        else if (!samePhysicalRegistration(physical, normalizedInput)) {
+            throw new StorageError(STORAGE_ERROR_CODES.SYNC_REGISTRATION_CONFLICT, "physical sync sheet registration does not match the existing allowlist");
+        }
+        return {
+            kind: "registered",
+            sheet: await requireRegisteredSyncSheetWithSql(sql, normalizedInput.physicalSheetId),
+        };
+    });
+}
+/** Registers one projection in an adapter-owned MikroORM transaction. */
+export async function registerSyncSheetWithAdapter(storage, fence, input) {
+    return storage.transaction(({ sql }) => registerSyncSheetWithSql(sql, fence, input));
+}
+/** Reads one enabled physical registry entry or rejects any unregistered target. */
+export function requireRegisteredSyncSheet(db, physicalSheetId) {
+    if (physicalSheetId.length === 0) {
+        throw new StorageError(STORAGE_ERROR_CODES.INVALID_SYNC_REGISTRATION, "physical sheet ID is required");
+    }
+    const row = db.prepare(READ_REGISTERED_SYNC_SHEET_SQL)
+        .get(physicalSheetId);
+    return registeredSyncSheetFromRow(row);
+}
+/** Reads one enabled physical registry entry through an active async SQL context. */
+export async function requireRegisteredSyncSheetWithSql(sql, physicalSheetId) {
+    if (physicalSheetId.length === 0) {
+        throw new StorageError(STORAGE_ERROR_CODES.INVALID_SYNC_REGISTRATION, "physical sheet ID is required");
+    }
+    const row = await sql.get(READ_REGISTERED_SYNC_SHEET_SQL, [physicalSheetId]);
+    return registeredSyncSheetFromRow(row);
+}
+/** Reads one enabled physical registry entry through a fresh adapter read context. */
+export async function requireRegisteredSyncSheetWithAdapter(storage, physicalSheetId) {
+    return storage.read(({ sql }) => requireRegisteredSyncSheetWithSql(sql, physicalSheetId));
+}
+function validateRegistration(input) {
+    for (const [label, value] of [
+        ["logical sheet ID", input.logicalSheetId],
+        ["physical sheet ID", input.physicalSheetId],
+        ["spreadsheet ID", input.spreadsheetId],
+        ["tab name", input.tabName],
+        ["registered range", input.registeredRange],
+        ["ownership manifest", input.ownershipManifestJson],
+        ["business key field", input.businessKeyField],
+    ]) {
+        if (value.length === 0) {
+            throw new StorageError(STORAGE_ERROR_CODES.INVALID_SYNC_REGISTRATION, label + " is required");
+        }
+    }
+    if (!Number.isSafeInteger(input.schemaVersion) || input.schemaVersion < 1) {
+        throw new StorageError(STORAGE_ERROR_CODES.INVALID_SYNC_REGISTRATION, "schema version must be a positive safe integer");
+    }
+    if (!isRegisteredProjection(input.projection)) {
+        throw new StorageError(STORAGE_ERROR_CODES.INVALID_SYNC_REGISTRATION, "unsupported sync projection");
+    }
+    if (input.anchorMode !== undefined && input.anchorMode !== "developer_metadata") {
+        throw new StorageError(STORAGE_ERROR_CODES.INVALID_SYNC_REGISTRATION, "v1 sync registry requires developer_metadata anchors");
+    }
+    try {
+        JSON.parse(input.ownershipManifestJson);
+    }
+    catch {
+        throw new StorageError(STORAGE_ERROR_CODES.INVALID_SYNC_REGISTRATION, "ownership manifest must be valid JSON");
+    }
+}
+function normalizeRegistrationInput(input) {
+    return {
+        ...input,
+        registeredRange: normalizeRegisteredRange(input.registeredRange, STORAGE_ERROR_CODES.INVALID_SYNC_REGISTRATION),
+    };
+}
+function sameLogicalRegistration(existing, input) {
+    return existing.schema_version === input.schemaVersion &&
+        existing.ownership_manifest_json === input.ownershipManifestJson &&
+        existing.business_key_field === input.businessKeyField &&
+        existing.anchor_mode === (input.anchorMode ?? "developer_metadata") &&
+        existing.enabled === 1;
+}
+function samePhysicalRegistration(existing, input) {
+    return existing.logical_sheet_id === input.logicalSheetId &&
+        existing.spreadsheet_id === input.spreadsheetId &&
+        existing.tab_name === input.tabName &&
+        existing.registered_range === input.registeredRange &&
+        existing.projection === input.projection &&
+        existing.schema_version === input.schemaVersion &&
+        existing.anchor_mode === (input.anchorMode ?? "developer_metadata") &&
+        existing.enabled === 1;
+}
+function registeredSyncSheetFromRow(row) {
+    if (row === undefined || row.physical_enabled !== 1 || row.logical_enabled !== 1) {
+        throw new StorageError(STORAGE_ERROR_CODES.SYNC_REGISTRY_TARGET_UNAVAILABLE, "physical sheet is not an enabled sync registry target");
+    }
+    if (!isRegisteredProjection(row.projection) || row.anchor_mode !== "developer_metadata") {
+        throw new StorageError(STORAGE_ERROR_CODES.SYNC_REGISTRY_TARGET_UNAVAILABLE, "physical sheet registry has an unsupported projection or anchor mode");
+    }
+    const registeredRange = normalizeRegisteredRange(row.registered_range, STORAGE_ERROR_CODES.SYNC_REGISTRY_TARGET_UNAVAILABLE);
+    if (registeredRange !== row.registered_range) {
+        throw new StorageError(STORAGE_ERROR_CODES.SYNC_REGISTRY_TARGET_UNAVAILABLE, "physical sheet registry range is not in canonical whole-column form");
+    }
+    return {
+        logicalSheetId: row.logical_sheet_id,
+        physicalSheetId: row.physical_sheet_id,
+        spreadsheetId: row.spreadsheet_id,
+        tabName: row.tab_name,
+        registeredRange,
+        projection: row.projection,
+        schemaVersion: row.schema_version,
+        ownershipManifestJson: row.ownership_manifest_json,
+        businessKeyField: row.business_key_field,
+        anchorMode: "developer_metadata",
+    };
+}
+function isRegisteredProjection(value) {
+    return value === "user_input" || value === "system_state" || value === "sync_conflicts";
+}
+/** Normalizes the v1 whole-column gateway boundary to the form accepted by Apps Script. */
+function normalizeRegisteredRange(value, errorCode) {
+    const normalized = value.trim().toUpperCase();
+    const match = /^([A-Z]+):([A-Z]+)$/.exec(normalized);
+    if (match === null || match[1] === undefined || match[2] === undefined) {
+        throw new StorageError(errorCode, "registered range must be a whole-column range such as A:Z");
+    }
+    if (sheetColumnNumber(match[2], errorCode) < sheetColumnNumber(match[1], errorCode)) {
+        throw new StorageError(errorCode, "registered range must be a whole-column range such as A:Z");
+    }
+    return normalized;
+}
+function sheetColumnNumber(letters, errorCode) {
+    let result = 0;
+    for (const letter of letters) {
+        result = result * 26 + letter.charCodeAt(0) - 64;
+        if (!Number.isSafeInteger(result)) {
+            throw new StorageError(errorCode, "registered range column is out of range");
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=syncRegistry.js.map

package/dist/infrastructure/storage/sync/shared/syncRegistry.js.map

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

package/dist/infrastructure/storage/sync/shared/writerLease.d.ts

@@ -0,0 +1,90 @@
+/**
+ * SQLite writer lease and fencing token management.
+ *
+ * Per design concurrency/writer-rpc.md:
+ * - Single writer owns all canonical/outbox mutations.
+ * - Every mutation CAS-checks the current fencing token.
+ * - Lease takeover increments epoch + fencing token.
+ * - Stale fencing tokens are rejected even if the affected row hasn't changed.
+ */
+import type { DatabaseSyncLike } from "../../sqlite/sqliteBridge.js";
+import type { LookupResult } from "../../../../shared/state/types.js";
+import type { SqlExecutor, SqlStorageAdapter } from "../../../../adapter/persistence/contracts/sql.js";
+export interface WriterLease {
+    readonly role: string;
+    readonly writerId: string;
+    readonly writerEpoch: number;
+    readonly fencingToken: string;
+    readonly leaseUntil: number;
+}
+/** Runtime values for the two observable writer-lease claim outcomes. */
+export declare const WRITER_LEASE_CLAIM_RESULT_KINDS: {
+    readonly CLAIMED: "claimed";
+    readonly NOT_CLAIMED: "not_claimed";
+};
+/** Closed set of writer-lease claim outcome kinds. */
+export type WriterLeaseClaimResultKind = (typeof WRITER_LEASE_CLAIM_RESULT_KINDS)[keyof typeof WRITER_LEASE_CLAIM_RESULT_KINDS];
+/** Runtime values explaining why a writer-lease claim did not succeed. */
+export declare const WRITER_LEASE_CLAIM_FAILURE_REASONS: {
+    readonly ACTIVE_WRITER: "active_writer";
+    readonly INITIAL_CLAIM_NOT_APPLIED: "initial_claim_not_applied";
+    readonly RENEWAL_RACE_LOST: "renewal_race_lost";
+    readonly TAKEOVER_RACE_LOST: "takeover_race_lost";
+};
+/** Closed set of writer-lease claim failure reasons. */
+export type WriterLeaseClaimFailureReason = (typeof WRITER_LEASE_CLAIM_FAILURE_REASONS)[keyof typeof WRITER_LEASE_CLAIM_FAILURE_REASONS];
+export type WriterLeaseClaimResult = {
+    readonly kind: typeof WRITER_LEASE_CLAIM_RESULT_KINDS.CLAIMED;
+    readonly lease: WriterLease;
+} | {
+    readonly kind: typeof WRITER_LEASE_CLAIM_RESULT_KINDS.NOT_CLAIMED;
+    readonly reason: WriterLeaseClaimFailureReason;
+};
+export interface ClaimLeaseOptions {
+    readonly role: string;
+    readonly writerId: string;
+    readonly leaseDurationMs: number;
+    readonly now: number;
+}
+/** The current lease identity required for a fenced storage mutation. */
+export interface FencingContext {
+    readonly role: string;
+    readonly writerEpoch: number;
+    readonly fencingToken: string;
+    readonly now: number;
+}
+/**
+ * Claims or renews the writer lease for a role.
+ *
+ * If no lease exists, creates one with epoch 1.
+ * If the current lease belongs to this writer, renews it.
+ * If the current lease has expired, takes over with incremented epoch + new fencing token.
+ * If the current lease is held by another active writer, returns a typed failure.
+ */
+export declare function claimWriterLease(db: DatabaseSyncLike, options: ClaimLeaseOptions): WriterLeaseClaimResult;
+/**
+ * Claims or renews a writer lease inside an already-active async SQL context.
+ *
+ * This is the MikroORM-compatible counterpart of `claimWriterLease()`. Call
+ * it from a broader adapter transaction when the lease claim must be atomic
+ * with an entity, canonical-state, or outbox mutation.
+ */
+export declare function claimWriterLeaseWithSql(sql: SqlExecutor, options: ClaimLeaseOptions): Promise<WriterLeaseClaimResult>;
+/** Claims or renews a writer lease in one adapter-owned transaction. */
+export declare function claimWriterLeaseWithAdapter(storage: SqlStorageAdapter, options: ClaimLeaseOptions): Promise<WriterLeaseClaimResult>;
+/** Reads the current lease for a role with an explicit not-found state. */
+export declare function readWriterLease(db: DatabaseSyncLike, role: string): LookupResult<WriterLease>;
+/** Reads a writer lease through an already-active async SQL context. */
+export declare function readWriterLeaseWithSql(sql: SqlExecutor, role: string): Promise<LookupResult<WriterLease>>;
+/** Reads a writer lease through a fresh adapter read context. */
+export declare function readWriterLeaseWithAdapter(storage: SqlStorageAdapter, role: string): Promise<LookupResult<WriterLease>>;
+/**
+ * Checks whether the given epoch + fencing token match the current lease.
+ * Used by effect workers to verify their claim is still valid before applying results.
+ */
+export declare function isFencingValid(db: DatabaseSyncLike, fence: FencingContext): boolean;
+/** Checks a fencing token inside an already-active async SQL context. */
+export declare function isFencingValidWithSql(sql: SqlExecutor, fence: FencingContext): Promise<boolean>;
+/** Checks a fencing token through a fresh adapter read context. */
+export declare function isFencingValidWithAdapter(storage: SqlStorageAdapter, fence: FencingContext): Promise<boolean>;
+//# sourceMappingURL=writerLease.d.ts.map

package/dist/infrastructure/storage/sync/shared/writerLease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writerLease.d.ts","sourceRoot":"","sources":["../../../../../src/infrastructure/storage/sync/shared/writerLease.ts"],"names":[],"mappings":"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"}

package/dist/infrastructure/storage/sync/shared/writerLease.js

@@ -0,0 +1,282 @@
+/**
+ * SQLite writer lease and fencing token management.
+ *
+ * Per design concurrency/writer-rpc.md:
+ * - Single writer owns all canonical/outbox mutations.
+ * - Every mutation CAS-checks the current fencing token.
+ * - Lease takeover increments epoch + fencing token.
+ * - Stale fencing tokens are rejected even if the affected row hasn't changed.
+ */
+import { STORAGE_ERROR_CODES, StorageError } from "../../errors.js";
+import { LOOKUP_RESULT_KINDS } from "../../../../shared/state/constants.js";
+import { withSqlSavepoint } from "../../sqlite/sqlTransaction.js";
+const READ_WRITER_LEASE_SQL = "SELECT role, writer_id, writer_epoch, fencing_token, lease_until FROM writer_lease WHERE role = ?";
+const INSERT_WRITER_LEASE_SQL = `
+  INSERT INTO writer_lease (role, writer_id, writer_epoch, fencing_token, lease_until)
+  VALUES (?, ?, ?, ?, ?)
+`;
+const RENEW_WRITER_LEASE_SQL = `
+  UPDATE writer_lease
+  SET lease_until = ?
+  WHERE role = ? AND writer_id = ? AND writer_epoch = ?
+    AND fencing_token = ? AND lease_until > ?
+`;
+const TAKEOVER_WRITER_LEASE_SQL = `
+  UPDATE writer_lease
+  SET writer_id = ?, writer_epoch = ?, fencing_token = ?, lease_until = ?
+  WHERE role = ? AND writer_epoch = ? AND fencing_token = ? AND lease_until <= ?
+`;
+/** Runtime values for the two observable writer-lease claim outcomes. */
+export const WRITER_LEASE_CLAIM_RESULT_KINDS = {
+    CLAIMED: "claimed",
+    NOT_CLAIMED: "not_claimed",
+};
+/** Runtime values explaining why a writer-lease claim did not succeed. */
+export const WRITER_LEASE_CLAIM_FAILURE_REASONS = {
+    ACTIVE_WRITER: "active_writer",
+    INITIAL_CLAIM_NOT_APPLIED: "initial_claim_not_applied",
+    RENEWAL_RACE_LOST: "renewal_race_lost",
+    TAKEOVER_RACE_LOST: "takeover_race_lost",
+};
+/**
+ * Claims or renews the writer lease for a role.
+ *
+ * If no lease exists, creates one with epoch 1.
+ * If the current lease belongs to this writer, renews it.
+ * If the current lease has expired, takes over with incremented epoch + new fencing token.
+ * If the current lease is held by another active writer, returns a typed failure.
+ */
+export function claimWriterLease(db, options) {
+    validateClaimOptions(options);
+    return withSavepoint(db, "claim_writer_lease", () => {
+        const existing = readLeaseRow(db, options.role);
+        const newLeaseUntil = options.now + options.leaseDurationMs;
+        if (existing === undefined) {
+            const lease = makeLease(options.role, options.writerId, 1, newLeaseUntil);
+            const result = db.prepare(INSERT_WRITER_LEASE_SQL).run(lease.role, lease.writerId, lease.writerEpoch, lease.fencingToken, lease.leaseUntil);
+            return result.changes === 1
+                ? { kind: WRITER_LEASE_CLAIM_RESULT_KINDS.CLAIMED, lease }
+                : {
+                    kind: WRITER_LEASE_CLAIM_RESULT_KINDS.NOT_CLAIMED,
+                    reason: WRITER_LEASE_CLAIM_FAILURE_REASONS.INITIAL_CLAIM_NOT_APPLIED,
+                };
+        }
+        if (existing.writer_id === options.writerId && existing.lease_until > options.now) {
+            const result = db.prepare(RENEW_WRITER_LEASE_SQL).run(newLeaseUntil, options.role, options.writerId, existing.writer_epoch, existing.fencing_token, options.now);
+            return result.changes === 1
+                ? {
+                    kind: WRITER_LEASE_CLAIM_RESULT_KINDS.CLAIMED,
+                    lease: {
+                        role: existing.role,
+                        writerId: existing.writer_id,
+                        writerEpoch: existing.writer_epoch,
+                        fencingToken: existing.fencing_token,
+                        leaseUntil: newLeaseUntil,
+                    },
+                }
+                : {
+                    kind: WRITER_LEASE_CLAIM_RESULT_KINDS.NOT_CLAIMED,
+                    reason: WRITER_LEASE_CLAIM_FAILURE_REASONS.RENEWAL_RACE_LOST,
+                };
+        }
+        if (existing.lease_until > options.now) {
+            return {
+                kind: WRITER_LEASE_CLAIM_RESULT_KINDS.NOT_CLAIMED,
+                reason: WRITER_LEASE_CLAIM_FAILURE_REASONS.ACTIVE_WRITER,
+            };
+        }
+        // An expired owner, including the same process, must take a new epoch.
+        // Reusing its old fence would allow delayed work to look current again.
+        const takeover = makeLease(options.role, options.writerId, existing.writer_epoch + 1, newLeaseUntil);
+        const result = db.prepare(TAKEOVER_WRITER_LEASE_SQL).run(takeover.writerId, takeover.writerEpoch, takeover.fencingToken, takeover.leaseUntil, options.role, existing.writer_epoch, existing.fencing_token, options.now);
+        return result.changes === 1
+            ? { kind: WRITER_LEASE_CLAIM_RESULT_KINDS.CLAIMED, lease: takeover }
+            : {
+                kind: WRITER_LEASE_CLAIM_RESULT_KINDS.NOT_CLAIMED,
+                reason: WRITER_LEASE_CLAIM_FAILURE_REASONS.TAKEOVER_RACE_LOST,
+            };
+    });
+}
+/**
+ * Claims or renews a writer lease inside an already-active async SQL context.
+ *
+ * This is the MikroORM-compatible counterpart of `claimWriterLease()`. Call
+ * it from a broader adapter transaction when the lease claim must be atomic
+ * with an entity, canonical-state, or outbox mutation.
+ */
+export async function claimWriterLeaseWithSql(sql, options) {
+    validateClaimOptions(options);
+    return withSqlSavepoint(sql, "claim_writer_lease", async () => {
+        const existing = await readLeaseRowWithSql(sql, options.role);
+        const newLeaseUntil = options.now + options.leaseDurationMs;
+        if (existing === undefined) {
+            const lease = makeLease(options.role, options.writerId, 1, newLeaseUntil);
+            const result = await sql.run(INSERT_WRITER_LEASE_SQL, [
+                lease.role,
+                lease.writerId,
+                lease.writerEpoch,
+                lease.fencingToken,
+                lease.leaseUntil,
+            ]);
+            return result.changes === 1
+                ? { kind: WRITER_LEASE_CLAIM_RESULT_KINDS.CLAIMED, lease }
+                : {
+                    kind: WRITER_LEASE_CLAIM_RESULT_KINDS.NOT_CLAIMED,
+                    reason: WRITER_LEASE_CLAIM_FAILURE_REASONS.INITIAL_CLAIM_NOT_APPLIED,
+                };
+        }
+        if (existing.writer_id === options.writerId && existing.lease_until > options.now) {
+            const result = await sql.run(RENEW_WRITER_LEASE_SQL, [
+                newLeaseUntil,
+                options.role,
+                options.writerId,
+                existing.writer_epoch,
+                existing.fencing_token,
+                options.now,
+            ]);
+            return result.changes === 1
+                ? {
+                    kind: WRITER_LEASE_CLAIM_RESULT_KINDS.CLAIMED,
+                    lease: {
+                        role: existing.role,
+                        writerId: existing.writer_id,
+                        writerEpoch: existing.writer_epoch,
+                        fencingToken: existing.fencing_token,
+                        leaseUntil: newLeaseUntil,
+                    },
+                }
+                : {
+                    kind: WRITER_LEASE_CLAIM_RESULT_KINDS.NOT_CLAIMED,
+                    reason: WRITER_LEASE_CLAIM_FAILURE_REASONS.RENEWAL_RACE_LOST,
+                };
+        }
+        if (existing.lease_until > options.now) {
+            return {
+                kind: WRITER_LEASE_CLAIM_RESULT_KINDS.NOT_CLAIMED,
+                reason: WRITER_LEASE_CLAIM_FAILURE_REASONS.ACTIVE_WRITER,
+            };
+        }
+        const takeover = makeLease(options.role, options.writerId, existing.writer_epoch + 1, newLeaseUntil);
+        const result = await sql.run(TAKEOVER_WRITER_LEASE_SQL, [
+            takeover.writerId,
+            takeover.writerEpoch,
+            takeover.fencingToken,
+            takeover.leaseUntil,
+            options.role,
+            existing.writer_epoch,
+            existing.fencing_token,
+            options.now,
+        ]);
+        return result.changes === 1
+            ? { kind: WRITER_LEASE_CLAIM_RESULT_KINDS.CLAIMED, lease: takeover }
+            : {
+                kind: WRITER_LEASE_CLAIM_RESULT_KINDS.NOT_CLAIMED,
+                reason: WRITER_LEASE_CLAIM_FAILURE_REASONS.TAKEOVER_RACE_LOST,
+            };
+    });
+}
+/** Claims or renews a writer lease in one adapter-owned transaction. */
+export async function claimWriterLeaseWithAdapter(storage, options) {
+    return storage.transaction(({ sql }) => claimWriterLeaseWithSql(sql, options));
+}
+/** Reads the current lease for a role with an explicit not-found state. */
+export function readWriterLease(db, role) {
+    const row = readLeaseRow(db, role);
+    return row === undefined
+        ? { kind: LOOKUP_RESULT_KINDS.NOT_FOUND }
+        : {
+            kind: LOOKUP_RESULT_KINDS.FOUND,
+            value: {
+                role: row.role,
+                writerId: row.writer_id,
+                writerEpoch: row.writer_epoch,
+                fencingToken: row.fencing_token,
+                leaseUntil: row.lease_until,
+            },
+        };
+}
+/** Reads a writer lease through an already-active async SQL context. */
+export async function readWriterLeaseWithSql(sql, role) {
+    const row = await readLeaseRowWithSql(sql, role);
+    return row === undefined
+        ? { kind: LOOKUP_RESULT_KINDS.NOT_FOUND }
+        : {
+            kind: LOOKUP_RESULT_KINDS.FOUND,
+            value: {
+                role: row.role,
+                writerId: row.writer_id,
+                writerEpoch: row.writer_epoch,
+                fencingToken: row.fencing_token,
+                leaseUntil: row.lease_until,
+            },
+        };
+}
+/** Reads a writer lease through a fresh adapter read context. */
+export async function readWriterLeaseWithAdapter(storage, role) {
+    return storage.read(({ sql }) => readWriterLeaseWithSql(sql, role));
+}
+/**
+ * Checks whether the given epoch + fencing token match the current lease.
+ * Used by effect workers to verify their claim is still valid before applying results.
+ */
+export function isFencingValid(db, fence) {
+    const lease = readWriterLease(db, fence.role);
+    if (lease.kind === LOOKUP_RESULT_KINDS.NOT_FOUND)
+        return false;
+    return (lease.value.writerEpoch === fence.writerEpoch &&
+        lease.value.fencingToken === fence.fencingToken &&
+        lease.value.leaseUntil > fence.now);
+}
+/** Checks a fencing token inside an already-active async SQL context. */
+export async function isFencingValidWithSql(sql, fence) {
+    const lease = await readWriterLeaseWithSql(sql, fence.role);
+    if (lease.kind === LOOKUP_RESULT_KINDS.NOT_FOUND)
+        return false;
+    return (lease.value.writerEpoch === fence.writerEpoch &&
+        lease.value.fencingToken === fence.fencingToken &&
+        lease.value.leaseUntil > fence.now);
+}
+/** Checks a fencing token through a fresh adapter read context. */
+export async function isFencingValidWithAdapter(storage, fence) {
+    return storage.read(({ sql }) => isFencingValidWithSql(sql, fence));
+}
+function readLeaseRow(db, role) {
+    return db.prepare(READ_WRITER_LEASE_SQL).get(role);
+}
+function readLeaseRowWithSql(sql, role) {
+    return sql.get(READ_WRITER_LEASE_SQL, [role]);
+}
+function makeLease(role, writerId, writerEpoch, leaseUntil) {
+    return {
+        role,
+        writerId,
+        writerEpoch,
+        fencingToken: `fence-${writerEpoch}`,
+        leaseUntil,
+    };
+}
+function validateClaimOptions(options) {
+    if (!Number.isSafeInteger(options.now) || options.now < 0) {
+        throw new StorageError(STORAGE_ERROR_CODES.INVALID_WRITER_LEASE_OPTIONS, "writer lease now must be a non-negative safe integer");
+    }
+    if (!Number.isSafeInteger(options.leaseDurationMs) || options.leaseDurationMs <= 0) {
+        throw new StorageError(STORAGE_ERROR_CODES.INVALID_WRITER_LEASE_OPTIONS, "writer lease duration must be a positive safe integer");
+    }
+    if (options.role.length === 0 || options.writerId.length === 0) {
+        throw new StorageError(STORAGE_ERROR_CODES.INVALID_WRITER_LEASE_OPTIONS, "writer lease role and writer ID are required");
+    }
+}
+function withSavepoint(db, name, operation) {
+    db.exec(`SAVEPOINT ${name}`);
+    try {
+        const value = operation();
+        db.exec(`RELEASE ${name}`);
+        return value;
+    }
+    catch (error) {
+        db.exec(`ROLLBACK TO ${name}`);
+        db.exec(`RELEASE ${name}`);
+        throw error;
+    }
+}
+//# sourceMappingURL=writerLease.js.map