@stelis/say-ur-intent 0.0.3 → 0.0.4

package/dist/core/activity/sqliteActivityStore.js

@@ -1,4 +1,4 @@
-import { mkdirSync } from "node:fs";
+import { chmodSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import Database from "better-sqlite3";
@@ -7,6 +7,8 @@ import { parseLifecycleValidatedReviewState } from "../action/reviewStateValidat
 import { actionPlanSchema, executionResultSchema } from "../action/schemas.js";
 import { parseSuiAddress } from "../suiAddress.js";
 import { SqlitePreferencesRepository } from "../preferences/sqlitePreferencesRepository.js";
+import { SqliteTransactionMaterialStore } from "../session/sqliteTransactionMaterialStore.js";
+import { SqliteSessionRecordStore, SqlitePrivateReviewArtifactStore, createSqliteWalletIdentityRecordStore, createSqliteSettingsRecordStore } from "../session/sqliteSessionStore.js";
 import { SqliteLocalDataService } from "./localDataService.js";
 import { ActivityStoreReadError, REVIEW_ACTIVITY_DETAIL_MAX_ITEMS, REVIEW_ACTIVITY_LOW_SAMPLE_THRESHOLD } from "./activityStore.js";
 import { configureDatabase, initializeDatabase } from "./sqliteActivityStoreSchema.js";
@@ -16,13 +18,24 @@ export { ActivityStoreError };
 const ACTIVE_ACCOUNT_SINGLETON_ID = 1;
 export const DATA_DIR_ENV = "SAY_UR_INTENT_DATA_DIR";
 export const ACTIVITY_DATABASE_FILENAME = "say-ur-intent.sqlite";
+// Best-effort permission hardening. The owner-only data directory is the primary
+// protection; failures (e.g. on Windows, which ignores POSIX modes) are non-fatal.
+function restrictPathPermissions(path, mode) {
+    try {
+        chmodSync(path, mode);
+    }
+    catch {
+        // Non-fatal: the 0700 directory remains the primary protection.
+    }
+}
 export class SqliteActivityStore {
     db;
     validateAdapterLifecycle;
     constructor(options) {
         this.validateAdapterLifecycle = options.validateAdapterLifecycle;
+        const dataDirectory = dirname(options.databasePath);
         try {
-            mkdirSync(dirname(options.databasePath), { recursive: true });
+            mkdirSync(dataDirectory, { recursive: true, mode: 0o700 });
         }
         catch {
             throw new ActivityStoreError(`Could not create the local activity data directory. Check directory permissions or set ${DATA_DIR_ENV}.`);
@@ -36,6 +49,12 @@ export class SqliteActivityStore {
             this.db.close();
             throw error;
         }
+        // This database persists unsigned transaction material (Option B), so restrict it to
+        // the owner. The 0700 directory is the primary protection (it also covers the WAL/SHM
+        // sidecars and blocks other OS users); the 0600 file is belt-and-suspenders. Best-effort
+        // because some platforms (e.g. Windows) ignore POSIX modes.
+        restrictPathPermissions(dataDirectory, 0o700);
+        restrictPathPermissions(options.databasePath, 0o600);
     }
     async upsertAccount(address, source, now = new Date()) {
         return this.upsertAccountSync(address, source, now.toISOString());
@@ -613,6 +632,21 @@ export class SqliteActivityStore {
     createCoinMetadataCache() {
         return new SqliteCoinMetadataCache(this.db);
     }
+    createTransactionMaterialStore() {
+        return new SqliteTransactionMaterialStore(this.db);
+    }
+    createSessionRecordStore() {
+        return new SqliteSessionRecordStore(this.db);
+    }
+    createPrivateReviewArtifactStore() {
+        return new SqlitePrivateReviewArtifactStore(this.db);
+    }
+    createWalletIdentityRecordStore() {
+        return createSqliteWalletIdentityRecordStore(this.db);
+    }
+    createSettingsRecordStore() {
+        return createSqliteSettingsRecordStore(this.db);
+    }
     upsertAccountSync(address, source, timestamp) {
         const normalized = parseSuiAddress(address);
         if (!normalized) {

package/dist/core/activity/sqliteActivityStoreSchema.js

@@ -7,6 +7,9 @@ export function configureDatabase(db) {
     db.exec("PRAGMA journal_mode=WAL");
     db.exec("PRAGMA synchronous=NORMAL");
     db.exec("PRAGMA foreign_keys=ON");
+    // Multiple client processes share this database; wait instead of failing with
+    // SQLITE_BUSY when another process holds the write lock.
+    db.exec("PRAGMA busy_timeout=5000");
 }
 export function initializeDatabase(db) {
     const currentUserVersion = db.pragma("user_version", { simple: true });
@@ -159,6 +162,57 @@ export function initializeDatabase(db) {
       PRIMARY KEY (coin_type, chain_identifier)
     );
 
+  `);
+    // Live multi-client state (Option B): runtime session state lives in the shared
+    // database so any review-server process can serve any session. Added WITHOUT a
+    // DB_USER_VERSION bump — older runtimes ignore unknown tables, so a newer client can
+    // introduce them without breaking a concurrently-running older client.
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS live_transaction_materials (
+      material_id TEXT PRIMARY KEY,
+      review_session_id TEXT NOT NULL,
+      plan_id TEXT NOT NULL,
+      account TEXT NOT NULL,
+      kind TEXT NOT NULL,
+      source TEXT NOT NULL,
+      transaction_bytes BLOB NOT NULL,
+      redacted_diagnostics_json TEXT,
+      created_at TEXT NOT NULL,
+      expires_at TEXT NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_live_transaction_materials_session
+      ON live_transaction_materials(review_session_id);
+
+    CREATE TABLE IF NOT EXISTS live_review_sessions (
+      id TEXT PRIMARY KEY,
+      token_hash TEXT NOT NULL,
+      status TEXT NOT NULL,
+      account TEXT,
+      pending_handoff_digest TEXT,
+      plans_json TEXT NOT NULL,
+      review_state_json TEXT,
+      execution_result_json TEXT,
+      created_at TEXT NOT NULL,
+      expires_at TEXT NOT NULL,
+      last_activity_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS live_private_review_artifacts (
+      review_session_id TEXT PRIMARY KEY
+        REFERENCES live_review_sessions(id) ON DELETE CASCADE,
+      artifacts_json TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS live_wallet_identity_sessions (
+      id TEXT PRIMARY KEY,
+      session_json TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS live_settings_sessions (
+      id TEXT PRIMARY KEY,
+      session_json TEXT NOT NULL
+    );
   `);
     migrateDatabase(db, currentUserVersion);
     if (db.pragma("user_version", { simple: true }) !== DB_USER_VERSION) {

package/dist/core/session/keyedRecordStore.js

@@ -0,0 +1,18 @@
+export class InMemoryKeyedRecordStore {
+    records = new Map();
+    get(id) {
+        return this.records.get(id);
+    }
+    set(id, value) {
+        this.records.set(id, value);
+    }
+    delete(id) {
+        this.records.delete(id);
+    }
+    ids() {
+        return [...this.records.keys()];
+    }
+    clear() {
+        this.records.clear();
+    }
+}

package/dist/core/session/sessionRecordStore.js

@@ -0,0 +1,33 @@
+export class InMemorySessionRecordStore {
+    sessions = new Map();
+    get(id) {
+        return this.sessions.get(id);
+    }
+    set(id, session) {
+        this.sessions.set(id, session);
+    }
+    ids() {
+        return [...this.sessions.keys()];
+    }
+    clear() {
+        this.sessions.clear();
+    }
+    acquireHandoffLock(id, digest) {
+        const session = this.sessions.get(id);
+        if (!session) {
+            return false;
+        }
+        if (session.pendingHandoffDigest !== undefined && session.pendingHandoffDigest !== digest) {
+            return false;
+        }
+        session.pendingHandoffDigest = digest;
+        return true;
+    }
+    releaseHandoffLock(id) {
+        const session = this.sessions.get(id);
+        if (!session) {
+            return;
+        }
+        delete session.pendingHandoffDigest;
+    }
+}

package/dist/core/session/sessionStore.js

@@ -9,6 +9,7 @@ import { publicHumanReadableReviewFromEvidence } from "../action/humanReadableRe
 import { publicTransactionSimulationSummaryFromEvidence, verifyReviewTimeSimulationEvidence } from "../action/reviewTimeSimulationEvidence.js";
 import { verifySupportedHumanReadableReviewEvidence } from "../action/humanReadableReviewProjectionVerifier.js";
 import { InMemoryPrivateReviewArtifactStore } from "./privateReviewArtifacts.js";
+import { InMemorySessionRecordStore } from "./sessionRecordStore.js";
 import { isFinalSessionStatus } from "./status.js";
 import { parseSuiAddress } from "../suiAddress.js";
 import { cloneLocalSession, createLocalSessionBase, DEFAULT_SESSION_TTL_MS, isLocalSessionExpired, tokenMatchesHash } from "./localSession.js";
@@ -52,9 +53,9 @@ const ALLOWED_TRANSITIONS = {
     failure: [],
     expired: []
 };
-export class InMemorySessionStore {
-    sessions = new Map();
-    privateReviewArtifacts = new InMemoryPrivateReviewArtifactStore();
+export class LocalSessionStore {
+    sessions;
+    privateReviewArtifacts;
     walletIdentity;
     settings;
     ttlMs;
@@ -64,17 +65,21 @@ export class InMemorySessionStore {
     logger;
     validateAdapterLifecycle;
     constructor(options) {
+        this.sessions = options.sessions;
+        this.privateReviewArtifacts = options.artifacts;
         this.ttlMs = options.ttlMs ?? DEFAULT_SESSION_TTL_MS;
         this.walletIdentity = new WalletIdentitySessionManager({
             ttlMs: this.ttlMs,
             appendEventLog: (record) => this.appendEventLog(record),
             setActiveAccount: async (account, now, wallet) => {
                 await this.activityStore.setActiveAccount(account, "wallet_identity", now, wallet);
-            }
+            },
+            ...(options.walletIdentityStore ? { recordStore: options.walletIdentityStore } : {})
         });
         this.settings = new SettingsSessionManager({
             ttlMs: this.ttlMs,
-            appendEventLog: (record) => this.appendEventLog(record)
+            appendEventLog: (record) => this.appendEventLog(record),
+            ...(options.settingsStore ? { recordStore: options.settingsStore } : {})
         });
         this.eventLog = options.eventLog ?? new NullEventLogSink();
         this.activityStore = options.activityStore;
@@ -118,7 +123,7 @@ export class InMemorySessionStore {
     }
     async listReviewSessions(now = new Date()) {
         const sessions = [];
-        for (const id of this.sessions.keys()) {
+        for (const id of this.sessions.ids()) {
             const session = await this.getReviewSession(id, now);
             if (session) {
                 sessions.push(session);
@@ -450,8 +455,7 @@ export class InMemorySessionStore {
         if (!session || session.pendingHandoffDigest === undefined) {
             return;
         }
-        delete session.pendingHandoffDigest;
-        this.sessions.set(id, session);
+        this.sessions.releaseHandoffLock(id);
         await this.appendEventLog({
             type: "handoff.cancelled",
             sessionId: id,
@@ -512,8 +516,9 @@ export class InMemorySessionStore {
         // One-transaction lock: while a handoff is outstanding, state recomputes
         // are refused so a second, different transaction cannot be signed from
         // the same session. Cleared on result recording, cancel, or material expiry.
-        session.pendingHandoffDigest = contract.transactionMaterialCommitment;
-        this.sessions.set(id, session);
+        if (!this.sessions.acquireHandoffLock(id, contract.transactionMaterialCommitment)) {
+            throw new SessionStoreError("handoff_unavailable", "Another signing is already in progress for this review session");
+        }
         await this.appendEventLog({
             type: "handoff.prepared",
             sessionId: id,
@@ -528,7 +533,7 @@ export class InMemorySessionStore {
         };
     }
     async invalidateAllLocalSessions(reason, now = new Date()) {
-        for (const id of this.sessions.keys()) {
+        for (const id of this.sessions.ids()) {
             this.deleteReviewSessionTransactionMaterials(id);
         }
         this.sessions.clear();
@@ -753,6 +758,18 @@ export class InMemorySessionStore {
         return verifiedArtifacts;
     }
 }
+// In-memory session store: the orchestration above with Map-backed record and
+// artifact stores. Public name + constructor are unchanged so existing callers and
+// the session-store contract test keep working as the regression wall.
+export class InMemorySessionStore extends LocalSessionStore {
+    constructor(options) {
+        super({
+            ...options,
+            sessions: new InMemorySessionRecordStore(),
+            artifacts: new InMemoryPrivateReviewArtifactStore()
+        });
+    }
+}
 function assertPrivateDerivedReviewStateProjections(state, privateArtifacts) {
     for (const binding of PRIVATE_DERIVED_REVIEW_FIELD_BINDINGS) {
         const publicValue = binding.getPublicState(state);

package/dist/core/session/settingsSessions.js

@@ -1,9 +1,11 @@
 import { cloneLocalSession, createLocalSessionBase, isLocalSessionExpired, tokenMatchesHash } from "./localSession.js";
+import { InMemoryKeyedRecordStore } from "./keyedRecordStore.js";
 export class SettingsSessionManager {
     options;
-    sessions = new Map();
+    sessions;
     constructor(options) {
         this.options = options;
+        this.sessions = options.recordStore ?? new InMemoryKeyedRecordStore();
     }
     async create(now) {
         const { base, token } = createLocalSessionBase(now, this.options.ttlMs);

package/dist/core/session/sqliteSessionStore.js

@@ -0,0 +1,175 @@
+import { clonePrivateReviewArtifacts } from "./privateReviewArtifacts.js";
+import { walletIdentitySessionSchema } from "./walletIdentity.js";
+/**
+ * SQLite-backed live review-session records. Holds the same SessionRecordStore
+ * contract as the in-memory backend so the shared LocalSessionStore orchestration
+ * (and every security invariant) runs unchanged. The handoff lock is a single
+ * conditional UPDATE so two processes can never hand off two different transactions
+ * for the same session.
+ */
+export class SqliteSessionRecordStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    get(id) {
+        const row = this.db
+            .prepare(`SELECT * FROM live_review_sessions WHERE id = ?`)
+            .get(id);
+        return row ? sessionFromRow(row) : undefined;
+    }
+    set(id, session) {
+        this.db
+            .prepare(`INSERT INTO live_review_sessions
+           (id, token_hash, status, account, pending_handoff_digest,
+            plans_json, review_state_json, execution_result_json,
+            created_at, expires_at, last_activity_at)
+         VALUES
+           (@id, @tokenHash, @status, @account, @pendingHandoffDigest,
+            @plansJson, @reviewStateJson, @executionResultJson,
+            @createdAt, @expiresAt, @lastActivityAt)
+         ON CONFLICT(id) DO UPDATE SET
+           token_hash = excluded.token_hash,
+           status = excluded.status,
+           account = excluded.account,
+           pending_handoff_digest = excluded.pending_handoff_digest,
+           plans_json = excluded.plans_json,
+           review_state_json = excluded.review_state_json,
+           execution_result_json = excluded.execution_result_json,
+           created_at = excluded.created_at,
+           expires_at = excluded.expires_at,
+           last_activity_at = excluded.last_activity_at`)
+            .run({
+            id: session.id,
+            tokenHash: session.tokenHash,
+            status: session.status,
+            account: session.account ?? null,
+            pendingHandoffDigest: session.pendingHandoffDigest ?? null,
+            plansJson: JSON.stringify(session.plans),
+            reviewStateJson: session.reviewState ? JSON.stringify(session.reviewState) : null,
+            executionResultJson: session.executionResult ? JSON.stringify(session.executionResult) : null,
+            createdAt: session.createdAt,
+            expiresAt: session.expiresAt,
+            lastActivityAt: session.lastActivityAt
+        });
+    }
+    ids() {
+        const rows = this.db.prepare(`SELECT id FROM live_review_sessions`).all();
+        return rows.map((row) => row.id);
+    }
+    clear() {
+        this.db.prepare(`DELETE FROM live_review_sessions`).run();
+    }
+    acquireHandoffLock(id, digest) {
+        // Atomic across processes: claim the lock only when it is free or already held
+        // by the same digest. A different in-flight digest leaves the row untouched.
+        const result = this.db
+            .prepare(`UPDATE live_review_sessions
+         SET pending_handoff_digest = ?
+         WHERE id = ? AND (pending_handoff_digest IS NULL OR pending_handoff_digest = ?)`)
+            .run(digest, id, digest);
+        return result.changes > 0;
+    }
+    releaseHandoffLock(id) {
+        this.db
+            .prepare(`UPDATE live_review_sessions SET pending_handoff_digest = NULL WHERE id = ?`)
+            .run(id);
+    }
+}
+export class SqlitePrivateReviewArtifactStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    get(reviewSessionId) {
+        const row = this.db
+            .prepare(`SELECT artifacts_json FROM live_private_review_artifacts WHERE review_session_id = ?`)
+            .get(reviewSessionId);
+        if (!row) {
+            return undefined;
+        }
+        // clonePrivateReviewArtifacts re-parses/validates the evidence on read, matching
+        // the in-memory store's clone-on-read behaviour.
+        return clonePrivateReviewArtifacts(JSON.parse(row.artifacts_json));
+    }
+    set(reviewSessionId, artifacts) {
+        const json = JSON.stringify(clonePrivateReviewArtifacts(artifacts));
+        this.db
+            .prepare(`INSERT INTO live_private_review_artifacts (review_session_id, artifacts_json)
+         VALUES (?, ?)
+         ON CONFLICT(review_session_id) DO UPDATE SET artifacts_json = excluded.artifacts_json`)
+            .run(reviewSessionId, json);
+    }
+    delete(reviewSessionId) {
+        this.db.prepare(`DELETE FROM live_private_review_artifacts WHERE review_session_id = ?`).run(reviewSessionId);
+    }
+    clear() {
+        this.db.prepare(`DELETE FROM live_private_review_artifacts`).run();
+    }
+}
+/**
+ * SQLite-backed id-keyed store for the short-lived wallet-identity and settings
+ * session managers. Each record is a JSON blob keyed by id; the table name is a
+ * trusted constant supplied by the factories below (never user input).
+ */
+export class SqliteKeyedRecordStore {
+    db;
+    table;
+    revive;
+    constructor(db, table, revive) {
+        this.db = db;
+        this.table = table;
+        this.revive = revive;
+    }
+    get(id) {
+        const row = this.db
+            .prepare(`SELECT session_json FROM ${this.table} WHERE id = ?`)
+            .get(id);
+        return row ? this.revive(JSON.parse(row.session_json)) : undefined;
+    }
+    set(id, value) {
+        this.db
+            .prepare(`INSERT INTO ${this.table} (id, session_json) VALUES (?, ?)
+         ON CONFLICT(id) DO UPDATE SET session_json = excluded.session_json`)
+            .run(id, JSON.stringify(value));
+    }
+    delete(id) {
+        this.db.prepare(`DELETE FROM ${this.table} WHERE id = ?`).run(id);
+    }
+    ids() {
+        const rows = this.db.prepare(`SELECT id FROM ${this.table}`).all();
+        return rows.map((row) => row.id);
+    }
+    clear() {
+        this.db.prepare(`DELETE FROM ${this.table}`).run();
+    }
+}
+export function createSqliteWalletIdentityRecordStore(db) {
+    return new SqliteKeyedRecordStore(db, "live_wallet_identity_sessions", (raw) => walletIdentitySessionSchema.parse(raw));
+}
+export function createSqliteSettingsRecordStore(db) {
+    return new SqliteKeyedRecordStore(db, "live_settings_sessions", (raw) => raw);
+}
+// Reconstruct the ReviewSession from columns + JSON blobs. Optional fields are
+// omitted (not set to undefined) so the shape matches the in-memory store exactly.
+function sessionFromRow(row) {
+    return {
+        id: row.id,
+        tokenHash: row.token_hash,
+        status: row.status,
+        createdAt: row.created_at,
+        expiresAt: row.expires_at,
+        lastActivityAt: row.last_activity_at,
+        plans: JSON.parse(row.plans_json),
+        ...(row.account === null ? {} : { account: row.account }),
+        ...(row.review_state_json === null
+            ? {}
+            : { reviewState: JSON.parse(row.review_state_json) }),
+        ...(row.execution_result_json === null
+            ? {}
+            : { executionResult: JSON.parse(row.execution_result_json) }),
+        ...(row.pending_handoff_digest === null
+            ? {}
+            : { pendingHandoffDigest: row.pending_handoff_digest })
+    };
+}

package/dist/core/session/sqliteTransactionMaterialStore.js

@@ -0,0 +1,64 @@
+import { buildTransactionMaterialRecord, sameHandle, toMaterialHandle } from "./transactionMaterialStore.js";
+/**
+ * SQLite-backed transaction material store. Holds the same synchronous contract as
+ * InMemoryLocalTransactionMaterialStore so producers and the wallet handoff path are
+ * unchanged, but persists records (including the unsigned transaction BLOB) to the
+ * shared local database so any review-server process can read them. Validation,
+ * handle identity, and expiry semantics are shared via transactionMaterialStore.ts,
+ * so the two backends never drift. The unsigned bytes are protected at rest by the
+ * data directory (0700) and database file (0600) permissions set in SqliteActivityStore.
+ */
+export class SqliteTransactionMaterialStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    recordTransactionMaterial(input, now = new Date()) {
+        const record = buildTransactionMaterialRecord(input, now);
+        this.db
+            .prepare(`INSERT INTO live_transaction_materials
+           (material_id, review_session_id, plan_id, account, kind, source,
+            transaction_bytes, redacted_diagnostics_json, created_at, expires_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(record.materialId, record.reviewSessionId, record.planId, record.account, record.kind, record.source, Buffer.from(record.transactionBytes), record.redactedDiagnostics === undefined ? null : JSON.stringify(record.redactedDiagnostics), record.createdAt, record.expiresAt);
+        return toMaterialHandle(record);
+    }
+    getTransactionMaterial(handle, now = new Date()) {
+        const row = this.db
+            .prepare(`SELECT * FROM live_transaction_materials WHERE material_id = ?`)
+            .get(handle.materialId);
+        if (!row) {
+            return undefined;
+        }
+        if (Date.parse(row.expires_at) <= now.getTime()) {
+            this.db.prepare(`DELETE FROM live_transaction_materials WHERE material_id = ?`).run(handle.materialId);
+            return undefined;
+        }
+        const record = recordFromRow(row);
+        if (!sameHandle(record, handle)) {
+            return undefined;
+        }
+        return record;
+    }
+    deleteReviewSessionTransactionMaterials(reviewSessionId) {
+        this.db.prepare(`DELETE FROM live_transaction_materials WHERE review_session_id = ?`).run(reviewSessionId);
+    }
+}
+// Each read rebuilds a fresh record (new Uint8Array from the BLOB, parsed
+// diagnostics) so a caller mutating the result never touches the stored row.
+function recordFromRow(row) {
+    return {
+        materialId: row.material_id,
+        reviewSessionId: row.review_session_id,
+        planId: row.plan_id,
+        account: row.account,
+        kind: row.kind,
+        source: row.source,
+        createdAt: row.created_at,
+        expiresAt: row.expires_at,
+        transactionBytes: new Uint8Array(row.transaction_bytes),
+        ...(row.redacted_diagnostics_json == null
+            ? {}
+            : { redactedDiagnostics: JSON.parse(row.redacted_diagnostics_json) })
+    };
+}

package/dist/core/session/transactionMaterialStore.js

@@ -116,51 +116,68 @@ export class LocalTransactionMaterialStoreError extends Error {
         super(message);
     }
 }
+// Validate the store input and build the stored record (with cloned bytes). Shared
+// by every LocalTransactionMaterialStore implementation so validation never drifts
+// between the in-memory and SQLite backends.
+export function buildTransactionMaterialRecord(input, now = new Date()) {
+    const account = parseSuiAddress(input.account);
+    if (!account) {
+        throw new LocalTransactionMaterialStoreError("Invalid transaction material account");
+    }
+    if (!input.reviewSessionId) {
+        throw new LocalTransactionMaterialStoreError("reviewSessionId is required");
+    }
+    if (!input.planId) {
+        throw new LocalTransactionMaterialStoreError("planId is required");
+    }
+    if (!LOCAL_TRANSACTION_MATERIAL_KINDS.includes(input.kind)) {
+        throw new LocalTransactionMaterialStoreError("Invalid transaction material kind");
+    }
+    if (!LOCAL_TRANSACTION_MATERIAL_SOURCES.includes(input.source)) {
+        throw new LocalTransactionMaterialStoreError("Invalid transaction material source");
+    }
+    if (input.transactionBytes.byteLength === 0) {
+        throw new LocalTransactionMaterialStoreError("transactionBytes must not be empty");
+    }
+    const createdAt = now.toISOString();
+    const expiresAt = input.expiresAt.toISOString();
+    if (Date.parse(expiresAt) <= Date.parse(createdAt)) {
+        throw new LocalTransactionMaterialStoreError("expiresAt must be after createdAt");
+    }
+    return {
+        materialId: `txmat_${randomUUID()}`,
+        reviewSessionId: input.reviewSessionId,
+        planId: input.planId,
+        account,
+        kind: input.kind,
+        source: input.source,
+        createdAt,
+        expiresAt,
+        transactionBytes: cloneBytes(input.transactionBytes),
+        ...(input.redactedDiagnostics === undefined
+            ? {}
+            : { redactedDiagnostics: structuredClone(input.redactedDiagnostics) })
+    };
+}
+// Project the public (redacted) handle out of a stored record.
+export function toMaterialHandle(record) {
+    return {
+        materialId: record.materialId,
+        reviewSessionId: record.reviewSessionId,
+        planId: record.planId,
+        account: record.account,
+        kind: record.kind,
+        source: record.source,
+        createdAt: record.createdAt,
+        expiresAt: record.expiresAt
+    };
+}
 export class InMemoryLocalTransactionMaterialStore {
     records = new Map();
     recordTransactionMaterial(input, now = new Date()) {
-        const account = parseSuiAddress(input.account);
-        if (!account) {
-            throw new LocalTransactionMaterialStoreError("Invalid transaction material account");
-        }
-        if (!input.reviewSessionId) {
-            throw new LocalTransactionMaterialStoreError("reviewSessionId is required");
-        }
-        if (!input.planId) {
-            throw new LocalTransactionMaterialStoreError("planId is required");
-        }
-        if (!LOCAL_TRANSACTION_MATERIAL_KINDS.includes(input.kind)) {
-            throw new LocalTransactionMaterialStoreError("Invalid transaction material kind");
-        }
-        if (!LOCAL_TRANSACTION_MATERIAL_SOURCES.includes(input.source)) {
-            throw new LocalTransactionMaterialStoreError("Invalid transaction material source");
-        }
-        if (input.transactionBytes.byteLength === 0) {
-            throw new LocalTransactionMaterialStoreError("transactionBytes must not be empty");
-        }
-        const createdAt = now.toISOString();
-        const expiresAt = input.expiresAt.toISOString();
-        if (Date.parse(expiresAt) <= Date.parse(createdAt)) {
-            throw new LocalTransactionMaterialStoreError("expiresAt must be after createdAt");
-        }
-        const handle = {
-            materialId: `txmat_${randomUUID()}`,
-            reviewSessionId: input.reviewSessionId,
-            planId: input.planId,
-            account,
-            kind: input.kind,
-            source: input.source,
-            createdAt,
-            expiresAt
-        };
-        this.records.set(handle.materialId, {
-            ...handle,
-            transactionBytes: cloneBytes(input.transactionBytes),
-            ...(input.redactedDiagnostics === undefined
-                ? {}
-                : { redactedDiagnostics: structuredClone(input.redactedDiagnostics) })
-        });
-        return { ...handle };
+        const record = buildTransactionMaterialRecord(input, now);
+        this.records.set(record.materialId, record);
+        return toMaterialHandle(record);
     }
     getTransactionMaterial(handle, now = new Date()) {
         const record = this.records.get(handle.materialId);
@@ -190,7 +207,7 @@ export class InMemoryLocalTransactionMaterialStore {
         }
     }
 }
-function sameHandle(record, handle) {
+export function sameHandle(record, handle) {
     return record.materialId === handle.materialId &&
         record.reviewSessionId === handle.reviewSessionId &&
         record.planId === handle.planId &&