hikoutei 0.2.0

package/dist/infrastructure/storage/sync/outbound/effectOutboxSql.js

@@ -0,0 +1,184 @@
+/** SQL statements used by the effect outbox state machine. */
+import { SYNC_EFFECT_RECOVERY_ERROR_CODES } from "./effectOutboxContracts.js";
+export const RECOVERABLE_EFFECT_ERROR_CODE_SQL = [
+    SYNC_EFFECT_RECOVERY_ERROR_CODES.LEASE_EXPIRED_REQUIRES_POSTCONDITION,
+    SYNC_EFFECT_RECOVERY_ERROR_CODES.GATEWAY_RETRYABLE_ERROR,
+    SYNC_EFFECT_RECOVERY_ERROR_CODES.POSTCONDITION_READ_FAILED,
+    SYNC_EFFECT_RECOVERY_ERROR_CODES.POSTCONDITION_UNAVAILABLE,
+    SYNC_EFFECT_RECOVERY_ERROR_CODES.POSTCONDITION_UNAPPLIED_REQUIRES_REDRIVE,
+].map((code) => `'${code}'`)
+    .join(", ");
+export const FENCE_EXISTS_SQL = `
+  SELECT 1 FROM writer_lease
+  WHERE role = ? AND writer_epoch = ? AND fencing_token = ? AND lease_until > ?
+`;
+export const CLAIM_EFFECT_SQL = `
+  UPDATE sheet_effect_outbox AS candidate
+  SET status = 'processing', claim_token = ?, writer_epoch = ?, lease_until = ?,
+      attempts = attempts + 1
+  WHERE candidate.effect_id = ?
+    AND candidate.status IN ('pending', 'failed')
+    AND EXISTS (${FENCE_EXISTS_SQL})
+    AND NOT EXISTS (
+      SELECT 1
+      FROM sheet_effect_outbox AS predecessor
+      WHERE predecessor.logical_sheet_id = candidate.logical_sheet_id
+        AND predecessor.target_kind = candidate.target_kind
+        AND predecessor.target_id = candidate.target_id
+        AND predecessor.stream_sequence < candidate.stream_sequence
+        AND predecessor.status NOT IN ('applied', 'superseded')
+    )
+`;
+export const INSERT_PENDING_EFFECT_SQL = `
+  INSERT INTO sheet_effect_outbox (
+    effect_id, effect_kind, commit_id, logical_sheet_id, physical_sheet_id,
+    projection, row_binding_id, conflict_id, target_kind, target_id,
+    target_entity_revision, target_field_revision_hash, target_canonical_commit_id,
+    expected_visible_revision, expected_visible_hash, repair_guard_hash,
+    source_quarantine_id, payload_json, payload_hash, effect_dedupe_key,
+    stream_sequence, created_at, status
+  )
+  SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending'
+  WHERE EXISTS (${FENCE_EXISTS_SQL})
+`;
+export const APPLY_EFFECT_RESULT_SQL = `
+  UPDATE sheet_effect_outbox
+  SET status = ?, last_error_code = ?, last_error_message = ?,
+      claim_token = NULL, lease_until = NULL
+  WHERE effect_id = ?
+    AND status = 'processing'
+    AND claim_token = ?
+    AND writer_epoch = ?
+    AND lease_until IS NOT NULL
+    AND lease_until > ?
+    AND EXISTS (${FENCE_EXISTS_SQL})
+`;
+export const SUPERSEDE_EFFECT_SQL = `
+  UPDATE sheet_effect_outbox
+  SET status = 'superseded', supersedes_effect_id = ?
+  WHERE effect_id = ?
+    AND status IN ('pending', 'processing', 'blocked_candidate', 'conflict', 'failed')
+    AND EXISTS (${FENCE_EXISTS_SQL})
+`;
+export const INSERT_REPLANNED_EFFECT_SQL = `
+  INSERT INTO sheet_effect_outbox (
+    effect_id, effect_kind, commit_id, logical_sheet_id, physical_sheet_id,
+    projection, row_binding_id, conflict_id, target_kind, target_id,
+    target_entity_revision, target_field_revision_hash, target_canonical_commit_id,
+    expected_visible_revision, expected_visible_hash, repair_guard_hash,
+    source_quarantine_id, payload_json, payload_hash, effect_dedupe_key,
+    stream_sequence, predecessor_effect_id, created_at, status
+  )
+  SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending'
+  WHERE EXISTS (${FENCE_EXISTS_SQL})
+`;
+export const RECOVER_EXPIRED_LEASES_SQL = `
+  UPDATE sheet_effect_outbox
+  SET status = 'failed', claim_token = NULL, lease_until = NULL,
+      last_error_code = '${SYNC_EFFECT_RECOVERY_ERROR_CODES.LEASE_EXPIRED_REQUIRES_POSTCONDITION}',
+      last_error_message = 'Read the remote postcondition before retrying this effect.'
+  WHERE status = 'processing' AND lease_until IS NOT NULL AND lease_until <= ?
+    AND EXISTS (${FENCE_EXISTS_SQL})
+`;
+export const REQUEUE_CLAIMED_EFFECT_SQL = `
+  UPDATE sheet_effect_outbox
+  SET status = 'pending', claim_token = NULL, lease_until = NULL,
+      last_error_code = ?, last_error_message = ?
+  WHERE effect_id = ? AND status = 'processing' AND claim_token = ?
+    AND writer_epoch = ? AND lease_until IS NOT NULL AND lease_until > ?
+    AND EXISTS (${FENCE_EXISTS_SQL})
+`;
+export const RELEASE_UNPROCESSED_EFFECT_SQL = `
+  UPDATE sheet_effect_outbox
+  SET status = 'pending', claim_token = NULL, lease_until = NULL,
+      last_error_code = 'gateway_batch_deferred',
+      last_error_message = 'Gateway acknowledged a bounded batch before this effect.'
+  WHERE effect_id = ? AND status = 'processing' AND claim_token = ?
+    AND writer_epoch = ? AND lease_until IS NOT NULL AND lease_until > ?
+    AND EXISTS (${FENCE_EXISTS_SQL})
+`;
+export const SELECT_PENDING_EFFECTS_BY_TARGET_SQL = `
+  SELECT effect_id, effect_kind, commit_id, logical_sheet_id, physical_sheet_id,
+         projection, row_binding_id, conflict_id, target_kind, target_id,
+         target_entity_revision, target_field_revision_hash, target_canonical_commit_id,
+         expected_visible_revision, expected_visible_hash, repair_guard_hash,
+         source_quarantine_id, payload_json, payload_hash, effect_dedupe_key,
+         stream_sequence, created_at, status
+  FROM sheet_effect_outbox
+  WHERE logical_sheet_id = ? AND target_kind = ? AND target_id = ?
+    AND status = 'pending'
+    AND NOT EXISTS (
+      SELECT 1
+      FROM sheet_effect_outbox AS predecessor
+      WHERE predecessor.logical_sheet_id = sheet_effect_outbox.logical_sheet_id
+        AND predecessor.target_kind = sheet_effect_outbox.target_kind
+        AND predecessor.target_id = sheet_effect_outbox.target_id
+        AND predecessor.stream_sequence < sheet_effect_outbox.stream_sequence
+        AND predecessor.status NOT IN ('applied', 'superseded')
+    )
+  ORDER BY stream_sequence
+`;
+export const SELECT_READY_EFFECTS_SQL = `
+  SELECT effect_id, effect_kind, commit_id, logical_sheet_id, physical_sheet_id,
+         projection, row_binding_id, conflict_id, target_kind, target_id,
+         target_entity_revision, target_field_revision_hash, target_canonical_commit_id,
+         expected_visible_revision, expected_visible_hash, repair_guard_hash,
+         source_quarantine_id, payload_json, payload_hash, effect_dedupe_key,
+         stream_sequence, created_at, status
+  FROM sheet_effect_outbox AS candidate
+  WHERE (
+    candidate.status = 'pending'
+    OR (
+      candidate.status = 'failed'
+      AND candidate.last_error_code IN (${RECOVERABLE_EFFECT_ERROR_CODE_SQL})
+    )
+  )
+    AND NOT EXISTS (
+      SELECT 1
+      FROM sheet_effect_outbox AS predecessor
+      WHERE predecessor.logical_sheet_id = candidate.logical_sheet_id
+        AND predecessor.target_kind = candidate.target_kind
+        AND predecessor.target_id = candidate.target_id
+        AND predecessor.stream_sequence < candidate.stream_sequence
+        AND predecessor.status NOT IN ('applied', 'superseded')
+    )
+  ORDER BY candidate.logical_sheet_id, candidate.physical_sheet_id,
+           candidate.target_kind, candidate.target_id, candidate.stream_sequence
+  LIMIT ?
+`;
+export const COUNT_PENDING_OR_PROCESSING_EFFECTS_SQL = `
+  SELECT COUNT(*) AS count
+  FROM sheet_effect_outbox
+  WHERE status IN ('pending', 'processing')
+`;
+export const UPSERT_VISIBLE_STATE_SQL = `
+  INSERT INTO sheet_visible_state (
+    physical_sheet_id, projection, row_binding_id, confirmed_snapshot_hash,
+    confirmed_visible_revision, confirmed_entity_revision, last_observed_hash
+  ) VALUES (?, ?, ?, ?, ?, ?, ?)
+  ON CONFLICT(physical_sheet_id, projection, row_binding_id)
+  DO UPDATE SET
+    confirmed_snapshot_hash = excluded.confirmed_snapshot_hash,
+    confirmed_visible_revision = excluded.confirmed_visible_revision,
+    confirmed_entity_revision = excluded.confirmed_entity_revision,
+    last_observed_hash = excluded.last_observed_hash
+  WHERE sheet_visible_state.confirmed_visible_revision <= excluded.confirmed_visible_revision
+`;
+export const UPSERT_VISIBLE_FIELD_STATE_SQL = `
+  INSERT INTO sheet_visible_field_state (
+    physical_sheet_id, projection, row_binding_id, field_name,
+    confirmed_field_hash, confirmed_visible_revision, candidate_epoch,
+    last_observed_field_hash
+  ) VALUES (?, ?, ?, ?, ?, ?, 0, ?)
+  ON CONFLICT(physical_sheet_id, projection, row_binding_id, field_name)
+  DO UPDATE SET
+    confirmed_field_hash = excluded.confirmed_field_hash,
+    confirmed_visible_revision = excluded.confirmed_visible_revision,
+    last_observed_field_hash = excluded.last_observed_field_hash
+  WHERE sheet_visible_field_state.confirmed_visible_revision <= excluded.confirmed_visible_revision
+`;
+/**
+ * Claims a pending effect for processing.
+ * Uses CAS on status to ensure only one worker wins.
+ */
+//# sourceMappingURL=effectOutboxSql.js.map

