clearhand 0.1.0

package/dist/server/connectors/stripe.js

@@ -0,0 +1,252 @@
+import Stripe from 'stripe';
+import { recordEgress } from '../trust/egress.js';
+export const STRIPE_SECRET_NAME = 'stripe_api_key';
+const STRIPE_HOST = 'api.stripe.com';
+const API_VERSION = '2025-05-28.basil';
+/**
+ * Every Stripe call goes through here: the key is decrypted just-in-time with
+ * a stated purpose (which lands in the secret access log) and the egress
+ * ledger records the host before the call is made.
+ */
+function client(db, secrets, purpose, ref) {
+    const key = secrets.use(STRIPE_SECRET_NAME, purpose, ref);
+    recordEgress(db, STRIPE_HOST, purpose);
+    return new Stripe(key, { apiVersion: API_VERSION });
+}
+/**
+ * Entry-time validation. Least privilege is policy: a full-access live key is
+ * accepted only with a loud warning; the recommended shape is a restricted
+ * key (rk_live_…) with customers:read, charges:read, refunds:write,
+ * subscriptions:write, invoices:read.
+ */
+export async function verifyStripeKey(db, rawKey) {
+    const keyType = rawKey.startsWith('rk_')
+        ? 'restricted'
+        : rawKey.includes('_test_')
+            ? 'test'
+            : rawKey.startsWith('sk_')
+                ? 'full'
+                : 'unknown';
+    try {
+        recordEgress(db, STRIPE_HOST, 'verify stripe key');
+        const probe = new Stripe(rawKey, { apiVersion: API_VERSION });
+        await probe.balance.retrieve();
+        const check = { ok: true, keyType, accountHint: `…${rawKey.slice(-4)}` };
+        if (keyType === 'full') {
+            check.warning =
+                'This is a FULL-ACCESS live key. ClearHand works with a restricted key and recommends one: ' +
+                    'create it at https://dashboard.stripe.com/apikeys/create with customers:read, charges:read, ' +
+                    'refunds:write, subscriptions:write, invoices:read.';
+        }
+        return check;
+    }
+    catch (err) {
+        return { ok: false, keyType, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+function subView(s) {
+    return {
+        id: s.id,
+        status: s.status,
+        cancel_at_period_end: s.cancel_at_period_end,
+        cancel_at: s.cancel_at,
+    };
+}
+/**
+ * The executor's Stripe ops. Every mutation returns a FRESH RETRIEVED view —
+ * not the mutation response — so the executor's confirm-before-success checks
+ * assert real post-mutation state (a 200 with an unchanged object must fail
+ * the check, not pass it).
+ */
+export function makeStripeExecOps(db, secrets) {
+    return {
+        async retrieveSubscription(subId, ref) {
+            const s = client(db, secrets, `pre-flight retrieve ${subId}`, ref);
+            return subView(await s.subscriptions.retrieve(subId));
+        },
+        async cancelNow(subId, ref) {
+            const s = client(db, secrets, `cancel subscription now ${subId}`, ref);
+            await s.subscriptions.cancel(subId, { invoice_now: false, prorate: false });
+            return subView(await s.subscriptions.retrieve(subId));
+        },
+        async cancelAtPeriodEnd(subId, ref) {
+            const s = client(db, secrets, `cancel at period end ${subId}`, ref);
+            await s.subscriptions.update(subId, { cancel_at_period_end: true });
+            return subView(await s.subscriptions.retrieve(subId));
+        },
+        async cancelAt(subId, epochSeconds, ref) {
+            const s = client(db, secrets, `schedule cancel ${subId}`, ref);
+            // proration_behavior 'none' is mandatory: omitting it generated a
+            // wrongful proration charge in the ancestor system (Incident A).
+            await s.subscriptions.update(subId, {
+                cancel_at: epochSeconds,
+                proration_behavior: 'none',
+            });
+            return subView(await s.subscriptions.retrieve(subId));
+        },
+        async retrieveCharge(chargeId, ref) {
+            const s = client(db, secrets, `retrieve charge ${chargeId}`, ref);
+            const ch = await s.charges.retrieve(chargeId);
+            return {
+                id: ch.id,
+                amount: ch.amount,
+                currency: ch.currency,
+                refunded: ch.refunded,
+                amount_refunded: ch.amount_refunded,
+            };
+        },
+        async createRefund(params, ref) {
+            const s = client(db, secrets, `execute refund on ${params.chargeId}`, ref);
+            const created = await s.refunds.create({
+                charge: params.chargeId,
+                ...(params.amountCents !== undefined ? { amount: params.amountCents } : {}),
+                reason: 'requested_by_customer',
+            });
+            // Confirm-before-success: re-read the refund.
+            const confirmed = await s.refunds.retrieve(created.id);
+            if (confirmed.status !== 'succeeded' && confirmed.status !== 'pending') {
+                throw new Error(`refund ${created.id} did not confirm: status=${confirmed.status}`);
+            }
+            return { id: confirmed.id, status: confirmed.status ?? 'unknown', amount: confirmed.amount };
+        },
+        async latestPaidInvoiceCharge(subId, ref) {
+            const s = client(db, secrets, `resolve charge from ${subId}`, ref);
+            const invoices = await s.invoices.list({ subscription: subId, status: 'paid', limit: 1 });
+            const inv = invoices.data[0];
+            if (!inv)
+                return null;
+            if (typeof inv.charge === 'string')
+                return inv.charge;
+            if (inv.charge && typeof inv.charge === 'object')
+                return inv.charge.id;
+            // Newer API shapes hang the charge off the payment intent.
+            const pi = inv.payment_intent;
+            if (typeof pi === 'string') {
+                const intent = await s.paymentIntents.retrieve(pi);
+                const latest = intent.latest_charge;
+                return typeof latest === 'string' ? latest : (latest?.id ?? null);
+            }
+            return null;
+        },
+    };
+}
+/** Counts for the connect micro-payoff. Sampled lists; "+" marks a full page. */
+export async function stripeInventory(db, secrets) {
+    const stripe = client(db, secrets, 'connect inventory (counts)');
+    const [products, prices, charges, refunds, disputes] = await Promise.all([
+        stripe.products.list({ active: true, limit: 100 }),
+        stripe.prices.list({ active: true, limit: 100 }),
+        stripe.charges.list({ limit: 100 }),
+        stripe.refunds.list({ limit: 100 }),
+        stripe.disputes.list({ limit: 100 }),
+    ]);
+    const count = (l) => l.has_more ? `${l.data.length}+` : String(l.data.length);
+    return {
+        products: products.data.length,
+        prices: prices.data.length,
+        charges: count(charges),
+        refunds: count(refunds),
+        disputes: count(disputes),
+    };
+}
+export async function enrichFromStripe(db, secrets, customerEmail, ref) {
+    const stripe = client(db, secrets, 'enrich case (customer lookup)', ref);
+    const found = await stripe.customers.list({ email: customerEmail, limit: 5 });
+    const enrichment = {
+        found: found.data.length > 0,
+        fetchedAt: new Date().toISOString(),
+        customers: [],
+    };
+    for (const cust of found.data) {
+        const [subs, charges] = await Promise.all([
+            stripe.subscriptions.list({ customer: cust.id, status: 'all', limit: 10 }),
+            stripe.charges.list({ customer: cust.id, limit: 20 }),
+        ]);
+        let ltv = 0;
+        let refundCount = 0;
+        let refundTotal = 0;
+        const recentCharges = charges.data.map((ch) => {
+            if (ch.status === 'succeeded')
+                ltv += ch.amount - ch.amount_refunded;
+            if (ch.amount_refunded > 0) {
+                refundCount += 1;
+                refundTotal += ch.amount_refunded;
+            }
+            return {
+                id: ch.id,
+                amountCents: ch.amount,
+                currency: ch.currency,
+                created: new Date(ch.created * 1000).toISOString(),
+                status: ch.status,
+                refunded: ch.refunded,
+                amountRefundedCents: ch.amount_refunded,
+            };
+        });
+        enrichment.customers.push({
+            customerId: cust.id,
+            created: new Date(cust.created * 1000).toISOString(),
+            currency: cust.currency ?? null,
+            ltvCents: ltv,
+            subscriptions: subs.data.map((s) => {
+                const item = s.items.data[0];
+                return {
+                    id: s.id,
+                    status: s.status,
+                    priceNickname: item?.price.nickname ?? null,
+                    priceId: item?.price.id ?? '',
+                    amountCents: item?.price.unit_amount ?? null,
+                    interval: item?.price.recurring?.interval ?? null,
+                    currentPeriodEnd: item?.current_period_end
+                        ? new Date(item.current_period_end * 1000).toISOString()
+                        : null,
+                    cancelAtPeriodEnd: s.cancel_at_period_end,
+                };
+            }),
+            recentCharges,
+            refunds: { count: refundCount, totalCents: refundTotal },
+        });
+    }
+    return enrichment;
+}
+/**
+ * Aggregate stats used by onboarding extraction: catalog + actual refund
+ * practice ("you refunded N% of requests, median full") so the policy
+ * interview can ask evidence-based questions instead of blank forms.
+ */
+export async function stripeBusinessSummary(db, secrets) {
+    const stripe = client(db, secrets, 'onboarding extraction (catalog + refund stats)');
+    const [products, prices, charges, refunds] = await Promise.all([
+        stripe.products.list({ active: true, limit: 50 }),
+        stripe.prices.list({ active: true, limit: 100 }),
+        stripe.charges.list({ limit: 100 }),
+        stripe.refunds.list({ limit: 100 }),
+    ]);
+    const succeeded = charges.data.filter((c) => c.status === 'succeeded');
+    const fullRefunds = refunds.data.filter((r) => {
+        const ch = charges.data.find((c) => c.id === r.charge);
+        return ch ? r.amount >= ch.amount : false;
+    });
+    return {
+        fetchedAt: new Date().toISOString(),
+        catalog: products.data.map((p) => ({
+            id: p.id,
+            name: p.name,
+            description: p.description,
+            prices: prices.data
+                .filter((pr) => pr.product === p.id)
+                .map((pr) => ({
+                id: pr.id,
+                nickname: pr.nickname,
+                amountCents: pr.unit_amount,
+                currency: pr.currency,
+                interval: pr.recurring?.interval ?? 'one_time',
+            })),
+        })),
+        refundPractice: {
+            sampledCharges: succeeded.length,
+            sampledRefunds: refunds.data.length,
+            fullRefundShare: refunds.data.length > 0 ? fullRefunds.length / refunds.data.length : null,
+            totalRefundedCents: refunds.data.reduce((s, r) => s + r.amount, 0),
+        },
+    };
+}

package/dist/server/context.js

@@ -0,0 +1,83 @@
+import { openDb, logSecretAccess } from './db/index.js';
+import { SecretStore } from './secrets/store.js';
+import { loadConfig } from '../shared/config.js';
+import { makeStripeExecOps, enrichFromStripe } from './connectors/stripe.js';
+import { makeMailer } from './connectors/mailbox.js';
+import { makeGithubOps } from './connectors/github.js';
+import { mailboxConfig, githubConfig } from './services/connections.js';
+import { makeDemoExecutorOps, seedDemoData } from './demo.js';
+import { now } from './db/index.js';
+/**
+ * Wires the deterministic core. Connector configs are resolved at CALL time
+ * (not boot time) so connecting Stripe or a mailbox in the dashboard takes
+ * effect on the next action without a server restart.
+ */
+export async function createAppContext(opts = {}) {
+    const config = loadConfig();
+    const db = openDb(opts.dbFile);
+    const secrets = await SecretStore.create({
+        storage: config.secretStorage,
+        onAccess: (a) => logSecretAccess(db, a),
+    });
+    const demo = config.demoMode;
+    if (demo)
+        seedDemoData(db);
+    const executorDeps = makeExecutorDeps(db, secrets, demo);
+    const approval = {
+        db,
+        executorDeps,
+        enrichCase: demo ? undefined : (caseId) => enrichCaseFromStripe(db, secrets, caseId),
+    };
+    return { db, secrets, config, approval, demo };
+}
+function makeExecutorDeps(db, secrets, demo) {
+    if (demo) {
+        const ops = makeDemoExecutorOps();
+        return { db, ...ops };
+    }
+    const stripe = makeStripeExecOps(db, secrets);
+    return {
+        db,
+        stripe,
+        mailer: {
+            async sendReply(params) {
+                const cfg = mailboxConfig(db);
+                if (!cfg)
+                    throw new Error('mailbox not connected — connect it on the dashboard Connections page');
+                return makeMailer(db, secrets, cfg).sendReply(params);
+            },
+        },
+        github: {
+            async createIssue(params, ref) {
+                const cfg = githubConfig(db);
+                if (!cfg)
+                    throw new Error('GitHub not connected — connect it on the dashboard Connections page');
+                return makeGithubOps(db, secrets, cfg).createIssue(params, ref);
+            },
+        },
+    };
+}
+/**
+ * Case enrichment: server-owned. The `stripe` slice of prepared_context is
+ * written only here (agents may add notes/customer_history via PATCH
+ * /context, never Stripe-shaped data — LLM-supplied money data is
+ * radioactive at the trust boundary).
+ */
+export async function enrichCaseFromStripe(db, secrets, caseId) {
+    const row = db
+        .prepare(`SELECT c.id, cu.email FROM cases c JOIN customers cu ON cu.id = c.customer_id WHERE c.id = ?`)
+        .get(caseId);
+    if (!row)
+        throw new Error(`case ${caseId} not found or has no customer`);
+    const enrichment = await enrichFromStripe(db, secrets, row.email, `case:${caseId}`);
+    const existingRaw = db.prepare(`SELECT prepared_context_json FROM cases WHERE id = ?`).get(caseId).prepared_context_json;
+    let ctx = {};
+    try {
+        ctx = existingRaw ? JSON.parse(existingRaw) : {};
+    }
+    catch {
+        ctx = {};
+    }
+    ctx.stripe = enrichment;
+    db.prepare(`UPDATE cases SET prepared_context_json = ?, enriched_at = ?, updated_at = ? WHERE id = ?`).run(JSON.stringify(ctx), now(), now(), caseId);
+}

package/dist/server/db/index.js

@@ -0,0 +1,324 @@
+import Database from 'better-sqlite3';
+import path from 'node:path';
+import { dbPath, ensureDir } from '../../shared/paths.js';
+import { FINANCIAL_ACTION_TYPES } from '../../shared/actions.js';
+/**
+ * SQLite via better-sqlite3, deliberately synchronous: the no-double-execute
+ * guarantee in the executor rests on single-writer synchronous transactions
+ * (the CAS claim in services/executor.ts). Do not swap this for an async
+ * driver or another store without re-proving that invariant under the new
+ * concurrency model (see docs/PORT_SPEC.md, porting note 1).
+ */
+const MIGRATIONS = [
+    // v1 — initial schema
+    `
+  CREATE TABLE customers (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    email TEXT NOT NULL UNIQUE,
+    name TEXT,
+    stripe_customer_id TEXT,
+    language TEXT,
+    notes TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+  );
+
+  CREATE TABLE cases (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    customer_id INTEGER REFERENCES customers(id),
+    source TEXT NOT NULL DEFAULT 'imap',
+    -- provider thread/conversation key. NOT unique: follow-ups on a closed
+    -- thread open a NEW case sharing the conversation (see newestCaseForConversation).
+    conversation_key TEXT,
+    subject TEXT,
+    status TEXT NOT NULL DEFAULT 'new' CHECK (status IN
+      ('new','processed','reviewing','pending','resolved','escalated','ignored')),
+    priority TEXT NOT NULL DEFAULT 'normal' CHECK (priority IN ('low','normal','high','urgent')),
+    category TEXT,
+    language TEXT,
+    summary TEXT,
+    prepared_context_json TEXT,
+    enriched_at TEXT,
+    parent_case_id INTEGER REFERENCES cases(id),
+    merged_from_case_ids TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+  );
+  CREATE INDEX cases_conversation ON cases(source, conversation_key, id);
+  CREATE INDEX cases_status ON cases(status, updated_at);
+
+  CREATE TABLE emails (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    case_id INTEGER NOT NULL REFERENCES cases(id),
+    direction TEXT NOT NULL CHECK (direction IN ('inbound','outbound')),
+    from_addr TEXT,
+    to_addr TEXT,
+    subject TEXT,
+    body_text TEXT,
+    body_html TEXT,
+    body_translated TEXT,
+    language TEXT,
+    provider_message_id TEXT,
+    in_reply_to TEXT,
+    received_at TEXT,
+    created_at TEXT NOT NULL
+  );
+  CREATE INDEX emails_case ON emails(case_id, received_at);
+  CREATE UNIQUE INDEX emails_provider_id ON emails(provider_message_id)
+    WHERE provider_message_id IS NOT NULL;
+
+  CREATE TABLE drafts (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    case_id INTEGER NOT NULL REFERENCES cases(id),
+    version INTEGER NOT NULL DEFAULT 1,
+    body_english TEXT NOT NULL,
+    body_translated TEXT,
+    target_language TEXT,
+    is_current INTEGER NOT NULL DEFAULT 1,
+    created_by TEXT NOT NULL DEFAULT 'agent' CHECK (created_by IN ('agent','human')),
+    created_at TEXT NOT NULL
+  );
+  CREATE INDEX drafts_case ON drafts(case_id, is_current);
+
+  CREATE TABLE actions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    case_id INTEGER NOT NULL REFERENCES cases(id),
+    action_type TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'proposed' CHECK (status IN
+      ('proposed','approved','executing','executed','failed','rejected','superseded')),
+    execution_order INTEGER NOT NULL DEFAULT 0,
+    proposal_json TEXT NOT NULL,
+    modified_json TEXT,
+    confidence REAL,
+    policy_matched TEXT,
+    approved_by TEXT,
+    approved_at TEXT,
+    error_message TEXT,
+    result_json TEXT,
+    executed_at TEXT,
+    superseded_by_action_id INTEGER REFERENCES actions(id),
+    created_at TEXT NOT NULL
+  );
+  CREATE INDEX actions_case ON actions(case_id, status);
+
+  CREATE TABLE feedback_events (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    case_id INTEGER REFERENCES cases(id),
+    action_id INTEGER,
+    event_type TEXT NOT NULL,
+    original_json TEXT,
+    modified_json TEXT,
+    diff_summary TEXT,
+    case_category TEXT,
+    created_at TEXT NOT NULL
+  );
+
+  CREATE TABLE learning_reviews (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    case_id INTEGER REFERENCES cases(id),
+    category TEXT,
+    proposed_rule TEXT NOT NULL,
+    target_file TEXT NOT NULL,
+    target_section TEXT,
+    status TEXT NOT NULL DEFAULT 'proposed' CHECK (status IN ('proposed','approved','rejected')),
+    created_at TEXT NOT NULL,
+    resolved_at TEXT
+  );
+
+  CREATE TABLE calibrations (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    customer_message TEXT NOT NULL,
+    context_note TEXT,
+    clearhand_draft TEXT NOT NULL,
+    actual_reply TEXT,
+    verdict TEXT CHECK (verdict IN (NULL,'fine','edited','wrong_policy','wrong_facts','wrong_tone')),
+    tags TEXT,
+    note TEXT,
+    created_at TEXT NOT NULL,
+    reviewed_at TEXT
+  );
+
+  CREATE TABLE audit_log (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    at TEXT NOT NULL,
+    actor TEXT NOT NULL,
+    event TEXT NOT NULL,
+    case_id INTEGER,
+    action_id INTEGER,
+    phase TEXT,
+    detail TEXT
+  );
+  CREATE INDEX audit_case ON audit_log(case_id, at);
+  CREATE INDEX audit_action ON audit_log(action_id, at);
+
+  CREATE TABLE secret_access_log (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    at TEXT NOT NULL,
+    secret_key TEXT NOT NULL,
+    purpose TEXT NOT NULL,
+    ref TEXT,
+    backend TEXT NOT NULL
+  );
+  CREATE INDEX secret_access_at ON secret_access_log(at);
+
+  CREATE TABLE egress_log (
+    host TEXT NOT NULL,
+    purpose TEXT NOT NULL,
+    first_at TEXT NOT NULL,
+    last_at TEXT NOT NULL,
+    count INTEGER NOT NULL DEFAULT 0,
+    PRIMARY KEY (host, purpose)
+  );
+
+  CREATE TABLE connections (
+    id TEXT PRIMARY KEY,
+    status TEXT NOT NULL DEFAULT 'disconnected'
+      CHECK (status IN ('connected','disconnected','error','needs_reauth')),
+    config TEXT,
+    last_verified TEXT,
+    last_used TEXT,
+    last_error TEXT,
+    updated_at TEXT NOT NULL
+  );
+  `,
+    // v2 — onboarding state machine + progress event stream
+    `
+  CREATE TABLE onboarding (
+    id INTEGER PRIMARY KEY CHECK (id = 1),
+    state_json TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+  );
+
+  CREATE TABLE onboarding_events (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    at TEXT NOT NULL,
+    stage TEXT NOT NULL,
+    kind TEXT NOT NULL,
+    payload TEXT
+  );
+  `,
+    // v3 — learning_reviews gains the 'applied' terminal state (the agent marks
+    // a review applied only after the overlay edit actually landed). SQLite
+    // can't alter a CHECK, so rebuild the table.
+    `
+  CREATE TABLE learning_reviews_v3 (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    case_id INTEGER REFERENCES cases(id),
+    category TEXT,
+    proposed_rule TEXT NOT NULL,
+    target_file TEXT NOT NULL,
+    target_section TEXT,
+    status TEXT NOT NULL DEFAULT 'proposed'
+      CHECK (status IN ('proposed','approved','rejected','applied')),
+    created_at TEXT NOT NULL,
+    resolved_at TEXT
+  );
+  INSERT INTO learning_reviews_v3 SELECT * FROM learning_reviews;
+  DROP TABLE learning_reviews;
+  ALTER TABLE learning_reviews_v3 RENAME TO learning_reviews;
+  `,
+];
+export function openDb(file = dbPath()) {
+    ensureDir(path.dirname(file));
+    const db = new Database(file);
+    db.pragma('journal_mode = WAL');
+    db.pragma('foreign_keys = ON');
+    migrate(db);
+    return db;
+}
+/** In-memory database for tests. */
+export function openMemoryDb() {
+    const db = new Database(':memory:');
+    db.pragma('foreign_keys = ON');
+    migrate(db);
+    return db;
+}
+function migrate(db) {
+    const current = db.pragma('user_version', { simple: true });
+    for (let v = current; v < MIGRATIONS.length; v++) {
+        const sql = MIGRATIONS[v];
+        if (!sql)
+            continue;
+        db.transaction(() => {
+            db.exec(sql);
+            db.pragma(`user_version = ${v + 1}`);
+        })();
+    }
+}
+export function now() {
+    return new Date().toISOString();
+}
+export function audit(db, actor, event, opts = {}) {
+    db.prepare(`INSERT INTO audit_log (at, actor, event, case_id, action_id, phase, detail)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`).run(now(), actor, event, opts.caseId ?? null, opts.actionId ?? null, opts.phase ?? null, opts.detail !== undefined ? JSON.stringify(opts.detail) : null);
+}
+export function logSecretAccess(db, access) {
+    db.prepare(`INSERT INTO secret_access_log (at, secret_key, purpose, ref, backend) VALUES (?, ?, ?, ?, ?)`).run(access.at, access.key, access.purpose, access.ref ?? null, access.backend);
+}
+/**
+ * THE financial-guard counter (strict variant — do not regress).
+ * `executed` = done; `rejected`/`superseded` = intentionally not doing it;
+ * everything else — including `failed` — still owes the customer. An earlier
+ * proposed-only counter in the ancestor system missed an approved-then-FAILED
+ * refund; `failed` stays in this list.
+ */
+export function countPendingFinancialActions(db, caseId) {
+    const row = db
+        .prepare(`SELECT COUNT(*) AS n FROM actions
+        WHERE case_id = ?
+          AND action_type IN (${[...FINANCIAL_ACTION_TYPES].map(() => '?').join(',')})
+          AND status IN ('proposed','approved','executing','failed')`)
+        .get(caseId, ...FINANCIAL_ACTION_TYPES);
+    return row.n;
+}
+/**
+ * Claim-on-first-touch: any working write to a `new` case promotes it to
+ * `reviewing` — the signal that a session already picked it up. In the
+ * ancestor system this stopped an in-server batch processor from
+ * double-processing; here it stops two concurrent agent sessions (a
+ * scheduled morning run plus a manual one) from both triaging the same
+ * case. Returns true when this call performed the claim.
+ */
+export function claimCaseIfNew(db, caseId) {
+    const res = db
+        .prepare(`UPDATE cases SET status = 'reviewing', updated_at = ? WHERE id = ? AND status = 'new'`)
+        .run(now(), caseId);
+    return res.changes === 1;
+}
+/**
+ * A helpdesk conversation can back multiple cases over time (follow-ups on
+ * closed threads open fresh cases). New activity always attaches to the
+ * NEWEST case of the conversation — never the original.
+ */
+export function newestCaseForConversation(db, source, conversationKey) {
+    return db
+        .prepare(`SELECT id, status FROM cases
+        WHERE source = ? AND conversation_key = ?
+        ORDER BY id DESC LIMIT 1`)
+        .get(source, conversationKey);
+}
+/**
+ * Soft-supersede: replacing proposals never deletes them. Old rows flip to
+ * `superseded` with a pointer to the replacement and a feedback event, so
+ * dashboards and the learning loop keep the trail. The just-created
+ * replacement is excluded from the target set.
+ */
+export function softSupersedeProposals(db, caseId, actionType, newActionId, reason) {
+    const tx = db.transaction(() => {
+        const rows = db
+            .prepare(`SELECT id, proposal_json FROM actions
+          WHERE case_id = ? AND status = 'proposed' AND id != ?
+            ${actionType ? 'AND action_type = ?' : ''}`)
+            .all(...(actionType ? [caseId, newActionId, actionType] : [caseId, newActionId]));
+        const upd = db.prepare(`UPDATE actions SET status = 'superseded', superseded_by_action_id = ?, error_message = ?
+        WHERE id = ?`);
+        const fb = db.prepare(`INSERT INTO feedback_events (case_id, action_id, event_type, original_json, diff_summary, created_at)
+       VALUES (?, ?, 'action_superseded', ?, ?, ?)`);
+        for (const row of rows) {
+            upd.run(newActionId, reason, row.id);
+            fb.run(caseId, row.id, row.proposal_json, `superseded by action ${newActionId}: ${reason}`, now());
+        }
+        return rows.length;
+    });
+    return tx();
+}