@sprigr/apps-app-sdk 0.7.0 → 0.8.1

package/README.md

@@ -56,3 +56,24 @@ export default { list_things: actorTool(async (env, actor, args) => { /* ... */
 - `fetchFileBytes` / `fetchFileAsBase64` / `bytesToBase64` / `base64ToBytes` — file byte helpers
 
 Full platform semantics: [`docs/platform-reference.md`](../../docs/platform-reference.md).
+
+## Write protection
+
+Three platform tiers, and they are not substitutes for each other. Full guide: [`docs/write-protection.md`](../../docs/write-protection.md).
+
+| Tier | Where | Who attests | Helper |
+|---|---|---|---|
+| T1 confirmation policy | manifest `tools[].confirmation` | the model (`confirm: true`) | `buildConfirmationPolicy` + `checkConfirmationPolicy`, `sprigr-check-write-protection` |
+| T2 approval | handler returns `_approval` | a human tap | `requireApproval`, `approvalHash` / `set` / `seq` |
+| T3 undo | handler returns `_undo`; manifest `undo.reverse_tool` | platform token | `requireApproval` (capture), `undoEnvelope`, `runUndoApply`, `@sprigr/apps-undo-journal` |
+
+- `requireApproval(handlers, specs, opts)` wraps the named tools so each returns an `_approval` card instead of writing, then on the granted pass captures a before-image through the **pinned** connection and offers `_undo`. It resolves the connection inside itself, before the label lookup, the hash and the capture: a gate that sits outside the app's own pin names the wrong store, hashes the wrong store and captures the wrong store's copy. Register the result after the originals: `Object.assign(registry, requireApproval(registry, SPECS, opts))`.
+- `approvalHash(rawId, connection, ...parts)`, `set(values)`, `seq(values)`: a stable operation identity so a tap survives the model reordering a list or dropping an optional argument on the retry.
+- `undoEnvelope({...})` throws on a blank field. The platform drops the whole envelope on a blank and mints nothing, silently.
+- `refuseWithoutForce(name, handler, opts)` / `archiveOfferRefusal(...)`: a delete refuses once and offers the vendor's native archive unless `force: true`.
+- `buildConfirmationPolicy({ irreversible, always, rules })` declares a dispatcher's policy beside its action registry; `checkConfirmationPolicy({ policy, registry, ungated, requiredInput })` returns every silent failure (dead rule, `(unset)` placeholder, money threshold, unclassified write) for a one-line test.
+- `runUndoApply(args, { env, journal, specs, pin })` is the body of your `internal: true` reverse tool: load, re-pin to the journalled connection, restore, drop. `pin` may hand `restore` a different type from the env (a per-actor token state), may throw (`connection_unavailable`) or return null to refuse (`connection_mismatch`); a restore that throws is `restore_failed` and the copy is kept.
+- `safeCapture(scope, name, id, read)` and `offerUndo({ journal, entity, id, before, connection, fidelity, resource, describe, warning })`: the capture-then-offer halves for a write that is not behind an approval card (a dispatcher `update_*` action). `requireApproval` uses the same two on its granted pass.
+- `sprigr-check-write-protection` (bin): every destructive-by-name tool or enumerated dispatcher action must carry a policy, or a reason in `apps/<app>/write-protection.json`; ratchets on `tools/write-protection-baseline.json`.
+
+**Never offer `_undo` for money or messages.** Refunds, captures, cancellations, sent mail: the approval gate is the only control there.

package/bin/check-write-protection.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * sprigr-check-write-protection: every destructive tool declares a policy.
+ *
+ * The platform cannot tell which of an app's tools are destructive (sprigr-team
+ * decisions 0009 and 0011 both say so), so nothing platform-side can enforce
+ * that a permanent delete is gated. The app repo can, by name: this scans every
+ * `sprigr-app.json` and fails on a tool or enumerated dispatcher action whose
+ * name is destructive and that carries no `confirmation` entry.
+ *
+ * Escape hatches, both explicit and reviewable:
+ *
+ *   apps/<app>/write-protection.json
+ *     { "allow": { "<tool>": "<reason>", "<tool>:<action>": "<reason>" } }
+ *     A destructive-by-name entry that is genuinely harmless (a read named
+ *     `refund_rate`, a fixture reset). Every entry needs a reason. A stale
+ *     entry fails, so the file cannot silently mask a tool that came back.
+ *
+ *   --baseline <file>   (default tools/write-protection-baseline.json if present)
+ *     The ratchet. Violations listed in the baseline are reported but do not
+ *     fail; anything new fails; a baseline entry that no longer violates fails
+ *     too, so headroom is banked with --write-baseline rather than re-spent.
+ *
+ * A dispatcher tool that does not enumerate its actions (`dispatch.actions`
+ * or an `enum` on the action field) cannot be inspected and is itself a
+ * violation until enumerated or allowlisted.
+ *
+ * Dependency-free: Node stdlib only, like the other repo guards.
+ *
+ *   sprigr-check-write-protection [--apps apps] [--warn] [--baseline f] [--write-baseline]
+ */
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * A tool or action name that destroys, reverses money, or cannot be walked
+ * back. Tested against the bare name and with any leading `<app>_` prefix
+ * stripped, so `shopify_delete_product` and `delete_product` both match.
+ */
+export const DESTRUCTIVE_ACTION_PATTERN =
+  /(^|_)(delete|remove|destroy|cancel|void|refund|unship|rotate|offboard|purge|wipe|drop|terminate|clear|reset|revoke|unregister|force|deactivate|suspend)(_|$)|(^|_)(capture_payment|complete_draft)/;
+
+export function isDestructiveName(name) {
+  return DESTRUCTIVE_ACTION_PATTERN.test(name);
+}
+
+function enumeratedActions(tool) {
+  const d = tool.dispatch;
+  if (d && d.actions) {
+    if (Array.isArray(d.actions)) return d.actions.map((a) => (typeof a === 'string' ? a : a && a.name)).filter(Boolean);
+    if (typeof d.actions === 'object') return Object.keys(d.actions);
+  }
+  const field = (d && d.actionField) || 'action';
+  const prop = tool.input_schema && tool.input_schema.properties && tool.input_schema.properties[field];
+  if (!prop) return null; // not a dispatcher
+  if (Array.isArray(prop.enum)) return prop.enum.map(String);
+  for (const k of ['oneOf', 'anyOf']) {
+    if (Array.isArray(prop[k])) return prop[k].map((o) => o && o.const).filter(Boolean).map(String);
+  }
+  return []; // a dispatcher, but nothing enumerated
+}
+
+function isGatedRule(rule) {
+  return !!rule && typeof rule === 'object' && (rule.always === true || !!rule.when);
+}
+
+/**
+ * Violations for one manifest, as `tool` or `tool:action` strings.
+ * Pure, so it is unit-testable without touching the filesystem.
+ */
+export function scanManifest(manifest) {
+  const out = [];
+  for (const tool of manifest.tools || []) {
+    if (!tool || tool.internal) continue;
+    const pol = tool.confirmation && typeof tool.confirmation === 'object' ? tool.confirmation : null;
+    const toolGated = tool.confirmation_required === true || isGatedRule(pol);
+    const actions = enumeratedActions(tool);
+    if (actions === null) {
+      if (isDestructiveName(tool.name) && !toolGated) out.push(tool.name);
+      continue;
+    }
+    if (toolGated) continue;
+    if (actions.length === 0) {
+      out.push(`${tool.name}:<unenumerated>`);
+      continue;
+    }
+    const perAction = (pol && pol.actions) || {};
+    for (const a of actions) {
+      if (isDestructiveName(a) && !isGatedRule(perAction[a])) out.push(`${tool.name}:${a}`);
+    }
+  }
+  return out;
+}
+
+/** Apply the app's allowlist. Returns { violations, stale, unreasoned }. */
+export function applyAllowlist(violations, allowlist) {
+  const allow = (allowlist && allowlist.allow) || {};
+  const unreasoned = Object.entries(allow).filter(([, r]) => typeof r !== 'string' || !r.trim()).map(([k]) => k);
+  const remaining = violations.filter((v) => !(v in allow));
+  const stale = Object.keys(allow).filter((k) => !violations.includes(k));
+  return { violations: remaining, stale, unreasoned };
+}
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+export function run(argv, cwd = process.cwd()) {
+  const args = [...argv];
+  const opt = (flag, dflt) => {
+    const i = args.indexOf(flag);
+    if (i === -1) return dflt;
+    const v = args[i + 1];
+    args.splice(i, 2);
+    return v;
+  };
+  const has = (flag) => {
+    const i = args.indexOf(flag);
+    if (i === -1) return false;
+    args.splice(i, 1);
+    return true;
+  };
+  const warnOnly = has('--warn');
+  const writeBaseline = has('--write-baseline');
+  const appsDir = opt('--apps', 'apps');
+  const defaultBaseline = join(cwd, 'tools', 'write-protection-baseline.json');
+  const baselinePath = opt('--baseline', existsSync(defaultBaseline) ? defaultBaseline : null);
+  const baseline = baselinePath && existsSync(baselinePath) ? readJson(baselinePath) : {};
+
+  const root = join(cwd, appsDir);
+  const appDirs = existsSync(join(cwd, 'sprigr-app.json'))
+    ? [{ slug: '.', dir: cwd }]
+    : readdirSync(root, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && existsSync(join(root, e.name, 'sprigr-app.json')))
+        .map((e) => ({ slug: e.name, dir: join(root, e.name) }));
+
+  const failures = [];
+  const report = [];
+  const nextBaseline = {};
+
+  for (const { slug, dir } of appDirs) {
+    let manifest;
+    try {
+      manifest = readJson(join(dir, 'sprigr-app.json'));
+    } catch (err) {
+      failures.push(`${slug}: sprigr-app.json does not parse (${err.message})`);
+      continue;
+    }
+    const allowPath = join(dir, 'write-protection.json');
+    const allowlist = existsSync(allowPath) ? readJson(allowPath) : null;
+    const raw = scanManifest(manifest);
+    const { violations, stale, unreasoned } = applyAllowlist(raw, allowlist);
+    for (const k of unreasoned) failures.push(`${slug}: write-protection.json allow entry "${k}" has no reason`);
+    for (const k of stale) failures.push(`${slug}: write-protection.json allow entry "${k}" is stale (no longer destructive-and-ungated); remove it`);
+
+    const known = new Set(baseline[slug] || []);
+    const fresh = violations.filter((v) => !known.has(v));
+    const banked = [...known].filter((v) => !violations.includes(v));
+    if (violations.length) nextBaseline[slug] = violations.sort();
+
+    for (const v of fresh) failures.push(`${slug}: ${v} is destructive by name and declares no confirmation policy`);
+    for (const v of banked) failures.push(`${slug}: baseline lists "${v}" but it is now gated or gone; run --write-baseline to bank the headroom`);
+    report.push(`${slug.padEnd(28)} destructive-ungated=${String(violations.length).padStart(3)} (new ${fresh.length}, baselined ${violations.length - fresh.length})`);
+  }
+
+  if (writeBaseline && baselinePath) {
+    writeFileSync(baselinePath, JSON.stringify(nextBaseline, null, 2) + '\n');
+    return { code: 0, lines: [...report, `wrote ${baselinePath}`] };
+  }
+
+  const lines = [...report];
+  if (failures.length) {
+    lines.push('', `${failures.length} write-protection finding(s):`, ...failures.map((f) => `  ${f}`));
+    lines.push(
+      '',
+      'Fix: add a `confirmation` policy to the tool (or `confirmation.actions[<action>]` on a dispatcher),',
+      'or record a reason in apps/<app>/write-protection.json under "allow". See @sprigr/apps-app-sdk README, "Write protection".',
+    );
+    return { code: warnOnly ? 0 : 1, lines };
+  }
+  lines.push(`OK: ${appDirs.length} app manifest(s), no unguarded destructive tools outside the baseline.`);
+  return { code: 0, lines };
+}
+
+const invokedDirectly = process.argv[1] && /check-write-protection\.mjs$/.test(process.argv[1]);
+if (invokedDirectly) {
+  const { code, lines } = run(process.argv.slice(2));
+  for (const l of lines) (code ? console.error : console.log)(l);
+  process.exit(code);
+}

package/dist/index.d.ts

@@ -825,6 +825,540 @@ declare function deleteAppFile(env: AppFilesEnv, key: string): Promise<{
     key: string;
 }>;
 
+/**
+ * Write-protection types, mirrored from the Sprigr platform.
+ *
+ * Three tiers exist on the platform and they are not substitutes for each
+ * other (sprigr-team decisions 0009, 0011, 0012):
+ *
+ *   T1  `confirmation` policy in the manifest. The platform enforces it BEFORE
+ *       your handler is dispatched, but the MODEL sets `confirm: true`, so it
+ *       is a reviewable declaration and an audit trail, not a control.
+ *   T2  `_approval` envelope returned by the handler. The platform pauses the
+ *       turn on a decision card; only a real human tap mints the grant. This is
+ *       the only tier that actually stops a write.
+ *   T3  `_undo` envelope returned beside a successful write. The platform mints
+ *       the token and surfaces `undo_change`; the app keeps the before-image.
+ *
+ * Canonical declarations live in sprigr-team:
+ *   - `AppToolConfirmRule`, `AppToolConfirmationPolicy`, `AppUndoEnvelope`:
+ *     packages/shared/src/types/marketplace.ts
+ *   - `AppApprovalEnvelope`: packages/agent-core/src/marketplace-tool-builder.ts
+ * Keep the field sets in sync when the platform changes them. Mirrored (not
+ * imported) for the same reason `MarketplaceEventSourceIntegration` is: the
+ * platform packages are private and this SDK is public.
+ */
+/** One confirmation rule. `always`, or `when` a counted input crosses a threshold. */
+interface ConfirmRule {
+    /** Gate every call. Use for permanent deletes, refunds, anything public-facing. */
+    always?: boolean;
+    /**
+     * Gate only when a batch crosses a threshold. `count` names an input key
+     * (dotted paths work; on a `{ action, input }` dispatcher it MUST be dotted
+     * through `input.`); an array contributes its length, a number its own
+     * value, anything else counts as nothing and never trips. Never threshold a
+     * money field: a numeric STRING amount is silently no gate at all.
+     */
+    when?: ConfirmCondition | ConfirmCondition[];
+    /**
+     * What the person is asked to approve. `{key}` interpolates from the
+     * top-level input. Do NOT end it in a period: the platform renders it as
+     * `Action: <text>.`.
+     */
+    describe?: string;
+    /** Appends "which cannot be undone" so the model cannot undersell it. */
+    irreversible?: boolean;
+}
+interface ConfirmCondition {
+    count: string;
+    atLeast: number;
+}
+/** Tool-level policy, plus per-action rules for a dispatcher tool. */
+interface ConfirmationPolicy extends ConfirmRule {
+    /**
+     * Per-action rules, keyed by action name (read from `dispatch.actionField`,
+     * default `action`). A listed action's rule wins; an unlisted action falls
+     * back to the tool-level rule, which is normally absent.
+     */
+    actions?: Record<string, ConfirmRule>;
+}
+/**
+ * Returned INSTEAD of doing the work when a write needs a human. The platform
+ * replaces your whole result with the decision card on this pass, so nothing
+ * beside `_approval` reaches anyone; put everything the person needs to read
+ * in `question`, `header` and `summary`.
+ */
+interface AppApprovalEnvelope {
+    /** The question on the card, e.g. "Delete 12 products from acme.myshopify.com?" */
+    question: string;
+    /** Short header above the card, e.g. "Shopify". */
+    header: string;
+    /** Optional detail under the approve option; the card is the whole preview. */
+    summary?: string;
+    /**
+     * Stable identity of the exact operation. SUPPLY THIS for any tool with
+     * optional arguments: the platform's default is derived from whatever the
+     * model happened to send, and a hash that moves between the ask and the
+     * retry silently discards the tap. See `approvalHash`.
+     */
+    hash?: string;
+}
+/**
+ * Platform-stamped marker telling an app that a human approved this call. The
+ * platform DELETES any caller-supplied copy before dispatch and sets it only
+ * after consuming a real grant, so a handler may trust it.
+ */
+declare const APPROVAL_GRANTED_KEY = "_approval_granted";
+type UndoFidelity = 'full' | 'recreated';
+/**
+ * Returned BESIDE the real result after a successful write. Every field is
+ * required and non-empty: the platform drops the whole envelope on a blank
+ * field and mints nothing, silently. Build it with `undoEnvelope()`, which
+ * refuses a blank at construction time.
+ */
+interface AppUndoEnvelope {
+    /** `'full'`: same id restored in place. `'recreated'`: a NEW object under a NEW id. */
+    fidelity: UndoFidelity;
+    /** Relayed to the model verbatim. On `'recreated'` it must say the id changes. */
+    warning: string;
+    /** Human-readable subject for the list tool, e.g. `collection "Summer Sale" on acme.myshopify.com`. */
+    describes: string;
+    /** Coarse type, for grouping: "product", "contact". */
+    resource: string;
+    /** The app's own handle for the before-image (`journal.captureBefore().ref`). */
+    ref: string;
+}
+/** Args-first handler signature the marketplace wrapper dispatches with. */
+type ToolArgs = Record<string, unknown>;
+type ToolHandler<E = unknown> = (args: ToolArgs, env: E, ctx?: unknown) => Promise<unknown>;
+
+/**
+ * The stable identity of a gated operation, for the approval grant.
+ *
+ * A grant is bound to a hash so a tap on a small write cannot be spent on a big
+ * one. When an app supplies no hash the platform derives one from the arguments
+ * the MODEL sent, and the model does not send the same thing twice: an optional
+ * param included on the asking call and dropped on the retry, a `store` learned
+ * between the two, a tag list in a different order, each mints a different hash.
+ * When the hash moves, the tap is silently discarded and the person is asked
+ * the identical question again with nothing saying their answer was thrown
+ * away.
+ *
+ * Only the app knows which arguments identify the operation, so only the app
+ * can make the identity stable. Put in exactly the things that decide what
+ * changes: the resource, the connection, and the payload. NOT `confirm` or
+ * `_approval_granted` (attestation, not operation) and not free text the model
+ * composes.
+ *
+ * Extracted unchanged from the Shopify app (sprigr-apps #1197).
+ */
+/**
+ * Field separator. A control character, so it cannot occur in a tag, an id or
+ * a store domain, which is what stops one combination of values being
+ * re-partitioned into another ("a" + "bc" must not collide with "ab" + "c").
+ */
+declare const UNIT_SEP = "\u001F";
+/** A set, order-insensitive: `set(["a","b"])` === `set(["b","a"])`. */
+declare function set(values: unknown): string;
+/** An ordered list, for payloads where position changes the outcome. */
+declare function seq(values: unknown): string;
+/**
+ * Join the parts into the `_approval.hash` string. The platform mixes the tool
+ * name in before hashing, so this never needs to repeat it.
+ */
+declare function approvalHash(...parts: Array<string | number | undefined | null>): string;
+
+/**
+ * Thrown by `undoEnvelope` for a field the platform would reject.
+ *
+ * The platform's `extractAppUndo` requires `fidelity` in {full, recreated} and
+ * every string non-empty after trim; on any miss it logs a warning in the
+ * PLATFORM worker and mints no token. The app sees nothing wrong: the write
+ * succeeds and the journal row is there. The only symptom is that the model
+ * never gets an undo affordance, which reads as a discoverability problem and
+ * sends you into the tool registry instead of your own envelope. Xero 0.1.1
+ * shipped `warning: ''` this way. Failing here, in a unit test, is cheaper.
+ */
+declare class InvalidUndoEnvelopeError extends Error {
+    constructor(message: string);
+}
+/** Build an `_undo` envelope, refusing anything the platform would drop. */
+declare function undoEnvelope(input: {
+    fidelity: UndoFidelity;
+    warning: string;
+    describes: string;
+    resource: string;
+    ref: string;
+}): AppUndoEnvelope;
+/**
+ * The honest warning for a `'recreated'` reversal. Always names the new-id
+ * consequence, then whatever the rebuild cannot bring back.
+ */
+declare function recreatedWarning(resource: string, notRestored?: string): string;
+/**
+ * The honest warning for a `'full'` reversal. Even a perfect revert overwrites
+ * anything changed since the capture, so this is never empty.
+ */
+declare function fullWarning(notRestored?: string): string;
+
+/**
+ * Archive-first: a delete refuses ONCE and offers the reversible option.
+ *
+ * Where the vendor has a real archived state, a native archive beats any
+ * journal: same id, real restore, no fidelity caveat. So a `delete_*` on such
+ * an entity does not delete unless the caller passes `force: true`; it returns
+ * a refusal pointing at the archive tool. Automation that genuinely means to
+ * delete adds `force: true` once; a person who said "get rid of it" is offered
+ * the thing they almost certainly meant.
+ *
+ * The refusal shape is shared by simPRO (five deletes) and Shopify
+ * (`shopify_delete_product`) so an agent that has learned one has learned both:
+ * "I did NOT write; here is the reversible option; pass force: true if you
+ * really mean it".
+ */
+interface ArchiveOfferOptions {
+    /** Human noun: "product", "customer". */
+    resource: string;
+    /** Tool or action name the caller should reach for instead. */
+    archiveAction: string;
+    /** Arg names that may carry the target id, most specific first. */
+    idKeys?: string[];
+    /** Deep link to the record, when a verified single-record URL shape exists. */
+    link?: (args: ToolArgs, id: string) => string | undefined;
+}
+interface ArchiveOfferRefusal {
+    ok: false;
+    deleted: false;
+    archive_available: true;
+    resource: string;
+    record_id: string | null;
+    delete_action: string;
+    archive_action: string;
+    link?: string;
+    note: string;
+}
+/** The refusal payload, for dispatcher apps that wrap at the action layer. */
+declare function archiveOfferRefusal(deleteAction: string, args: ToolArgs, opts: ArchiveOfferOptions): ArchiveOfferRefusal;
+/**
+ * Wrap a flat delete handler so an un-forced call returns the offer instead.
+ * `force` is consumed here and never forwarded to the provider.
+ */
+declare function refuseWithoutForce<E>(deleteAction: string, inner: ToolHandler<E>, opts: ArchiveOfferOptions): ToolHandler<E>;
+
+/**
+ * Human approval for the writes a vendor cannot undo, plus the before-image
+ * capture for the ones it can partly undo, in ONE wrapper.
+ *
+ * ## Why this exists when the manifest already declares `confirmation`
+ *
+ * The manifest tier gates on `confirm: true`, which the MODEL sets. Measured on
+ * staging 2026-08-19: an agent wrote `confirm: true` into its own code_mode
+ * source before any prompt, because the user's request ("add these five tags")
+ * reads as the confirmation for that action. That tier is an audit trail; it is
+ * not a control. `_approval` is the tier a model cannot satisfy alone: the
+ * platform pauses the turn on a decision card, and only a real tap makes the
+ * DecisionRouter write the grant that lets the retry through.
+ *
+ * ## The two rules baked in, both learned live
+ *
+ * 1. THE CONNECTION IS RESOLVED AND PINNED INSIDE THIS WRAPPER, before the card
+ *    label lookup, the hash, and the capture. Apps establish their store /
+ *    organisation / business pin inside their own inner wrapper; a gate that
+ *    sits outside it sees an UNPINNED env, resolves the install's default
+ *    connection, and (a) names the wrong store on the card, (b) hashes the
+ *    wrong store so the retry misses the grant, and (c) captures the wrong
+ *    store's copy so a permanent delete succeeds and mints no token. Shopify
+ *    shipped all three from one cause (sprigr-team decision 0011 addendum).
+ *
+ * 2. CAPTURE BEFORE THE WRITE, MINT ONLY AFTER IT SUCCEEDS, AND NEVER RETURN
+ *    `_undo` ON A NULL CAPTURE. A failed capture does not fail the write: the
+ *    user asked for it and a human approved it. It degrades to no token.
+ *
+ * Generalised from the Shopify app's `require-approval.ts`; the per-tool
+ * questions stay in the app, because only the app knows what cannot be walked
+ * back.
+ */
+/** Per-tool spec: how the card reads, and (optionally) how to journal a before-image. */
+interface ApprovalSpec<E = unknown> {
+    /**
+     * Arg names that may carry the target id, most specific first. ONE list, used
+     * for both the card label and the grant hash, so the two cannot drift apart
+     * and describe different resources.
+     */
+    keys: string[];
+    /**
+     * The card. `target` is the already-resolved human label (or the raw id),
+     * `connection` the resolved store / organisation / business, or '' when the
+     * app has one. Do not set `hash` here; the wrapper derives it from the raw
+     * id and the connection so it cannot move between the ask and the retry.
+     * Override with `hash` below only when the arguments understate the blast
+     * radius.
+     */
+    describe: (target: string, args: ToolArgs, connection: string) => Omit<AppApprovalEnvelope, 'hash'>;
+    /**
+     * Extra identity parts beyond `rawId + connection`, e.g. a sorted tag set.
+     * Use `set()` / `seq()` from `approval-hash`. Never include `confirm`.
+     */
+    hash?: (args: ToolArgs) => Array<string | number | undefined | null>;
+    /** Present only for tools whose write can be (partly) reversed. */
+    undo?: UndoCaptureSpec<E>;
+}
+interface UndoCaptureSpec<E = unknown> {
+    /** Coarse type surfaced as `_undo.resource`. */
+    resource: string;
+    fidelity: UndoFidelity;
+    /** Read the object BEFORE the write, through the PINNED env. Null or throw on miss. */
+    capture: (pinnedEnv: E, id: string, args: ToolArgs) => Promise<unknown>;
+    /** How the change reads in `list_undoable_changes`; the connection is appended by the wrapper. */
+    describe: (before: Record<string, unknown>, id: string) => string;
+    /** Relayed verbatim; on `'recreated'` it must say the id changes. Never empty. */
+    warning: (id: string, before: Record<string, unknown>) => string;
+}
+/** The journal surface this wrapper needs; `createUndoJournal()` satisfies it. */
+interface CaptureJournal {
+    captureBefore(args: {
+        entity: string;
+        originalId: string;
+        before: unknown;
+        connection: string | null;
+    }): Promise<{
+        ref: string;
+    } | null>;
+}
+interface RequireApprovalOptions<E = unknown> {
+    /** Log prefix, e.g. `shopify-undo`. */
+    scope: string;
+    /**
+     * Resolve the connection this call will ACTUALLY hit, from the caller's
+     * arguments and the install, canonicalised (a label like "EU store" becomes
+     * the real domain). Return '' for a single-connection app. Never read it off
+     * the arguments alone: on the retry the model usually omits it.
+     */
+    resolveConnection: (env: E, args: ToolArgs) => Promise<string>;
+    /** Re-pin the env to a resolved connection so lookups and captures hit it. */
+    pinEnv: (env: E, connection: string) => E;
+    /**
+     * Human label for a raw id, looked up THROUGH the pinned env. Fall back to
+     * the id on any miss; never guess, a confidently wrong card is worse than a
+     * terse one. Omit to always show the raw id.
+     */
+    describeTarget?: (pinnedEnv: E, id: string) => Promise<string>;
+    /**
+     * Where before-images go. Required when any spec declares `undo`. The
+     * journal's own capture returns null rather than throwing, and this wrapper
+     * treats null as "no undo offered".
+     */
+    journal?: (env: E) => CaptureJournal;
+    /**
+     * Stamp the resolved connection onto a successful result (e.g. `{ store }`)
+     * so an agent reporting "deleted it" can name where. Optional.
+     */
+    stampConnection?: (result: unknown, connection: string) => unknown;
+}
+/**
+ * Wrap the named tools so each asks a human first, then (if it declares
+ * `undo`) journals a before-image on the granted pass and offers `_undo`.
+ *
+ * Returns only the wrapped entries. Register them AFTER the originals
+ * (`Object.assign(registry, requireApproval(registry, specs, opts))`) so
+ * last-write-wins puts the gated version in front.
+ *
+ * A spec naming a tool absent from `handlers` throws rather than skipping: a
+ * rename that quietly ungated a permanent delete is exactly the failure this
+ * guard exists to prevent, and it would look identical to working.
+ */
+declare function requireApproval<E>(handlers: Record<string, ToolHandler<E>>, specs: Record<string, ApprovalSpec<E>>, opts: RequireApprovalOptions<E>): Record<string, ToolHandler<E>>;
+
+/**
+ * The reversal entry point every adopting app declares as `undo.reverse_tool`.
+ *
+ * Declared `internal: true` in the manifest, so the platform can dispatch it
+ * but no agent ever sees it: an agent that can see a reversal entry point can
+ * call it with an invented handle, and an agent inventing a plausible undo
+ * identifier is a thing that happened on the simPRO shakedown. The platform
+ * resolves its own token first and only then dispatches here with
+ * `{ ref, undo_token }`.
+ *
+ * By the time this runs the platform has checked that the token exists,
+ * belongs to this actor and company, has not expired, and has been claimed
+ * exactly once. This runner re-checks none of that, because it cannot. It does
+ * one thing: load the copy, re-pin the connection the original write hit,
+ * hand both to the app's restore, and report honestly.
+ *
+ * THE RE-PIN IS THE WHOLE GAME. The platform dispatches with no memory of
+ * which store / organisation / business the original write targeted. Without
+ * `pin`, a replay lands on the install's CURRENT default and rebuilds the
+ * object in the wrong customer account, and nothing errors.
+ *
+ * `E` is the env the tool receives; `P` is what `pin` hands to `restore`. For
+ * a store-pinned env they are the same type (Shopify). For an app that
+ * re-authenticates per actor and organisation, `P` is the fresh token state
+ * (Xero), which is why they are separate parameters.
+ *
+ * Extracted from the Shopify and Xero `undo-apply.ts` handlers, which were
+ * byte-similar apart from their restore call and their pin.
+ */
+
+interface RestoreSpec<P, T = Record<string, unknown>> {
+    resource: string;
+    fidelity: UndoFidelity;
+    /**
+     * Rebuild or write back, through the PINNED connection. May return
+     * `{ ok: false, error }` or throw; both become `restore_failed` and the
+     * before-image is kept.
+     */
+    restore: (pinned: P, before: T, row: JournalRowLike<T>) => Promise<{
+        ok: boolean;
+        newId?: string;
+        error?: string;
+    } | void>;
+    /** What the restore does NOT bring back, folded into the note verbatim. */
+    notRestored?: string;
+}
+interface JournalRowLike<T = unknown> {
+    entity: string;
+    original_id: string;
+    connection: string | null;
+    before: T;
+}
+interface UndoApplyOptions<E, P = E> {
+    env: E;
+    journal: {
+        loadBefore<T = unknown>(ref: string): Promise<JournalRowLike<T> | null>;
+        dropBefore(ref: string): Promise<void>;
+    };
+    specs: Record<string, RestoreSpec<P>>;
+    /**
+     * Re-pin to the journalled connection. May be async (re-auth per actor, as
+     * Xero does). Throw to report `connection_unavailable`; return null to
+     * REFUSE with `connection_mismatch`, e.g. a session-stateful app whose
+     * current business differs from the row's.
+     */
+    pin: (env: E, connection: string | null, args: ToolArgs) => Promise<P | null> | P | null;
+}
+type UndoApplyResult = {
+    ok: true;
+    resource: string;
+    original_id: string;
+    connection: string | null;
+    new_id: string | null;
+    fidelity: UndoFidelity;
+    not_restored?: string;
+    note: string;
+} | {
+    ok: false;
+    error: string;
+    note: string;
+};
+/** Run the reversal. Every failure names what it was and states that nothing changed. */
+declare function runUndoApply<E, P = E>(args: ToolArgs, opts: UndoApplyOptions<E, P>): Promise<UndoApplyResult>;
+
+/**
+ * Declare a dispatcher tool's confirmation policy beside its action registry,
+ * emit it into the manifest with a `gen:` script, and let a test prove that
+ * every write action is either gated or knowingly exempt.
+ *
+ * This is the Xero app's `confirmation-policy.ts` + its test, generalised. The
+ * two things that fail SILENTLY are what the checker exists for: a rule keyed
+ * on an action that does not exist (dead rule, no gate, no error) and a
+ * placeholder path that renders "(unset)" in the prompt a human is asked to
+ * approve.
+ */
+interface PolicySource {
+    /** Money has left, a customer has been mailed, or the vendor offers no way back. */
+    irreversible?: Record<string, string>;
+    /** Gated on every call, reversible but real. */
+    always?: Record<string, string>;
+    /** Full rules, for thresholds and anything the two maps above cannot express. */
+    rules?: Record<string, ConfirmRule>;
+}
+/** Build a sorted `{ actions }` policy. An action named in two groups throws. */
+declare function buildConfirmationPolicy(src: PolicySource): ConfirmationPolicy;
+/**
+ * Action-name prefixes that mean "this writes". Used only for coverage: every
+ * registry action with one of these prefixes must be gated or listed as
+ * deliberately ungated. Reads (`get_`, `list_`, `search_`) are not here.
+ */
+declare const DEFAULT_WRITE_PREFIXES: readonly string[];
+/** Fields a threshold must never be placed on: a numeric string never trips. */
+declare const DEFAULT_MONEY_FIELDS: readonly string[];
+interface PolicyCheckInput {
+    policy: ConfirmationPolicy;
+    /** Every dispatchable action name (the registry KEYS). */
+    registry: Iterable<string>;
+    /** Write actions deliberately left ungated, each a conscious choice. */
+    ungated?: readonly string[];
+    writePrefixes?: readonly string[];
+    /**
+     * The input fields an action REQUIRES. A `describe` may interpolate only
+     * those (or a field named by its own `when.count`): an optional field is
+     * absent on some calls by definition and renders as "(unset)". Omit to skip
+     * this check.
+     */
+    requiredInput?: (action: string) => readonly string[] | undefined;
+    /**
+     * True (default) when the tool nests params under `input`: every placeholder
+     * and count path must then be dotted through `input.`, because the platform
+     * evaluates against the TOP-LEVEL args it reads `action` from.
+     */
+    nestedUnderInput?: boolean;
+    moneyFields?: readonly string[];
+}
+/**
+ * Every way a policy can be wrong without erroring, as a list of findings.
+ * An app's test is `expect(checkConfirmationPolicy(...)).toEqual([])`.
+ */
+declare function checkConfirmationPolicy(input: PolicyCheckInput): string[];
+
+/**
+ * The two halves of offering an undo, for handlers that are not behind an
+ * approval card (a dispatcher's `update_*` actions, for instance). The order
+ * is the whole contract:
+ *
+ *   const before = await safeCapture(scope, action, id, () => read(pinned, id));
+ *   const result = await write(pinned, input);              // happens regardless
+ *   const _undo  = await offerUndo({ journal, entity: action, id, before, connection, ... });
+ *   return { ok: true, result, ...(_undo ? { _undo } : {}) };
+ *
+ * `requireApproval` uses the same two functions on its granted pass.
+ */
+/**
+ * Read the before-image, degrading to null on any failure. A capture that
+ * throws (404, scope denied, network) is not a reason to refuse a write the
+ * user asked for; it is a reason to offer no undo, and to say so in the log.
+ */
+declare function safeCapture(scope: string, name: string, id: string, capture: () => Promise<unknown>): Promise<Record<string, unknown> | null>;
+interface OfferUndoArgs {
+    journal: CaptureJournal;
+    /** The tool or action that captured; the reverse tool looks the spec up by it. */
+    entity: string;
+    id: string;
+    /** From `safeCapture`. Null means no undo is offered, deliberately. */
+    before: Record<string, unknown> | null;
+    /** The resolved store / organisation / business, or null for a single-connection app. */
+    connection: string | null;
+    fidelity: UndoFidelity;
+    resource: string;
+    /** How the change reads in `list_undoable_changes`; the connection is appended when present. */
+    describe: (before: Record<string, unknown>, id: string) => string;
+    /** Relayed verbatim; never empty. */
+    warning: string;
+    /** Word between the description and the connection: "on" for a store, "in" for an organisation. */
+    connectionPreposition?: 'on' | 'in';
+    /**
+     * What `describes` calls the connection, when the journalled id is not
+     * readable by a person (a Xero tenantId). Defaults to `connection`. The
+     * journal row always stores `connection` itself, because that is the pin.
+     */
+    connectionLabel?: string;
+}
+/**
+ * Store the before-image and build the `_undo` envelope, or return undefined
+ * when there is nothing to offer. Never returns an envelope for a null capture
+ * or a journal that could not store the copy.
+ */
+declare function offerUndo(args: OfferUndoArgs): Promise<AppUndoEnvelope | undefined>;
+
 /**
  * @sprigr/apps-app-sdk
  *
@@ -1225,4 +1759,4 @@ interface ExecutionContextLike {
 }
 type HandlerFn<TArgs, TResult> = (args: TArgs, env: Record<string, unknown>, ctx?: ExecutionContextLike) => Promise<TResult>;
 
-export { type Actor, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type D1Like, type D1PreparedStatementLike, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EventArgs, type ExecutionContextLike, type FetchFileResult, type FetchWithRetryOptions, type GetAppFileResult, type HandlerFn, type InboxOwner, type InstallBridge, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type PlatformHostEnv, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataIndexOpts, type SprigrDataSearchOpts, type SprigrDataSearchResult, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type ToolResult, type ToolWrapperOptions, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorTool, appFileUrl, base64ToBytes, buildMarketplaceWebhookUrl, bytesToBase64, canEmit, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, deleteAppFile, describeMissingBridge, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, overlaySprigr, ownerFromActorKey, parseActor, putAppFile, putAppFileStream, randomHex, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, tool, withSprigrEmitFallback };
+export { APPROVAL_GRANTED_KEY, type Actor, type AppApprovalEnvelope, type AppFileListItem, type AppFileUrlArgs, type AppFileUrlResult, type AppFilesEnv, type AppUndoEnvelope, type ApprovalSpec, type ArchiveOfferOptions, type ArchiveOfferRefusal, type CaptureJournal, type ConfirmCondition, type ConfirmRule, type ConfirmationPolicy, type D1Like, type D1PreparedStatementLike, DEFAULT_EMIT_TIMEOUT_MS, DEFAULT_MAX_FILE_BYTES, DEFAULT_MONEY_FIELDS, DEFAULT_WRITE_PREFIXES, type EmitMarketplaceEventOptions, type EmitResult, type EmitTransport, type EventArgs, type ExecutionContextLike, type FetchFileResult, type FetchWithRetryOptions, type GetAppFileResult, type HandlerFn, type InboxOwner, type InstallBridge, InvalidUndoEnvelopeError, type JournalRowLike, type MarketplaceEventEmitOpts, type MarketplaceEventSourceIntegration, NotConnectedError, type OAuthBouncerSignals, type OAuthState, type OfferUndoArgs, type PlatformHostEnv, type PolicyCheckInput, type PolicySource, type PutAppFileArgs, type PutAppFileResult, type PutAppFileStreamArgs, type RequireApprovalOptions, type RestoreSpec, type ScheduleArgs, type SprigrDataAggregationCell, type SprigrDataAggregationResult, type SprigrDataAggregationSpec, type SprigrDataApi, type SprigrDataIndexOpts, type SprigrDataSearchOpts, type SprigrDataSearchResult, type SprigrFilesApi, type SprigrFilesApiWithEdit, type SprigrFilesCreateInput, type SprigrFilesCreateResult, type SprigrFilesEditInput, type SprigrFilesEditResult, type SprigrFilesJobResult, type ToolArgs, type ToolHandler, type ToolResult, type ToolWrapperOptions, UNIT_SEP, type UndoApplyOptions, type UndoApplyResult, type UndoCaptureSpec, type UndoFidelity, type WebhookArgs, type WfpBridgeEnv, type WfpEmitReply, actorKey, actorTool, appFileUrl, approvalHash, archiveOfferRefusal, base64ToBytes, buildConfirmationPolicy, buildMarketplaceWebhookUrl, bytesToBase64, canEmit, checkConfirmationPolicy, constantTimeEqual, createMarketplaceEmitter, createToolWrappers, decodeState, deleteAppFile, describeMissingBridge, emitMarketplaceEvent, encodeState, fetchFileAsBase64, fetchFileBytes, fetchWithRetry, fullWarning, getAppFile, hmacSha256Hex, installTokenPost, isNotConnectedError, isStagingHost, listAppFiles, offerUndo, overlaySprigr, ownerFromActorKey, parseActor, putAppFile, putAppFileStream, randomHex, recreatedWarning, refuseWithoutForce, requireApproval, resolveInstallBridge, resolveOAuthBouncerBase, resolveOAuthBouncerCallbackUrl, resolvePlatformWebhookBase, runUndoApply, safeCapture, seq, set, tool, undoEnvelope, withSprigrEmitFallback };

package/dist/index.js

@@ -485,17 +485,450 @@ function listAppFiles(env, prefix) {
 function deleteAppFile(env, key) {
   return call(env, "delete", { key });
 }
+
+// src/write-protection/types.ts
+var APPROVAL_GRANTED_KEY = "_approval_granted";
+
+// src/write-protection/approval-hash.ts
+var UNIT_SEP = "";
+function set(values) {
+  if (!Array.isArray(values)) return "";
+  return [...values].map((v) => String(v)).sort().join(UNIT_SEP);
+}
+function seq(values) {
+  if (!Array.isArray(values)) return "";
+  return values.map((v) => String(v)).join(UNIT_SEP);
+}
+function approvalHash(...parts) {
+  return parts.map((p) => p === void 0 || p === null ? "" : String(p)).join(UNIT_SEP);
+}
+
+// src/write-protection/undo-envelope.ts
+var InvalidUndoEnvelopeError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidUndoEnvelopeError";
+  }
+};
+function undoEnvelope(input) {
+  if (input.fidelity !== "full" && input.fidelity !== "recreated") {
+    throw new InvalidUndoEnvelopeError(
+      `_undo.fidelity must be 'full' or 'recreated', got ${JSON.stringify(input.fidelity)}`
+    );
+  }
+  for (const key of ["warning", "describes", "resource", "ref"]) {
+    const v = input[key];
+    if (typeof v !== "string" || v.trim() === "") {
+      throw new InvalidUndoEnvelopeError(
+        `_undo.${key} must be a non-empty string; the platform drops the whole envelope and mints no token on a blank field`
+      );
+    }
+  }
+  return {
+    fidelity: input.fidelity,
+    warning: input.warning.trim(),
+    describes: input.describes.trim(),
+    resource: input.resource.trim(),
+    ref: input.ref
+  };
+}
+function recreatedWarning(resource, notRestored) {
+  const base = `Not a true undo: the original ${resource} is permanently gone and its id will never be reissued. Reversing creates a NEW ${resource} from the saved copy, under a new id, so anything that referenced the old id stays broken.`;
+  return notRestored && notRestored.trim() ? `${base} Not restored: ${notRestored.trim()}.` : base;
+}
+function fullWarning(notRestored) {
+  const base = "Reversing writes the previously saved values back over the record, so any change made to it since then is overwritten.";
+  return notRestored && notRestored.trim() ? `${base} It does not restore ${notRestored.trim()}.` : base;
+}
+
+// src/write-protection/refuse-without-force.ts
+function idOf(args, keys) {
+  for (const k of keys) {
+    const v = args[k];
+    if (typeof v === "string" && v.trim() || typeof v === "number") return String(v);
+  }
+  return null;
+}
+function archiveOfferRefusal(deleteAction, args, opts) {
+  const id = idOf(args, opts.idKeys ?? ["id"]);
+  const link = id && opts.link ? opts.link(args, id) : void 0;
+  return {
+    ok: false,
+    deleted: false,
+    archive_available: true,
+    resource: opts.resource,
+    record_id: id,
+    delete_action: deleteAction,
+    archive_action: opts.archiveAction,
+    ...link ? { link } : {},
+    note: `Nothing was deleted. This ${opts.resource}${id ? ` (${id})` : ""} can be ARCHIVED instead with ${opts.archiveAction}, which keeps its id and is reversible; a delete throws the id away for good and cannot be undone. Offer the archive to the person first. If they explicitly want it destroyed even though it cannot be recovered, call ${deleteAction} again with force: true.`
+  };
+}
+function refuseWithoutForce(deleteAction, inner, opts) {
+  return async (args, env, ctx) => {
+    const a = args ?? {};
+    if (a.force === true) {
+      const { force: _force, ...rest } = a;
+      return inner(rest, env, ctx);
+    }
+    return archiveOfferRefusal(deleteAction, a, opts);
+  };
+}
+
+// src/write-protection/undo-capture.ts
+async function safeCapture(scope, name, id, capture) {
+  try {
+    const got = await capture();
+    return got && typeof got === "object" ? got : null;
+  } catch (err) {
+    console.warn(`[${scope}] ${name} ${id}: capture failed, writing without undo: ${String(err)}`);
+    return null;
+  }
+}
+async function offerUndo(args) {
+  if (!args.before) return void 0;
+  const captured = await args.journal.captureBefore({
+    entity: args.entity,
+    originalId: args.id,
+    before: args.before,
+    connection: args.connection
+  });
+  if (!captured) return void 0;
+  const base = args.describe(args.before, args.id);
+  const prep = args.connectionPreposition ?? "on";
+  const label = args.connectionLabel ?? args.connection;
+  return undoEnvelope({
+    fidelity: args.fidelity,
+    warning: args.warning,
+    describes: label ? `${base} ${prep} ${label}` : base,
+    resource: args.resource,
+    ref: captured.ref
+  });
+}
+
+// src/write-protection/require-approval.ts
+function rawIdOf(args, keys) {
+  for (const k of keys) {
+    const v = args[k];
+    if (typeof v === "string" && v || typeof v === "number") return String(v);
+  }
+  return "";
+}
+function isOk(result) {
+  return !!result && typeof result === "object" && result.ok !== false;
+}
+function requireApproval(handlers, specs, opts) {
+  const gated = {};
+  for (const [name, spec] of Object.entries(specs)) {
+    const inner = handlers[name];
+    if (!inner) {
+      throw new Error(
+        `requireApproval: "${name}" has an approval spec but is not in the handler registry. It was probably renamed or removed; update the specs in the same change, or a destructive tool ships ungated.`
+      );
+    }
+    if (spec.undo && !opts.journal) {
+      throw new Error(`requireApproval: "${name}" declares undo but no journal was supplied.`);
+    }
+    gated[name] = async (args, env, ctx) => {
+      const a = args ?? {};
+      if (a[APPROVAL_GRANTED_KEY] === true) {
+        const { [APPROVAL_GRANTED_KEY]: _granted, ...rest } = a;
+        return granted(name, spec, rest, env, ctx, inner, opts);
+      }
+      const connection = await opts.resolveConnection(env, a);
+      const rawId = rawIdOf(a, spec.keys);
+      const pinned = connection ? opts.pinEnv(env, connection) : env;
+      const target = rawId && opts.describeTarget ? await safeLabel(opts.describeTarget, pinned, rawId) : rawId || "(unknown id)";
+      const extra = spec.hash ? spec.hash(a) : [];
+      return {
+        ok: false,
+        _approval: {
+          ...spec.describe(target, a, connection),
+          hash: approvalHash(rawId, connection, ...extra)
+        }
+      };
+    };
+  }
+  return gated;
+}
+async function safeLabel(fn, env, id) {
+  try {
+    const label = await fn(env, id);
+    return label && label.trim() ? label : id;
+  } catch {
+    return id;
+  }
+}
+async function granted(name, spec, args, env, ctx, inner, opts) {
+  const connection = await opts.resolveConnection(env, args);
+  const stamp = (r) => connection && opts.stampConnection ? opts.stampConnection(r, connection) : r;
+  const undo = spec.undo;
+  const id = rawIdOf(args, spec.keys);
+  if (!undo || !id) return stamp(await inner(args, env, ctx));
+  const pinned = connection ? opts.pinEnv(env, connection) : env;
+  const before = await safeCapture(opts.scope, name, id, () => undo.capture(pinned, id, args));
+  const result = await inner(args, env, ctx);
+  if (!isOk(result) || !before) return stamp(result);
+  const envelope = await offerUndo({
+    journal: opts.journal(env),
+    entity: name,
+    id,
+    before,
+    connection: connection || null,
+    fidelity: undo.fidelity,
+    resource: undo.resource,
+    describe: undo.describe,
+    warning: undo.warning(id, before)
+  });
+  if (!envelope) return stamp(result);
+  return { ...stamp(result), _undo: envelope };
+}
+
+// src/write-protection/undo-apply.ts
+async function runUndoApply(args, opts) {
+  const ref = typeof args.ref === "string" ? args.ref.trim() : "";
+  if (!ref) return { ok: false, error: "missing_ref", note: "No before-image reference was supplied. Nothing was changed." };
+  const row = await opts.journal.loadBefore(ref);
+  if (!row) {
+    return {
+      ok: false,
+      error: "before_image_missing",
+      note: "The saved copy of this record is no longer available, so it cannot be restored. Nothing was changed."
+    };
+  }
+  const spec = opts.specs[row.entity];
+  if (!spec) {
+    return {
+      ok: false,
+      error: "undo_no_longer_supported",
+      note: `This app no longer knows how to reverse a "${row.entity}" change. Nothing was changed.`
+    };
+  }
+  const before = row.before;
+  if (!before || typeof before !== "object") {
+    return { ok: false, error: "before_image_unreadable", note: "The saved copy could not be read back. Nothing was changed." };
+  }
+  let pinned;
+  try {
+    pinned = await opts.pin(opts.env, row.connection, args);
+  } catch (err) {
+    return {
+      ok: false,
+      error: "connection_unavailable",
+      note: `Could not reach the connection this change was made in${row.connection ? ` (${row.connection})` : ""}: ${String(err)}. Nothing was changed.`
+    };
+  }
+  if (pinned === null || pinned === void 0) {
+    return {
+      ok: false,
+      error: "connection_mismatch",
+      note: `This change was made in ${row.connection ?? "a different connection"}, which is not the one currently selected. Switch to it and retry. Nothing was changed.`
+    };
+  }
+  let result;
+  try {
+    result = await spec.restore(pinned, before, row) ?? { ok: true };
+  } catch (err) {
+    result = { ok: false, error: String(err) };
+  }
+  if (!result.ok) {
+    return {
+      ok: false,
+      error: "restore_failed",
+      note: `The provider refused to restore the ${spec.resource}: ${result.error ?? "unknown error"}. Nothing was restored.`
+    };
+  }
+  await opts.journal.dropBefore(ref);
+  const recreated = spec.fidelity === "recreated";
+  return {
+    ok: true,
+    resource: spec.resource,
+    original_id: row.original_id,
+    connection: row.connection,
+    new_id: result.newId ?? null,
+    fidelity: spec.fidelity,
+    ...spec.notRestored ? { not_restored: spec.notRestored } : {},
+    note: recreated ? `Created a NEW ${spec.resource}${result.newId ? ` (${result.newId})` : ""} from the saved copy. The original ${row.original_id} is still gone and its id will never be reissued.${spec.notRestored ? ` Not restored: ${spec.notRestored}.` : ""} Report this as a replacement, not as an undo.` : `Restored ${spec.resource} ${row.original_id} to its saved values.${spec.notRestored ? ` Not restored: ${spec.notRestored}.` : ""} Anything changed since the capture was overwritten.`
+  };
+}
+
+// src/write-protection/confirmation-policy.ts
+function buildConfirmationPolicy(src) {
+  const actions = {};
+  const put = (name, rule, group) => {
+    if (actions[name]) throw new Error(`buildConfirmationPolicy: "${name}" is declared twice (second time in ${group})`);
+    actions[name] = rule;
+  };
+  for (const [name, describe] of Object.entries(src.irreversible ?? {})) put(name, { always: true, describe, irreversible: true }, "irreversible");
+  for (const [name, describe] of Object.entries(src.always ?? {})) put(name, { always: true, describe }, "always");
+  for (const [name, rule] of Object.entries(src.rules ?? {})) put(name, rule, "rules");
+  return { actions: Object.fromEntries(Object.entries(actions).sort(([a], [b]) => a.localeCompare(b))) };
+}
+var DEFAULT_WRITE_PREFIXES = [
+  "create_",
+  "update_",
+  "delete_",
+  "remove_",
+  "set_",
+  "add_",
+  "archive_",
+  "unarchive_",
+  "void_",
+  "refund_",
+  "cancel_",
+  "send_",
+  "email_",
+  "post_",
+  "publish_",
+  "unpublish_",
+  "approve_",
+  "reject_",
+  "submit_",
+  "allocate_",
+  "mark_",
+  "complete_",
+  "reopen_",
+  "convert_",
+  "clone_",
+  "upload_",
+  "attach_",
+  "detach_",
+  "move_",
+  "merge_",
+  "assign_",
+  "unassign_",
+  "pay_",
+  "capture_",
+  "process_",
+  "apply_",
+  "authorise_",
+  "authorize_",
+  "register_",
+  "unregister_",
+  "rotate_",
+  "revoke_",
+  "clear_",
+  "reset_",
+  "purge_",
+  "force_",
+  "import_",
+  "push_",
+  "invite_",
+  "swap_",
+  "bulk_",
+  "batch_",
+  "unship_",
+  "offboard_",
+  "hold_",
+  "release_",
+  "retry_",
+  "trigger_",
+  "record_",
+  "adjust_",
+  "receive_",
+  "dispatch_",
+  "transfer_",
+  "link_",
+  "unlink_",
+  "enable_",
+  "disable_",
+  "pause_",
+  "resume_",
+  "restore_",
+  "replace_",
+  "insert_",
+  "patch_",
+  "put_",
+  "write_",
+  "save_",
+  "book_",
+  "schedule_",
+  "reschedule_",
+  "escalate_",
+  "resolve_",
+  "dismiss_",
+  "accept_",
+  "decline_",
+  "follow_",
+  "unfollow_",
+  "like_",
+  "comment_",
+  "deactivate_",
+  "activate_",
+  "suspend_",
+  "generate_",
+  "issue_",
+  "charge_"
+];
+var DEFAULT_MONEY_FIELDS = ["amount", "total", "unit_amount", "sub_total", "price", "budget"];
+var PLACEHOLDER = /\{([a-zA-Z0-9_.]+)\}/g;
+function conditions(rule) {
+  return !rule.when ? [] : Array.isArray(rule.when) ? rule.when : [rule.when];
+}
+function checkConfirmationPolicy(input) {
+  const registry = new Set(input.registry);
+  const ungated = input.ungated ?? [];
+  const prefixes = input.writePrefixes ?? DEFAULT_WRITE_PREFIXES;
+  const nested = input.nestedUnderInput ?? true;
+  const money = new Set(input.moneyFields ?? DEFAULT_MONEY_FIELDS);
+  const actions = input.policy.actions ?? {};
+  const out = [];
+  for (const [name, rule] of Object.entries(actions)) {
+    if (!registry.has(name)) out.push(`dead rule: "${name}" is not in the registry, so it gates nothing`);
+    if (!rule.always && conditions(rule).length === 0) out.push(`${name}: rule says nothing (no always, no when)`);
+    if (!rule.describe || !rule.describe.trim()) out.push(`${name}: describe missing`);
+    else if (rule.describe.trim().endsWith(".")) out.push(`${name}: describe must not end in a period (platform renders "Action: <text>.")`);
+    const required = new Set(input.requiredInput?.(name) ?? []);
+    for (const c of conditions(rule)) {
+      if (!(c.atLeast >= 1)) out.push(`${name}: atLeast must be >= 1 (${c.atLeast} is always true; use always: true)`);
+      if (nested && !c.count.startsWith("input.")) out.push(`${name}: count "${c.count}" must be dotted through input.`);
+      const leaf = c.count.split(".").pop() ?? "";
+      if (money.has(leaf)) out.push(`${name}: threshold on money field "${c.count}" is bypassed by a numeric string; use always`);
+      required.add(c.count.replace(/^input\./, "").split(".")[0]);
+    }
+    for (const m of (rule.describe ?? "").matchAll(PLACEHOLDER)) {
+      const path = m[1];
+      if (nested && !path.startsWith("input.")) {
+        out.push(`${name}: placeholder {${path}} is not under input. and will render as (unset)`);
+        continue;
+      }
+      if (input.requiredInput) {
+        const field = path.replace(/^input\./, "").replace(/\.length$/, "").split(".")[0];
+        if (!required.has(field)) out.push(`${name}: placeholder {${path}} reads "${field}", which the action does not require, so it renders as (unset) when omitted`);
+      }
+    }
+  }
+  for (const name of ungated) {
+    if (!registry.has(name)) out.push(`ungated list: "${name}" is not in the registry`);
+    if (actions[name]) out.push(`ungated list: "${name}" is also gated; remove one`);
+  }
+  for (const name of registry) {
+    if (!prefixes.some((p) => name.startsWith(p))) continue;
+    if (actions[name] || ungated.includes(name)) continue;
+    out.push(`unclassified write: "${name}" is neither gated nor listed as deliberately ungated`);
+  }
+  return out.sort();
+}
 export {
+  APPROVAL_GRANTED_KEY,
   DEFAULT_EMIT_TIMEOUT_MS,
   DEFAULT_MAX_FILE_BYTES,
+  DEFAULT_MONEY_FIELDS,
+  DEFAULT_WRITE_PREFIXES,
+  InvalidUndoEnvelopeError,
   NotConnectedError,
+  UNIT_SEP,
   actorKey,
   actorTool,
   appFileUrl,
+  approvalHash,
+  archiveOfferRefusal,
   base64ToBytes,
+  buildConfirmationPolicy,
   buildMarketplaceWebhookUrl,
   bytesToBase64,
   canEmit,
+  checkConfirmationPolicy,
   constantTimeEqual,
   createMarketplaceEmitter,
   createToolWrappers,
@@ -507,22 +940,32 @@ export {
   fetchFileAsBase64,
   fetchFileBytes,
   fetchWithRetry,
+  fullWarning,
   getAppFile,
   hmacSha256Hex,
   installTokenPost,
   isNotConnectedError,
   isStagingHost,
   listAppFiles,
+  offerUndo,
   overlaySprigr,
   ownerFromActorKey,
   parseActor,
   putAppFile,
   putAppFileStream,
   randomHex,
+  recreatedWarning,
+  refuseWithoutForce,
+  requireApproval,
   resolveInstallBridge,
   resolveOAuthBouncerBase,
   resolveOAuthBouncerCallbackUrl,
   resolvePlatformWebhookBase,
+  runUndoApply,
+  safeCapture,
+  seq,
+  set,
   tool,
+  undoEnvelope,
   withSprigrEmitFallback
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprigr/apps-app-sdk",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -30,6 +30,10 @@
   },
   "files": [
     "dist",
+    "bin",
     "README.md"
-  ]
+  ],
+  "bin": {
+    "sprigr-check-write-protection": "./bin/check-write-protection.mjs"
+  }
 }