package/dist/infrastructure/storage/sync/outbound/effectOutboxSql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effectOutboxSql.js","sourceRoot":"","sources":["../../../../../src/infrastructure/storage/sync/outbound/effectOutboxSql.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAE9D,OAAO,EAAE,gCAAgC,EAAE,MAAM,4BAA4B,CAAC;AAE9E,MAAM,CAAC,MAAM,iCAAiC,GAAG;IAC/C,gCAAgC,CAAC,oCAAoC;IACrE,gCAAgC,CAAC,uBAAuB;IACxD,gCAAgC,CAAC,yBAAyB;IAC1D,gCAAgC,CAAC,yBAAyB;IAC1D,gCAAgC,CAAC,wCAAwC;CAC1E,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG,CAAC;KACzB,IAAI,CAAC,IAAI,CAAC,CAAC;AAEd,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;CAG/B,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;kBAMd,gBAAgB;;;;;;;;;;CAUjC,CAAC;AAEF,MAAM,CAAC,MAAM,yBAAyB,GAAG;;;;;;;;;;kBAUvB,gBAAgB;CACjC,CAAC;AAEF,MAAM,CAAC,MAAM,uBAAuB,GAAG;;;;;;;;;;kBAUrB,gBAAgB;CACjC,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAG;;;;;kBAKlB,gBAAgB;CACjC,CAAC;AAEF,MAAM,CAAC,MAAM,2BAA2B,GAAG;;;;;;;;;;kBAUzB,gBAAgB;CACjC,CAAC;AAEF,MAAM,CAAC,MAAM,0BAA0B,GAAG;;;2BAGf,gCAAgC,CAAC,oCAAoC;;;kBAG9E,gBAAgB;CACjC,CAAC;AAEF,MAAM,CAAC,MAAM,0BAA0B,GAAG;;;;;;kBAMxB,gBAAgB;CACjC,CAAC;AAEF,MAAM,CAAC,MAAM,8BAA8B,GAAG;;;;;;;kBAO5B,gBAAgB;CACjC,CAAC;AAEF,MAAM,CAAC,MAAM,oCAAoC,GAAG;;;;;;;;;;;;;;;;;;;;CAoBnD,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAG;;;;;;;;;;;;0CAYE,iCAAiC;;;;;;;;;;;;;;;CAe1E,CAAC;AAEF,MAAM,CAAC,MAAM,uCAAuC,GAAG;;;;CAItD,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAG;;;;;;;;;;;;CAYvC,CAAC;AAEF,MAAM,CAAC,MAAM,8BAA8B,GAAG;;;;;;;;;;;;CAY7C,CAAC;AAGF;;;GAGG"}

