otto-intel-mcp 0.1.2 → 0.1.4

package/dist/execution-journal-schema.js

@@ -0,0 +1,368 @@
+/** Shared operations.db schema and cross-rail claims. No transaction or receipt authority lives here. */
+import { EXECUTION_STORAGE_SCHEMA, assertExecutionStorageSchema, assertDeclaredExecutionStorage } from './execution-journal-tables.js';
+import { END_USER_ID_PATTERN } from './execution-delegation-cap-store.js';
+/** Ordinary fresh initialization remains v4; v5 is an explicit offline semantic-reader migration. */
+export const EXECUTION_JOURNAL_SCHEMA_VERSION = 4;
+export const EXECUTION_JOURNAL_MAX_SCHEMA_VERSION = 6;
+export const USER_EXECUTION_CLAIM_KINDS = ['mint', 'delegated', 'exit', 'native', 'sponsored'];
+export class ExecutionJournalNotReadyError extends Error {
+    constructor() { super('the shared execution journal is not rollout-ready'); }
+}
+const CLAIM_COLUMNS = ['user_id', 'kind', 'claim_id', 'claim_generation', 'created_at_ms', 'updated_at_ms'];
+const CLAIM_TABLE = `(
+  user_id TEXT NOT NULL PRIMARY KEY,
+  kind TEXT NOT NULL CHECK (kind IN ('mint','delegated','exit','native','sponsored')),
+  claim_id TEXT NOT NULL,
+  claim_generation INTEGER CHECK (claim_generation IS NULL OR claim_generation >= 0),
+  created_at_ms INTEGER NOT NULL,
+  updated_at_ms INTEGER NOT NULL
+)`;
+function corrupt(detail) { throw new Error(`the shared execution journal is corrupt or unsupported (${detail})`); }
+function meta(db, key) {
+    const row = db.prepare('SELECT value FROM journal_meta WHERE key = ?').get(key);
+    if (!row)
+        return undefined;
+    if (typeof row.value !== 'string')
+        return corrupt('metadata value');
+    return row.value;
+}
+function validTime(value) {
+    return typeof value === 'string' && value.length > 0 && Number.isFinite(Date.parse(value));
+}
+function schemaVersion(db) {
+    const version = meta(db, 'schema_version');
+    if (version !== '2' && version !== '3' && version !== '4' && version !== '5' && version !== '6')
+        corrupt('schema version');
+    return Number(version);
+}
+/** Every writer checks the actual version under its own transaction. Opening is not migration authority. */
+export function assertExecutionJournalCompatible(db, minimumVersion = 2) {
+    assertExecutionStorageSchema(db, 'CREATE TABLE IF NOT EXISTS journal_meta (key TEXT NOT NULL PRIMARY KEY, value TEXT NOT NULL);');
+    const version = schemaVersion(db);
+    if (version < minimumVersion)
+        corrupt('schema version requires explicit operator migration');
+    const kinds = version === 2 ? "'mint','delegated','exit'" : version === 3
+        ? "'mint','delegated','exit','native'" : "'mint','delegated','exit','native','sponsored'";
+    assertExecutionStorageSchema(db, `CREATE TABLE IF NOT EXISTS user_execution_claims ${CLAIM_TABLE.replace("'mint','delegated','exit','native','sponsored'", kinds)};`);
+    const coverage = meta(db, 'unified_claims_coverage_started_at');
+    const readyAt = meta(db, 'unified_claims_ready_at');
+    if (!validTime(coverage) || (readyAt !== undefined && !validTime(readyAt)))
+        corrupt('rollout markers');
+    if (readyAt !== undefined && Date.parse(readyAt) < Date.parse(coverage))
+        corrupt('ready marker predates coverage');
+    for (const [prefix, introduced] of [['native', 3], ['sponsored', 4], ['native_userop_records', 5], ['lp_userop_records', 6]]) {
+        const began = meta(db, `${prefix}_claims_coverage_started_at`), ready = meta(db, `${prefix}_claims_ready_at`);
+        if (version < introduced) {
+            if (began !== undefined || ready !== undefined)
+                corrupt(`${prefix} markers predate schema`);
+        }
+        else {
+            if (!validTime(began) || (ready !== undefined && !validTime(ready)))
+                corrupt(`${prefix} rollout markers`);
+            if (ready !== undefined && Date.parse(ready) < Date.parse(began))
+                corrupt(`${prefix} ready marker predates coverage`);
+            if (ready !== undefined && readyAt === undefined)
+                corrupt(`${prefix} readiness has no legacy drain attestation`);
+        }
+    }
+}
+export function readExecutionJournalStatus(db) {
+    assertExecutionJournalCompatible(db);
+    return Object.freeze({
+        schemaVersion: schemaVersion(db),
+        ready: meta(db, 'unified_claims_ready_at') !== undefined,
+        coverageStartedAt: meta(db, 'unified_claims_coverage_started_at'),
+        nativeReady: meta(db, 'native_claims_ready_at') !== undefined,
+        nativeCoverageStartedAt: meta(db, 'native_claims_coverage_started_at') ?? null,
+        sponsoredReady: meta(db, 'sponsored_claims_ready_at') !== undefined,
+        sponsoredCoverageStartedAt: meta(db, 'sponsored_claims_coverage_started_at') ?? null,
+        nativeUserOpReady: meta(db, 'native_userop_records_claims_ready_at') !== undefined,
+        nativeUserOpCoverageStartedAt: meta(db, 'native_userop_records_claims_coverage_started_at') ?? null,
+        lpUserOpReady: meta(db, 'lp_userop_records_claims_ready_at') !== undefined,
+        lpUserOpCoverageStartedAt: meta(db, 'lp_userop_records_claims_coverage_started_at') ?? null,
+    });
+}
+export function requireExecutionJournalReady(db) {
+    if (!readExecutionJournalStatus(db).ready)
+        throw new ExecutionJournalNotReadyError();
+}
+export function requireNativeExecutionJournalReady(db) {
+    const status = readExecutionJournalStatus(db);
+    if (!status.ready || !status.nativeReady)
+        throw new ExecutionJournalNotReadyError();
+}
+export function requireSponsoredExecutionJournalReady(db) {
+    const status = readExecutionJournalStatus(db);
+    if (!status.ready || !status.sponsoredReady)
+        throw new ExecutionJournalNotReadyError();
+}
+/** v2 native records require a new reader rollout. Existing v4 sponsorship readiness is insufficient. */
+export function requireNativeUserOpJournalReady(db) {
+    const status = readExecutionJournalStatus(db);
+    if (status.schemaVersion < 5 || !status.ready || !status.sponsoredReady || !status.nativeUserOpReady)
+        throw new ExecutionJournalNotReadyError();
+}
+/** Operator-only transaction after draining every v4 worker; no table, record or claim is rewritten. */
+export function migrateNativeUserOpJournal(db, nowMs, expected) {
+    if (db.isTransaction !== true)
+        throw new Error('native UserOp migration requires the owning rollout transaction');
+    assertExecutionJournalCompatible(db, 4);
+    validateClaims(db);
+    assertDeclaredExecutionStorage(db, schemaVersion(db));
+    const before = readExecutionJournalStatus(db);
+    if (before.schemaVersion !== 4 || !before.ready || !before.sponsoredReady ||
+        before.coverageStartedAt !== expected.coverageStartedAt ||
+        before.sponsoredCoverageStartedAt !== expected.sponsoredCoverageStartedAt ||
+        !Number.isSafeInteger(nowMs) || nowMs < Math.max(Date.parse(before.sponsoredCoverageStartedAt), Date.parse(meta(db, 'unified_claims_ready_at')), Date.parse(meta(db, 'sponsored_claims_ready_at'))))
+        throw new Error('native UserOp migration precondition mismatch');
+    db.prepare("UPDATE journal_meta SET value='5' WHERE key='schema_version'").run();
+    db.prepare("INSERT INTO journal_meta(key,value) VALUES('native_userop_records_claims_coverage_started_at',?)")
+        .run(new Date(nowMs).toISOString());
+    assertExecutionJournalCompatible(db, 5);
+    assertDeclaredExecutionStorage(db, 5);
+    return readExecutionJournalStatus(db);
+}
+/** A separate explicit attestation that all deployed readers understand native version-2 records. */
+export function markNativeUserOpReadyAfterDrain(db, nowMs) {
+    if (db.isTransaction !== true)
+        throw new Error('native UserOp readiness requires the owning rollout transaction');
+    assertExecutionJournalCompatible(db, 5);
+    requireSponsoredExecutionJournalReady(db);
+    const status = readExecutionJournalStatus(db), began = status.nativeUserOpCoverageStartedAt;
+    if (!began || !Number.isSafeInteger(nowMs) || nowMs < Date.parse(began))
+        throw new Error('invalid native UserOp drain attestation time');
+    db.prepare("INSERT OR IGNORE INTO journal_meta(key,value) VALUES('native_userop_records_claims_ready_at',?)")
+        .run(new Date(nowMs).toISOString());
+    return readExecutionJournalStatus(db);
+}
+/** LP record v3 is another explicit reader rollout; prior native readiness does not grant LP admission. */
+export function requireLpUserOpJournalReady(db) {
+    const status = readExecutionJournalStatus(db);
+    if (status.schemaVersion !== 6 || !status.ready || !status.sponsoredReady || !status.lpUserOpReady)
+        throw new ExecutionJournalNotReadyError();
+}
+export function migrateLpUserOpJournal(db, nowMs, expected) {
+    if (db.isTransaction !== true)
+        throw new Error('LP UserOp migration requires the owning rollout transaction');
+    assertExecutionJournalCompatible(db, 5);
+    validateClaims(db);
+    assertDeclaredExecutionStorage(db, schemaVersion(db));
+    const before = readExecutionJournalStatus(db);
+    const lastMarker = Math.max(...['unified_claims_coverage_started_at', 'unified_claims_ready_at',
+        'native_claims_coverage_started_at', 'native_claims_ready_at', 'sponsored_claims_coverage_started_at',
+        'sponsored_claims_ready_at', 'native_userop_records_claims_coverage_started_at', 'native_userop_records_claims_ready_at']
+        .map(key => meta(db, key)).filter((value) => value !== undefined).map(Date.parse));
+    if (before.schemaVersion !== 5 || !before.ready || !before.sponsoredReady ||
+        before.coverageStartedAt !== expected.coverageStartedAt ||
+        before.sponsoredCoverageStartedAt !== expected.sponsoredCoverageStartedAt ||
+        before.nativeUserOpCoverageStartedAt !== expected.nativeUserOpCoverageStartedAt ||
+        !Number.isSafeInteger(nowMs) || nowMs < lastMarker)
+        throw new Error('LP UserOp migration precondition mismatch');
+    db.prepare("UPDATE journal_meta SET value='6' WHERE key='schema_version'").run();
+    db.prepare("INSERT INTO journal_meta(key,value) VALUES('lp_userop_records_claims_coverage_started_at',?)")
+        .run(new Date(nowMs).toISOString());
+    assertExecutionJournalCompatible(db, 6);
+    assertDeclaredExecutionStorage(db, 6);
+    return readExecutionJournalStatus(db);
+}
+export function markLpUserOpReadyAfterDrain(db, nowMs) {
+    if (db.isTransaction !== true)
+        throw new Error('LP UserOp readiness requires the owning rollout transaction');
+    assertExecutionJournalCompatible(db, 6);
+    requireSponsoredExecutionJournalReady(db);
+    const status = readExecutionJournalStatus(db), began = status.lpUserOpCoverageStartedAt;
+    if (!began || !Number.isSafeInteger(nowMs) || nowMs < Date.parse(began))
+        throw new Error('invalid LP UserOp drain attestation time');
+    db.prepare("INSERT OR IGNORE INTO journal_meta(key,value) VALUES('lp_userop_records_claims_ready_at',?)")
+        .run(new Date(nowMs).toISOString());
+    return readExecutionJournalStatus(db);
+}
+/** Explicit operator attestation that every worker understands sponsored claims; migration alone cannot enable sends. */
+export function markSponsoredExecutionReadyAfterLegacyDrain(db, nowMs) {
+    if (db.isTransaction !== true)
+        throw new Error('sponsored readiness requires the owning rollout transaction');
+    requireExecutionJournalReady(db);
+    const coverage = readExecutionJournalStatus(db).sponsoredCoverageStartedAt;
+    if (coverage === null || !Number.isSafeInteger(nowMs) || nowMs < Date.parse(coverage))
+        throw new Error('invalid sponsored drain attestation time');
+    db.prepare("INSERT OR IGNORE INTO journal_meta (key,value) VALUES ('sponsored_claims_ready_at',?)").run(new Date(nowMs).toISOString());
+    return readExecutionJournalStatus(db);
+}
+/** Explicit native rollout attestation, separate from the existing public Base rollout action. */
+export function markNativeExecutionReadyAfterLegacyDrain(db, nowMs) {
+    if (db.isTransaction !== true)
+        throw new Error('native readiness requires the owning rollout transaction');
+    requireExecutionJournalReady(db);
+    const coverage = readExecutionJournalStatus(db).nativeCoverageStartedAt;
+    if (coverage === null || !Number.isSafeInteger(nowMs) || nowMs < Date.parse(coverage))
+        throw new Error('invalid native drain attestation time');
+    db.prepare("INSERT OR IGNORE INTO journal_meta (key,value) VALUES ('native_claims_ready_at',?)")
+        .run(new Date(nowMs).toISOString());
+    return readExecutionJournalStatus(db);
+}
+export function executionClaimFromRow(row) {
+    if (row === undefined)
+        return undefined;
+    if (!row || typeof row !== 'object')
+        return corrupt('claim row');
+    const item = row;
+    if (typeof item.user_id !== 'string' || !END_USER_ID_PATTERN.test(item.user_id) ||
+        typeof item.kind !== 'string' || !USER_EXECUTION_CLAIM_KINDS.includes(item.kind) ||
+        typeof item.claim_id !== 'string' || item.claim_id.length < 1)
+        corrupt('claim identity');
+    const generation = item.claim_generation;
+    if (item.kind === 'mint'
+        ? typeof generation !== 'number' || !Number.isSafeInteger(generation) || generation < 0
+        : generation !== null)
+        corrupt('claim Stop generation');
+    return Object.freeze({
+        userId: item.user_id,
+        kind: item.kind,
+        claimId: item.claim_id,
+        ...(generation === null ? {} : { claimGeneration: generation }),
+    });
+}
+export function readUserExecutionClaim(db, userId) {
+    if (!END_USER_ID_PATTERN.test(userId))
+        throw new Error('invalid claim end user');
+    assertExecutionJournalCompatible(db);
+    return executionClaimFromRow(db.prepare('SELECT user_id,kind,claim_id,claim_generation FROM user_execution_claims WHERE user_id = ?').get(userId));
+}
+function validateClaims(db) {
+    const version = schemaVersion(db);
+    const rows = db.prepare('SELECT * FROM user_execution_claims ORDER BY user_id').all();
+    for (const row of rows) {
+        const claim = executionClaimFromRow(row);
+        if ((claim.kind === 'native' && version < 3) || (claim.kind === 'sponsored' && version < 4))
+            corrupt('claim predates schema');
+        if (![row.created_at_ms, row.updated_at_ms].every((time) => typeof time === 'number' && Number.isSafeInteger(time) && time >= 0))
+            corrupt('claim timestamps');
+    }
+}
+function hasStorage(db) {
+    return db.prepare("SELECT name FROM sqlite_master WHERE name NOT LIKE 'sqlite_%' LIMIT 1").get() !== undefined;
+}
+/**
+ * Fresh databases are initialized atomically, unready, with all storage contracts. Existing databases
+ * are only validated unless the operator supplies the exact prior version and coverage after draining
+ * every old writer. Ordinary status, construction and hosted startup can never widen a live journal.
+ */
+export function initializeExecutionJournal(db, nowMs, expectedPrior) {
+    if (!Number.isSafeInteger(nowMs) || nowMs < 0)
+        throw new Error('invalid journal migration time');
+    if (!expectedPrior && hasStorage(db)) {
+        assertExecutionJournalCompatible(db);
+        validateClaims(db);
+        assertDeclaredExecutionStorage(db, schemaVersion(db));
+        return;
+    }
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        // Recheck after the write lock: another fresh opener or operator may have won.
+        if (!expectedPrior && hasStorage(db)) {
+            assertExecutionJournalCompatible(db);
+            validateClaims(db);
+            assertDeclaredExecutionStorage(db, schemaVersion(db));
+            db.exec('COMMIT');
+            return;
+        }
+        if (expectedPrior) {
+            if (!['2', '3'].includes(expectedPrior.schemaVersion) || !validTime(expectedPrior.coverageStartedAt) ||
+                new Date(expectedPrior.coverageStartedAt).toISOString() !== expectedPrior.coverageStartedAt)
+                throw new Error('invalid expected journal migration state');
+            if (meta(db, 'schema_version') !== expectedPrior.schemaVersion ||
+                meta(db, 'unified_claims_coverage_started_at') !== expectedPrior.coverageStartedAt)
+                throw new Error('journal migration precondition mismatch: schema or coverage changed; no migration was made');
+            assertExecutionJournalCompatible(db);
+            validateClaims(db);
+            assertDeclaredExecutionStorage(db, schemaVersion(db));
+            if (db.prepare("SELECT name FROM sqlite_master WHERE name='user_execution_claims_v4'").get())
+                corrupt('migration table already exists');
+            const before = db.prepare('SELECT * FROM user_execution_claims ORDER BY user_id').all();
+            db.exec(`CREATE TABLE user_execution_claims_v4 ${CLAIM_TABLE}`);
+            db.exec(`INSERT INTO user_execution_claims_v4 (${CLAIM_COLUMNS.join(',')}) SELECT ${CLAIM_COLUMNS.join(',')} FROM user_execution_claims`);
+            if (JSON.stringify(before) !== JSON.stringify(db.prepare('SELECT * FROM user_execution_claims_v4 ORDER BY user_id').all()))
+                corrupt('claim migration changed rows');
+            db.exec('DROP TABLE user_execution_claims; ALTER TABLE user_execution_claims_v4 RENAME TO user_execution_claims');
+        }
+        else {
+            db.exec('CREATE TABLE journal_meta (key TEXT NOT NULL PRIMARY KEY, value TEXT NOT NULL)');
+            db.exec(`CREATE TABLE user_execution_claims ${CLAIM_TABLE}`);
+            db.prepare("INSERT INTO journal_meta (key,value) VALUES ('unified_claims_coverage_started_at',?)").run(new Date(nowMs).toISOString());
+        }
+        db.exec(EXECUTION_STORAGE_SCHEMA);
+        db.prepare("INSERT OR REPLACE INTO journal_meta (key,value) VALUES ('schema_version','4')").run();
+        if (!expectedPrior || expectedPrior.schemaVersion === '2') {
+            db.prepare("INSERT INTO journal_meta (key,value) VALUES ('native_claims_coverage_started_at',?)").run(new Date(nowMs).toISOString());
+        }
+        db.prepare("INSERT INTO journal_meta (key,value) VALUES ('sponsored_claims_coverage_started_at',?)").run(new Date(nowMs).toISOString());
+        assertExecutionJournalCompatible(db);
+        validateClaims(db);
+        assertDeclaredExecutionStorage(db, 4);
+        db.exec('COMMIT');
+    }
+    catch (error) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch { /* preserve the original error */ }
+        throw error;
+    }
+}
+function assertNativeClaimTransaction(db, binding, minimumVersion = 3) {
+    if (db.isTransaction !== true)
+        throw new Error('native claims require the owning operation transaction');
+    if (!END_USER_ID_PATTERN.test(binding.userId) || !/^[a-zA-Z0-9_-]{8,128}$/.test(binding.operationId))
+        throw new Error('invalid native claim binding');
+    assertExecutionJournalCompatible(db, minimumVersion);
+}
+/** Call inside the transaction that also creates the native operation row. No standalone reservation. */
+export function claimNativeExecution(db, binding, nowMs) {
+    assertNativeClaimTransaction(db, binding);
+    if (!Number.isSafeInteger(nowMs) || nowMs < 0)
+        throw new Error('invalid native claim time');
+    const claim = readUserExecutionClaim(db, binding.userId);
+    if (claim)
+        return claim.kind === 'native' && claim.claimId === binding.operationId
+            ? { outcome: 'existing' } : { outcome: 'conflict', claim };
+    requireNativeExecutionJournalReady(db);
+    db.prepare("INSERT INTO user_execution_claims (user_id,kind,claim_id,claim_generation,created_at_ms,updated_at_ms) VALUES (?,'native',?,NULL,?,?)")
+        .run(binding.userId, binding.operationId, nowMs, nowMs);
+    return { outcome: 'started' };
+}
+/** The caller must prove and record the native terminal outcome in this same transaction. */
+export function releaseNativeExecutionClaim(db, binding) {
+    assertNativeClaimTransaction(db, binding);
+    const claim = readUserExecutionClaim(db, binding.userId);
+    if (claim?.kind !== 'native' || claim.claimId !== binding.operationId)
+        throw new Error('native execution claim mismatch');
+    const result = db.prepare("DELETE FROM user_execution_claims WHERE user_id=? AND kind='native' AND claim_id=?")
+        .run(binding.userId, binding.operationId);
+    if (Number(result.changes) !== 1)
+        throw new Error('native execution claim release did not match exactly once');
+}
+/** Atomic companion to inserting/consuming a sponsored review in the same operations.db transaction. */
+export function claimSponsoredExecution(db, binding, nowMs) {
+    assertNativeClaimTransaction(db, binding, 4);
+    if (!Number.isSafeInteger(nowMs) || nowMs < 0)
+        throw new Error('invalid sponsored claim time');
+    const claim = readUserExecutionClaim(db, binding.userId);
+    if (claim)
+        return claim.kind === 'sponsored' && claim.claimId === binding.operationId
+            ? { outcome: 'existing' } : { outcome: 'conflict', claim };
+    requireSponsoredExecutionJournalReady(db);
+    db.prepare("INSERT INTO user_execution_claims (user_id,kind,claim_id,claim_generation,created_at_ms,updated_at_ms) VALUES (?,'sponsored',?,NULL,?,?)")
+        .run(binding.userId, binding.operationId, nowMs, nowMs);
+    return { outcome: 'started' };
+}
+/** Caller commits the proven terminal record in this same transaction. No TTL or provider-timeout release. */
+export function releaseSponsoredExecutionClaim(db, binding) {
+    assertNativeClaimTransaction(db, binding, 4);
+    const claim = readUserExecutionClaim(db, binding.userId);
+    if (claim?.kind !== 'sponsored' || claim.claimId !== binding.operationId)
+        throw new Error('sponsored execution claim mismatch');
+    const result = db.prepare("DELETE FROM user_execution_claims WHERE user_id=? AND kind='sponsored' AND claim_id=?").run(binding.userId, binding.operationId);
+    if (Number(result.changes) !== 1)
+        throw new Error('sponsored execution claim release did not match exactly once');
+}
+//# sourceMappingURL=execution-journal-schema.js.map