package/dist/infrastructure/storage/sync/outbound/effectOutboxSupport.d.ts

@@ -0,0 +1,25 @@
+/** Validation, projection confirmation, fencing, and SQL parameter helpers. */
+import type { DatabaseSyncLike } from "../../sqlite/sqliteBridge.js";
+import type { FencingContext } from "../shared/writerLease.js";
+import type { ApplyResultOptions, ClaimEffectOptions, EffectProjectionConfirmation, NewEffect } from "./effectOutboxContracts.js";
+import type { SqlExecutor, SqlParameter } from "../../../../adapter/persistence/contracts/sql.js";
+export declare function validateProjectionConfirmation(confirmation: EffectProjectionConfirmation): void;
+export declare function validateApplyResultOptions(options: ApplyResultOptions): void;
+export declare function validateEffectLeaseDuration(leaseDurationMs: number): void;
+export declare function validateReadyEffectLimit(limit: number): void;
+/** Writes row and field confirmation only after the outbox effect has won its claim CAS. */
+export declare function writeProjectionConfirmation(db: DatabaseSyncLike, confirmation: EffectProjectionConfirmation): void;
+/** Writes confirmed row and field state through the active async SQL context. */
+export declare function writeProjectionConfirmationWithSql(sql: SqlExecutor, confirmation: EffectProjectionConfirmation): Promise<void>;
+export declare function requireCurrentFence(db: DatabaseSyncLike, fence: FencingContext): void;
+export declare function requireCurrentFenceWithSql(sql: SqlExecutor, fence: FencingContext): Promise<void>;
+export declare function fenceParameters(fence: FencingContext): readonly [string, number, string, number];
+export declare function claimEffectParameters(options: ClaimEffectOptions): readonly SqlParameter[];
+export declare function applyEffectResultParameters(options: ApplyResultOptions): readonly SqlParameter[];
+export declare function effectInsertParameters(effect: NewEffect): readonly SqlParameter[];
+export declare function pendingEffectParameters(effect: NewEffect, fence: FencingContext): readonly SqlParameter[];
+export declare function replannedEffectParameters(effect: NewEffect, oldEffectId: string, fence: FencingContext): readonly SqlParameter[];
+/** Internal control-flow signal that forces the enclosing async savepoint to roll back. */
+export declare class AsyncFenceLostError extends Error {
+}
+//# sourceMappingURL=effectOutboxSupport.d.ts.map

package/dist/infrastructure/storage/sync/outbound/effectOutboxSupport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effectOutboxSupport.d.ts","sourceRoot":"","sources":["../../../../../src/infrastructure/storage/sync/outbound/effectOutboxSupport.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAG/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAKrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAM/D,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAClB,4BAA4B,EAC5B,SAAS,EACV,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACb,MAAM,kDAAkD,CAAC;AAE1D,wBAAgB,8BAA8B,CAAC,YAAY,EAAE,4BAA4B,GAAG,IAAI,CAsB/F;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAU5E;AAED,wBAAgB,2BAA2B,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAOzE;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAO5D;AAED,4FAA4F;AAC5F,wBAAgB,2BAA2B,CACzC,EAAE,EAAE,gBAAgB,EACpB,YAAY,EAAE,4BAA4B,GACzC,IAAI,CAkCN;AAED,iFAAiF;AACjF,wBAAsB,kCAAkC,CACtD,GAAG,EAAE,WAAW,EAChB,YAAY,EAAE,4BAA4B,GACzC,OAAO,CAAC,IAAI,CAAC,CAkCf;AAED,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,gBAAgB,EAAE,KAAK,EAAE,cAAc,GAAG,IAAI,CAOrF;AAED,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEhG;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,kBAAkB,GAAG,SAAS,YAAY,EAAE,CAQ1F;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,kBAAkB,GAAG,SAAS,YAAY,EAAE,CAWhG;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,YAAY,EAAE,CAwBjF;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,cAAc,GACpB,SAAS,YAAY,EAAE,CAMzB;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,cAAc,GACpB,SAAS,YAAY,EAAE,CAOzB;AAED,2FAA2F;AAC3F,qBAAa,mBAAoB,SAAQ,KAAK;CAAG"}