package/dist/execution-journal-tables.d.ts

@@ -0,0 +1,14 @@
+/** Canonical storage contracts. DDL runs only for empty initialization or explicit operator migration. */
+import type { ExecutionJournalDatabase } from './execution-journal-schema.js';
+export declare const LEGACY_OPERATION_SCHEMA = "CREATE TABLE IF NOT EXISTS operations (\n  artifact_id    TEXT    NOT NULL PRIMARY KEY,\n  user_id        TEXT    NOT NULL,\n  account        TEXT    NOT NULL,\n  chain_id       INTEGER NOT NULL CHECK (chain_id = 8453),\n  fingerprint    TEXT    NOT NULL,\n  state          TEXT    NOT NULL CHECK (state IN ('prepared','submitted','confirmed','failed','unknown')),\n  created_at_ms  INTEGER NOT NULL,\n  updated_at_ms  INTEGER NOT NULL,\n  recovery_context_json TEXT,\n  result_json    TEXT,\n  failure_code   TEXT\n);\nCREATE UNIQUE INDEX IF NOT EXISTS operations_one_unresolved_per_user\n  ON operations (user_id) WHERE state IN ('prepared','submitted','unknown');\nCREATE INDEX IF NOT EXISTS operations_user_updated\n  ON operations (user_id, updated_at_ms DESC);\nCREATE TABLE IF NOT EXISTS operation_steps (\n  artifact_id       TEXT    NOT NULL,\n  step_index        INTEGER NOT NULL CHECK (step_index >= 0 AND step_index <= 3),\n  step_kind         TEXT    NOT NULL CHECK (step_kind IN ('approve_reset','approve','call','allowance_clear')),\n  state             TEXT    NOT NULL CHECK (state IN ('prepared','submitted','confirmed','failed','unknown')),\n  request_json      TEXT    NOT NULL,\n  request_digest    TEXT    NOT NULL,\n  idempotency_key   TEXT    NOT NULL UNIQUE,\n  transaction_hash TEXT,\n  receipt_json      TEXT,\n  created_at_ms     INTEGER NOT NULL,\n  updated_at_ms     INTEGER NOT NULL,\n  PRIMARY KEY (artifact_id, step_index),\n  FOREIGN KEY (artifact_id) REFERENCES operations(artifact_id) ON DELETE CASCADE\n);\n";
+export declare const LEGACY_EXIT_SCHEMA = "CREATE TABLE IF NOT EXISTS exit_operations (\n  operation_id          TEXT    NOT NULL PRIMARY KEY,\n  user_id               TEXT    NOT NULL,\n  account               TEXT    NOT NULL,\n  destination           TEXT    NOT NULL,\n  amount_atomic         TEXT    NOT NULL,\n  state                 TEXT    NOT NULL CHECK (state IN ('preparing','signing','signed','submitted','unknown','confirmed','reverted','replaced','canceled')),\n  epoch                 INTEGER NOT NULL CHECK (epoch > 0),\n  owner_token_digest    TEXT,\n  lease_expires_at_ms   INTEGER,\n  search_from_block     TEXT,\n  transaction_json      TEXT,\n  signed_transaction    TEXT,\n  transaction_hash      TEXT,\n  broadcast_attempts    INTEGER NOT NULL DEFAULT 0 CHECK (broadcast_attempts >= 0),\n  receipt_json          TEXT,\n  finalized_nonce       TEXT,\n  replacement_transaction_hash TEXT,\n  replacement_block_number     TEXT,\n  replacement_block_hash       TEXT,\n  replacement_finalized_head_number TEXT,\n  replacement_finalized_head_hash   TEXT,\n  created_at_ms         INTEGER NOT NULL,\n  updated_at_ms         INTEGER NOT NULL\n);\nCREATE INDEX IF NOT EXISTS exit_operations_user_updated\n  ON exit_operations (user_id, updated_at_ms DESC);\nCREATE UNIQUE INDEX IF NOT EXISTS one_unresolved_exit_per_user\n  ON exit_operations (user_id)\n  WHERE state IN ('preparing','signing','signed','submitted','unknown');\n";
+export declare const NATIVE_CONSENT_SCHEMA = "\nCREATE TABLE IF NOT EXISTS native_yield_consent_subjects (\n  user_id TEXT NOT NULL,\n  account TEXT NOT NULL,\n  generation INTEGER NOT NULL CHECK (generation >= 0),\n  active_consent_id TEXT,\n  updated_at_ms INTEGER NOT NULL CHECK (updated_at_ms >= 0),\n  PRIMARY KEY (user_id, account)\n);\nCREATE TABLE IF NOT EXISTS native_yield_consents (\n  consent_id TEXT NOT NULL PRIMARY KEY,\n  user_id TEXT NOT NULL,\n  account TEXT NOT NULL,\n  authority_json TEXT NOT NULL,\n  consent_commitment TEXT NOT NULL,\n  generation INTEGER NOT NULL CHECK (generation > 0),\n  state TEXT NOT NULL CHECK (state IN ('challenge','confirmed','revoked','superseded')),\n  created_at_ms INTEGER NOT NULL CHECK (created_at_ms >= 0),\n  challenge_expires_at_ms INTEGER NOT NULL CHECK (challenge_expires_at_ms > created_at_ms),\n  confirmed_at_ms INTEGER,\n  FOREIGN KEY (user_id, account) REFERENCES native_yield_consent_subjects(user_id, account)\n);\nCREATE UNIQUE INDEX IF NOT EXISTS native_yield_consents_one_confirmed_subject\n  ON native_yield_consents(user_id, account) WHERE state = 'confirmed';\nCREATE INDEX IF NOT EXISTS native_yield_consents_subject_generation\n  ON native_yield_consents(user_id, account, generation);\nCREATE TRIGGER IF NOT EXISTS native_yield_consents_immutable_terms\nBEFORE UPDATE OF consent_id,user_id,account,authority_json,consent_commitment,generation,created_at_ms,challenge_expires_at_ms\nON native_yield_consents BEGIN\n  SELECT RAISE(ABORT, 'native consent challenge terms are immutable');\nEND;\nCREATE TRIGGER IF NOT EXISTS native_yield_consents_preserve_history\nBEFORE DELETE ON native_yield_consents BEGIN\n  SELECT RAISE(ABORT, 'native consent history is immutable');\nEND;\n";
+export declare const NATIVE_OPERATION_SCHEMA = "CREATE TABLE IF NOT EXISTS native_yield_operations (\n      operation_id TEXT PRIMARY KEY NOT NULL, user_id TEXT NOT NULL, record_json TEXT NOT NULL\n    ); CREATE INDEX IF NOT EXISTS native_yield_user ON native_yield_operations(user_id);";
+export declare const SPONSORED_OPERATION_SCHEMA = "CREATE TABLE IF NOT EXISTS sponsored_operations (\n      operation_id TEXT PRIMARY KEY NOT NULL, user_id TEXT NOT NULL, artifact_key TEXT NOT NULL,\n      record_json TEXT NOT NULL, UNIQUE(user_id,artifact_key));";
+export declare const EXECUTION_STORAGE_SCHEMA: string;
+/** Read-only: a missing/changed safety constraint requires operator repair, never a lazy CREATE. */
+export declare function assertExecutionStorageSchema(db: ExecutionJournalDatabase, expectedSql: string): void;
+/** Claim ownership must already be coherent. Startup never repairs history or invents claims. */
+export declare function assertLegacyExecutionRows(db: ExecutionJournalDatabase): void;
+/** Validate the declared source version BEFORE any migration can install missing later-rail objects. */
+export declare function assertDeclaredExecutionStorage(db: ExecutionJournalDatabase, version: 2 | 3 | 4 | 5 | 6): void;