package/dist/infrastructure/storage/sync/outbound/effectOutboxSupport.js

@@ -0,0 +1,158 @@
+/** Validation, projection confirmation, fencing, and SQL parameter helpers. */
+import { STORAGE_ERROR_CODES, StorageError } from "../../errors.js";
+import { isFencingValid, isFencingValidWithSql, } from "../shared/writerLease.js";
+import { toSqlNullable } from "../../sqlite/sqlState.js";
+import { UPSERT_VISIBLE_FIELD_STATE_SQL, UPSERT_VISIBLE_STATE_SQL, } from "./effectOutboxSql.js";
+export function validateProjectionConfirmation(confirmation) {
+    if (confirmation.physicalSheetId.length === 0 ||
+        confirmation.projection.length === 0 ||
+        confirmation.rowBindingId.length === 0 ||
+        confirmation.visibleHash.length === 0 ||
+        !Number.isSafeInteger(confirmation.visibleRevision) ||
+        confirmation.visibleRevision < 1) {
+        throw new StorageError(STORAGE_ERROR_CODES.INVALID_PROJECTION_CONFIRMATION, "projection confirmation has an invalid identity or visible revision");
+    }
+    for (const [fieldName, hash] of Object.entries(confirmation.fieldHashes)) {
+        if (fieldName.length === 0 || hash.length === 0) {
+            throw new StorageError(STORAGE_ERROR_CODES.INVALID_PROJECTION_CONFIRMATION, "projection confirmation contains an invalid field hash");
+        }
+    }
+}
+export function validateApplyResultOptions(options) {
+    if (options.status !== "applied" && options.projectionConfirmation !== undefined) {
+        throw new StorageError(STORAGE_ERROR_CODES.INVALID_EFFECT_RESULT, "only an applied effect may advance confirmed projection state");
+    }
+    if (options.projectionConfirmation !== undefined) {
+        validateProjectionConfirmation(options.projectionConfirmation);
+    }
+}
+export function validateEffectLeaseDuration(leaseDurationMs) {
+    if (!Number.isSafeInteger(leaseDurationMs) || leaseDurationMs <= 0) {
+        throw new StorageError(STORAGE_ERROR_CODES.INVALID_EFFECT_OPTIONS, "effect lease duration must be a positive safe integer");
+    }
+}
+export function validateReadyEffectLimit(limit) {
+    if (!Number.isSafeInteger(limit) || limit < 1) {
+        throw new StorageError(STORAGE_ERROR_CODES.INVALID_EFFECT_OPTIONS, "ready effect limit must be a positive safe integer");
+    }
+}
+/** Writes row and field confirmation only after the outbox effect has won its claim CAS. */
+export function writeProjectionConfirmation(db, confirmation) {
+    const row = db.prepare(UPSERT_VISIBLE_STATE_SQL).run(confirmation.physicalSheetId, confirmation.projection, confirmation.rowBindingId, confirmation.visibleHash, confirmation.visibleRevision, toSqlNullable(confirmation.entityRevision), confirmation.visibleHash);
+    if (row.changes !== 1) {
+        throw new StorageError(STORAGE_ERROR_CODES.PROJECTION_CONFIRMATION_REGRESSION, "projection confirmation would move visible state backwards");
+    }
+    for (const [fieldName, hash] of Object.entries(confirmation.fieldHashes)) {
+        const field = db.prepare(UPSERT_VISIBLE_FIELD_STATE_SQL).run(confirmation.physicalSheetId, confirmation.projection, confirmation.rowBindingId, fieldName, hash, confirmation.visibleRevision, hash);
+        if (field.changes !== 1) {
+            throw new StorageError(STORAGE_ERROR_CODES.PROJECTION_CONFIRMATION_REGRESSION, "projection confirmation would move a field visible state backwards");
+        }
+    }
+}
+/** Writes confirmed row and field state through the active async SQL context. */
+export async function writeProjectionConfirmationWithSql(sql, confirmation) {
+    const row = await sql.run(UPSERT_VISIBLE_STATE_SQL, [
+        confirmation.physicalSheetId,
+        confirmation.projection,
+        confirmation.rowBindingId,
+        confirmation.visibleHash,
+        confirmation.visibleRevision,
+        toSqlNullable(confirmation.entityRevision),
+        confirmation.visibleHash,
+    ]);
+    if (row.changes !== 1) {
+        throw new StorageError(STORAGE_ERROR_CODES.PROJECTION_CONFIRMATION_REGRESSION, "projection confirmation would move visible state backwards");
+    }
+    for (const [fieldName, hash] of Object.entries(confirmation.fieldHashes)) {
+        const field = await sql.run(UPSERT_VISIBLE_FIELD_STATE_SQL, [
+            confirmation.physicalSheetId,
+            confirmation.projection,
+            confirmation.rowBindingId,
+            fieldName,
+            hash,
+            confirmation.visibleRevision,
+            hash,
+        ]);
+        if (field.changes !== 1) {
+            throw new StorageError(STORAGE_ERROR_CODES.PROJECTION_CONFIRMATION_REGRESSION, "projection confirmation would move a field visible state backwards");
+        }
+    }
+}
+export function requireCurrentFence(db, fence) {
+    if (!isFencingValid(db, fence)) {
+        throw new StorageError(STORAGE_ERROR_CODES.STALE_WRITER_FENCE, "writer fencing is stale or expired");
+    }
+}
+export async function requireCurrentFenceWithSql(sql, fence) {
+    if (!(await isFencingValidWithSql(sql, fence))) {
+        throw new StorageError(STORAGE_ERROR_CODES.STALE_WRITER_FENCE, "writer fencing is stale or expired");
+    }
+}
+export function fenceParameters(fence) {
+    return [fence.role, fence.writerEpoch, fence.fencingToken, fence.now];
+}
+export function claimEffectParameters(options) {
+    return [
+        options.claimToken,
+        options.writerEpoch,
+        options.now + options.leaseDurationMs,
+        options.effectId,
+        ...fenceParameters(options),
+    ];
+}
+export function applyEffectResultParameters(options) {
+    return [
+        options.status,
+        toSqlNullable(options.lastErrorCode),
+        toSqlNullable(options.lastErrorMessage),
+        options.effectId,
+        options.claimToken,
+        options.writerEpoch,
+        options.now,
+        ...fenceParameters(options),
+    ];
+}
+export function effectInsertParameters(effect) {
+    return [
+        effect.effectId,
+        effect.effectKind,
+        effect.commitId,
+        effect.logicalSheetId,
+        effect.physicalSheetId,
+        effect.projection,
+        toSqlNullable(effect.rowBindingId),
+        toSqlNullable(effect.conflictId),
+        effect.targetKind,
+        effect.targetId,
+        toSqlNullable(effect.targetEntityRevision),
+        toSqlNullable(effect.targetFieldRevisionHash),
+        toSqlNullable(effect.targetCanonicalCommitId),
+        effect.expectedVisibleRevision,
+        effect.expectedVisibleHash,
+        toSqlNullable(effect.repairGuardHash),
+        toSqlNullable(effect.sourceQuarantineId),
+        effect.payloadJson,
+        effect.payloadHash,
+        effect.effectDedupeKey,
+        effect.streamSequence,
+    ];
+}
+export function pendingEffectParameters(effect, fence) {
+    return [
+        ...effectInsertParameters(effect),
+        fence.now,
+        ...fenceParameters(fence),
+    ];
+}
+export function replannedEffectParameters(effect, oldEffectId, fence) {
+    return [
+        ...effectInsertParameters(effect),
+        oldEffectId,
+        fence.now,
+        ...fenceParameters(fence),
+    ];
+}
+/** Internal control-flow signal that forces the enclosing async savepoint to roll back. */
+export class AsyncFenceLostError extends Error {
+}
+//# sourceMappingURL=effectOutboxSupport.js.map