package/dist/execution-journal-tables.js

@@ -0,0 +1,227 @@
+export const LEGACY_OPERATION_SCHEMA = `CREATE TABLE IF NOT EXISTS operations (
+  artifact_id    TEXT    NOT NULL PRIMARY KEY,
+  user_id        TEXT    NOT NULL,
+  account        TEXT    NOT NULL,
+  chain_id       INTEGER NOT NULL CHECK (chain_id = 8453),
+  fingerprint    TEXT    NOT NULL,
+  state          TEXT    NOT NULL CHECK (state IN ('prepared','submitted','confirmed','failed','unknown')),
+  created_at_ms  INTEGER NOT NULL,
+  updated_at_ms  INTEGER NOT NULL,
+  recovery_context_json TEXT,
+  result_json    TEXT,
+  failure_code   TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS operations_one_unresolved_per_user
+  ON operations (user_id) WHERE state IN ('prepared','submitted','unknown');
+CREATE INDEX IF NOT EXISTS operations_user_updated
+  ON operations (user_id, updated_at_ms DESC);
+CREATE TABLE IF NOT EXISTS operation_steps (
+  artifact_id       TEXT    NOT NULL,
+  step_index        INTEGER NOT NULL CHECK (step_index >= 0 AND step_index <= 3),
+  step_kind         TEXT    NOT NULL CHECK (step_kind IN ('approve_reset','approve','call','allowance_clear')),
+  state             TEXT    NOT NULL CHECK (state IN ('prepared','submitted','confirmed','failed','unknown')),
+  request_json      TEXT    NOT NULL,
+  request_digest    TEXT    NOT NULL,
+  idempotency_key   TEXT    NOT NULL UNIQUE,
+  transaction_hash TEXT,
+  receipt_json      TEXT,
+  created_at_ms     INTEGER NOT NULL,
+  updated_at_ms     INTEGER NOT NULL,
+  PRIMARY KEY (artifact_id, step_index),
+  FOREIGN KEY (artifact_id) REFERENCES operations(artifact_id) ON DELETE CASCADE
+);
+`;
+export const LEGACY_EXIT_SCHEMA = `CREATE TABLE IF NOT EXISTS exit_operations (
+  operation_id          TEXT    NOT NULL PRIMARY KEY,
+  user_id               TEXT    NOT NULL,
+  account               TEXT    NOT NULL,
+  destination           TEXT    NOT NULL,
+  amount_atomic         TEXT    NOT NULL,
+  state                 TEXT    NOT NULL CHECK (state IN ('preparing','signing','signed','submitted','unknown','confirmed','reverted','replaced','canceled')),
+  epoch                 INTEGER NOT NULL CHECK (epoch > 0),
+  owner_token_digest    TEXT,
+  lease_expires_at_ms   INTEGER,
+  search_from_block     TEXT,
+  transaction_json      TEXT,
+  signed_transaction    TEXT,
+  transaction_hash      TEXT,
+  broadcast_attempts    INTEGER NOT NULL DEFAULT 0 CHECK (broadcast_attempts >= 0),
+  receipt_json          TEXT,
+  finalized_nonce       TEXT,
+  replacement_transaction_hash TEXT,
+  replacement_block_number     TEXT,
+  replacement_block_hash       TEXT,
+  replacement_finalized_head_number TEXT,
+  replacement_finalized_head_hash   TEXT,
+  created_at_ms         INTEGER NOT NULL,
+  updated_at_ms         INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS exit_operations_user_updated
+  ON exit_operations (user_id, updated_at_ms DESC);
+CREATE UNIQUE INDEX IF NOT EXISTS one_unresolved_exit_per_user
+  ON exit_operations (user_id)
+  WHERE state IN ('preparing','signing','signed','submitted','unknown');
+`;
+export const NATIVE_CONSENT_SCHEMA = `
+CREATE TABLE IF NOT EXISTS native_yield_consent_subjects (
+  user_id TEXT NOT NULL,
+  account TEXT NOT NULL,
+  generation INTEGER NOT NULL CHECK (generation >= 0),
+  active_consent_id TEXT,
+  updated_at_ms INTEGER NOT NULL CHECK (updated_at_ms >= 0),
+  PRIMARY KEY (user_id, account)
+);
+CREATE TABLE IF NOT EXISTS native_yield_consents (
+  consent_id TEXT NOT NULL PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  account TEXT NOT NULL,
+  authority_json TEXT NOT NULL,
+  consent_commitment TEXT NOT NULL,
+  generation INTEGER NOT NULL CHECK (generation > 0),
+  state TEXT NOT NULL CHECK (state IN ('challenge','confirmed','revoked','superseded')),
+  created_at_ms INTEGER NOT NULL CHECK (created_at_ms >= 0),
+  challenge_expires_at_ms INTEGER NOT NULL CHECK (challenge_expires_at_ms > created_at_ms),
+  confirmed_at_ms INTEGER,
+  FOREIGN KEY (user_id, account) REFERENCES native_yield_consent_subjects(user_id, account)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS native_yield_consents_one_confirmed_subject
+  ON native_yield_consents(user_id, account) WHERE state = 'confirmed';
+CREATE INDEX IF NOT EXISTS native_yield_consents_subject_generation
+  ON native_yield_consents(user_id, account, generation);
+CREATE TRIGGER IF NOT EXISTS native_yield_consents_immutable_terms
+BEFORE UPDATE OF consent_id,user_id,account,authority_json,consent_commitment,generation,created_at_ms,challenge_expires_at_ms
+ON native_yield_consents BEGIN
+  SELECT RAISE(ABORT, 'native consent challenge terms are immutable');
+END;
+CREATE TRIGGER IF NOT EXISTS native_yield_consents_preserve_history
+BEFORE DELETE ON native_yield_consents BEGIN
+  SELECT RAISE(ABORT, 'native consent history is immutable');
+END;
+`;
+export const NATIVE_OPERATION_SCHEMA = `CREATE TABLE IF NOT EXISTS native_yield_operations (
+      operation_id TEXT PRIMARY KEY NOT NULL, user_id TEXT NOT NULL, record_json TEXT NOT NULL
+    ); CREATE INDEX IF NOT EXISTS native_yield_user ON native_yield_operations(user_id);`;
+export const SPONSORED_OPERATION_SCHEMA = `CREATE TABLE IF NOT EXISTS sponsored_operations (
+      operation_id TEXT PRIMARY KEY NOT NULL, user_id TEXT NOT NULL, artifact_key TEXT NOT NULL,
+      record_json TEXT NOT NULL, UNIQUE(user_id,artifact_key));`;
+export const EXECUTION_STORAGE_SCHEMA = LEGACY_OPERATION_SCHEMA + LEGACY_EXIT_SCHEMA +
+    NATIVE_CONSENT_SCHEMA + NATIVE_OPERATION_SCHEMA + SPONSORED_OPERATION_SCHEMA;
+// Compare independent schema terms without depending on nullable-column insertion order.
+// SQLite may quote a renamed table, but table constraints, indexes and triggers must be exact.
+function compact(sql) {
+    // Whitespace inside SQL literals is data. Never normalize a changed CHECK/string into acceptance.
+    return sql.replace(/'(?:''|[^'])*'|"(?:[^"]|"")*"|\s+|IF\s+NOT\s+EXISTS/gi, (token) => token.startsWith("'") ? token : token.startsWith('"') ? token.slice(1, -1) : '').replace(/;$/, '');
+}
+function tableTerms(sql) {
+    const start = sql.indexOf('('), end = sql.lastIndexOf(')');
+    if (start < 0 || end <= start || compact(sql.slice(end + 1)) !== '')
+        throw new Error('the shared execution journal is corrupt or unsupported (storage table options)');
+    const parts = [];
+    let depth = 0, quote = false, from = start + 1;
+    for (let i = from; i < end; i++) {
+        if (sql[i] === "'")
+            quote = !quote;
+        if (!quote) {
+            if (sql[i] === '(')
+                depth++;
+            if (sql[i] === ')')
+                depth--;
+            if (sql[i] === ',' && depth === 0) {
+                parts.push(compact(sql.slice(from, i)));
+                from = i + 1;
+            }
+        }
+    }
+    parts.push(compact(sql.slice(from, end)));
+    return parts;
+}
+function sameTable(actual, expected, name) {
+    const actualTerms = JSON.stringify(tableTerms(actual)), expectedTerms = tableTerms(expected);
+    if (actualTerms === JSON.stringify(expectedTerms))
+        return true;
+    // Historical ALTER TABLE appended these exact nullable recovery columns. No other reordering is supported.
+    const additions = name === 'operations' ? ['recovery_context_jsonTEXT'] : [];
+    return additions.length > 0 && actualTerms === JSON.stringify([
+        ...expectedTerms.filter(term => !additions.includes(term)), ...additions,
+    ]);
+}
+/** Read-only: a missing/changed safety constraint requires operator repair, never a lazy CREATE. */
+export function assertExecutionStorageSchema(db, expectedSql) {
+    const expected = [...expectedSql.matchAll(/CREATE\s+(?:UNIQUE\s+)?(TABLE|INDEX|TRIGGER)\s+IF NOT EXISTS\s+(\w+)[\s\S]*?(?=CREATE\s+(?:UNIQUE\s+)?(?:TABLE|INDEX|TRIGGER)\s+IF NOT EXISTS|$)/g)];
+    const names = new Set(expected.map(entry => entry[2]));
+    for (const entry of expected) {
+        const kind = entry[1].toLowerCase(), name = entry[2];
+        const row = db.prepare('SELECT sql FROM sqlite_master WHERE type=? AND name=?').get(kind, name);
+        if (typeof row?.sql !== 'string' || (kind === 'table'
+            ? !sameTable(row.sql, entry[0], name) : compact(row.sql) !== compact(entry[0])))
+            throw new Error(`the shared execution journal is corrupt or unsupported (storage contract ${name})`);
+        if (kind === 'table') {
+            const attached = db.prepare("SELECT name FROM sqlite_master WHERE tbl_name=? AND type IN ('index','trigger') AND name NOT LIKE 'sqlite_%'")
+                .all(name);
+            if (attached.some(object => !names.has(object.name)))
+                throw new Error(`the shared execution journal is corrupt or unsupported (unrecognized storage index or trigger on ${name})`);
+        }
+    }
+}
+/** Claim ownership must already be coherent. Startup never repairs history or invents claims. */
+export function assertLegacyExecutionRows(db) {
+    for (const [table, id, kind, states] of [
+        ['operations', 'artifact_id', 'delegated', "'prepared','submitted','unknown'"],
+        ['exit_operations', 'operation_id', 'exit', "'preparing','signing','signed','submitted','unknown'"],
+    ]) {
+        if (db.prepare(`SELECT o.${id} FROM ${table} o LEFT JOIN user_execution_claims c
+      ON c.user_id=o.user_id AND c.kind=? AND c.claim_id=o.${id}
+      WHERE o.state IN (${states}) AND c.user_id IS NULL LIMIT 1`).get(kind) ||
+            db.prepare(`SELECT c.claim_id FROM user_execution_claims c LEFT JOIN ${table} o
+      ON o.user_id=c.user_id AND o.${id}=c.claim_id AND o.state IN (${states})
+      WHERE c.kind=? AND o.${id} IS NULL LIMIT 1`).get(kind))
+            throw new Error(`the shared execution journal is corrupt or unsupported (${kind} unresolved claim binding)`);
+    }
+}
+/** Validate the declared source version BEFORE any migration can install missing later-rail objects. */
+export function assertDeclaredExecutionStorage(db, version) {
+    assertExecutionStorageSchema(db, LEGACY_OPERATION_SCHEMA + LEGACY_EXIT_SCHEMA);
+    assertLegacyExecutionRows(db);
+    for (const [kind, table, introduced, sql] of [
+        ['native', 'native_yield_operations', 3, NATIVE_CONSENT_SCHEMA + NATIVE_OPERATION_SCHEMA],
+        ['sponsored', 'sponsored_operations', 4, SPONSORED_OPERATION_SCHEMA],
+    ]) {
+        if (version < introduced) {
+            // A version label cannot hide storage from a newer rail. Even partial/empty tables may contain
+            // evidence no older writer can bind to a claim; startup and migration must leave them untouched.
+            for (const [, name] of sql.matchAll(/CREATE TABLE IF NOT EXISTS (\w+)/g)) {
+                if (db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=? COLLATE NOCASE").get(name))
+                    throw new Error(`the shared execution journal is corrupt or unsupported (${kind} storage predates schema)`);
+            }
+            continue;
+        }
+        assertExecutionStorageSchema(db, sql);
+        // Inspect unresolved identity/state only; terminal financial records retain their on-demand validator.
+        if (db.prepare(`SELECT operation_id FROM ${table} WHERE NOT json_valid(record_json) LIMIT 1`).get())
+            throw new Error(`the shared execution journal is corrupt or unsupported (${kind} operation JSON)`);
+        if (kind === 'sponsored' && db.prepare(`SELECT operation_id FROM sponsored_operations WHERE
+      json_type(record_json,'$.version') IS NOT 'integer' OR
+      json_extract(record_json,'$.version') NOT IN (${version < 5 ? '1' : version < 6 ? '1,2' : '1,2,3'}) LIMIT 1`).get())
+            throw new Error('the shared execution journal is corrupt or unsupported (sponsored record reader version)');
+        const states = kind === 'native' ? "'review','active','confirming','completed','failed','attention'"
+            : "'review','active','unknown','submitted','completed','failed'";
+        if (db.prepare(`SELECT operation_id FROM ${table} WHERE
+      json_type(record_json,'$.operationId') IS NOT 'text' OR json_extract(record_json,'$.operationId') IS NOT operation_id OR
+      json_type(record_json,'$.userId') IS NOT 'text' OR json_extract(record_json,'$.userId') IS NOT user_id OR
+      COALESCE(json_type(record_json,'$.reviewConsumed'),'missing') NOT IN ('true','false') OR
+      json_type(record_json,'$.state') IS NOT 'text' OR json_extract(record_json,'$.state') NOT IN (${states}) OR
+      (json_extract(record_json,'$.state')='review') IS NOT (json_extract(record_json,'$.reviewConsumed')=0)
+      LIMIT 1`).get())
+            throw new Error(`the shared execution journal is corrupt or unsupported (${kind} operation header)`);
+        const unresolved = "json_extract(o.record_json,'$.reviewConsumed')=1 AND json_extract(o.record_json,'$.state') NOT IN ('completed','failed')";
+        if (db.prepare(`SELECT o.operation_id FROM ${table} o LEFT JOIN user_execution_claims c
+      ON c.user_id=o.user_id AND c.kind=? AND c.claim_id=o.operation_id
+      WHERE (${unresolved}) AND (c.user_id IS NULL OR json_extract(o.record_json,'$.userId')!=o.user_id
+        OR json_extract(o.record_json,'$.operationId')!=o.operation_id) LIMIT 1`).get(kind) ||
+            db.prepare(`SELECT c.claim_id FROM user_execution_claims c LEFT JOIN ${table} o
+      ON o.user_id=c.user_id AND o.operation_id=c.claim_id AND (${unresolved})
+      WHERE c.kind=? AND o.operation_id IS NULL LIMIT 1`).get(kind))
+            throw new Error(`the shared execution journal is corrupt or unsupported (${kind} unresolved claim binding)`);
+    }
+}
+//# sourceMappingURL=execution-journal-tables.js.map