package/dist/infrastructure/storage/sync/outbound/effectOutboxSupport.js.map

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

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

@@ -0,0 +1,69 @@
+/**
+ * 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 { type DatabaseSyncLike } from "../../sqlite/sqliteBridge.js";
+import type { SqlExecutor, SqlStorageAdapter } from "../../../../adapter/persistence/contracts/sql.js";
+import { type FencingContext } from "./writerLease.js";
+/** The only projection labels accepted by the v1 runtime registry. */
+export type RegisteredProjection = "user_input" | "system_state" | "sync_conflicts";
+/** Immutable logical/physical registration supplied by deployment setup. */
+export interface RegisterSyncSheetInput {
+    readonly logicalSheetId: string;
+    readonly physicalSheetId: string;
+    readonly spreadsheetId: string;
+    readonly tabName: string;
+    readonly registeredRange: string;
+    readonly projection: RegisteredProjection;
+    readonly schemaVersion: number;
+    readonly ownershipManifestJson: string;
+    readonly businessKeyField: string;
+    readonly anchorMode?: "developer_metadata";
+}
+/** Registry row used for all gateway requests. */
+export interface RegisteredSyncSheet {
+    readonly logicalSheetId: string;
+    readonly physicalSheetId: string;
+    readonly spreadsheetId: string;
+    readonly tabName: string;
+    readonly registeredRange: string;
+    readonly projection: RegisteredProjection;
+    readonly schemaVersion: number;
+    readonly ownershipManifestJson: string;
+    readonly businessKeyField: string;
+    readonly anchorMode: "developer_metadata";
+}
+/** Records whether a fenced registry request won the writer ownership check. */
+export type RegisterSyncSheetResult = {
+    readonly kind: "registered";
+    readonly sheet: RegisteredSyncSheet;
+} | {
+    readonly kind: "fenced_out";
+};
+/**
+ * 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 declare function registerSyncSheet(db: DatabaseSyncLike, fence: FencingContext, input: RegisterSyncSheetInput): RegisterSyncSheetResult;
+/**
+ * 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 declare function registerSyncSheetWithSql(sql: SqlExecutor, fence: FencingContext, input: RegisterSyncSheetInput): Promise<RegisterSyncSheetResult>;
+/** Registers one projection in an adapter-owned MikroORM transaction. */
+export declare function registerSyncSheetWithAdapter(storage: SqlStorageAdapter, fence: FencingContext, input: RegisterSyncSheetInput): Promise<RegisterSyncSheetResult>;
+/** Reads one enabled physical registry entry or rejects any unregistered target. */
+export declare function requireRegisteredSyncSheet(db: DatabaseSyncLike, physicalSheetId: string): RegisteredSyncSheet;
+/** Reads one enabled physical registry entry through an active async SQL context. */
+export declare function requireRegisteredSyncSheetWithSql(sql: SqlExecutor, physicalSheetId: string): Promise<RegisteredSyncSheet>;
+/** Reads one enabled physical registry entry through a fresh adapter read context. */
+export declare function requireRegisteredSyncSheetWithAdapter(storage: SqlStorageAdapter, physicalSheetId: string): Promise<RegisteredSyncSheet>;
+//# sourceMappingURL=syncRegistry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"syncRegistry.d.ts","sourceRoot":"","sources":["../../../../../src/infrastructure/storage/sync/shared/syncRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAA4B,KAAK,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAG/F,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,kDAAkD,CAAC;AACvG,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAsC1B,sEAAsE;AACtE,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,cAAc,GAAG,gBAAgB,CAAC;AAEpF,4EAA4E;AAC5E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,oBAAoB,CAAC;CAC5C;AAED,kDAAkD;AAClD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;CAC3C;AAED,gFAAgF;AAChF,MAAM,MAAM,uBAAuB,GAC/B;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC;AAEpC;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,gBAAgB,EACpB,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,sBAAsB,GAC5B,uBAAuB,CA2DzB;AAED;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,uBAAuB,CAAC,CA+DlC;AAED,yEAAyE;AACzE,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,uBAAuB,CAAC,CAElC;AAED,oFAAoF;AACpF,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,gBAAgB,EACpB,eAAe,EAAE,MAAM,GACtB,mBAAmB,CAUrB;AAED,qFAAqF;AACrF,wBAAsB,iCAAiC,CACrD,GAAG,EAAE,WAAW,EAChB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,mBAAmB,CAAC,CAS9B;AAED,sFAAsF;AACtF,wBAAsB,qCAAqC,CACzD,OAAO,EAAE,iBAAiB,EAC1B,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,mBAAmB,CAAC,CAE9B"}