@ikenga/contract 0.9.1 → 0.10.0

package/src/canvas/use-pan-zoom.ts

@@ -18,6 +18,8 @@ export interface UsePanZoomArgs {
   editMode: boolean;
   /** Re-fit on window resize. Default true. */
   autoFitOnResize?: boolean;
+  /** Arrow-key pan + +/- zoom when the canvas root is focused. Default true (WCAG 2.5.7). */
+  keyboardPan?: boolean;
   /** Notified whenever the viewport pan/scale changes (controlled mirror). */
   onViewportChange?: (viewport: Viewport) => void;
   /** Escape exits edit mode → parent owns the state flip. */
@@ -49,6 +51,7 @@ export function usePanZoom(args: UsePanZoomArgs): UsePanZoom {
     layout,
     editMode,
     autoFitOnResize = true,
+    keyboardPan = true,
     onViewportChange,
     onEditModeChange,
     onSelectionChange,
@@ -130,7 +133,9 @@ export function usePanZoom(args: UsePanZoomArgs): UsePanZoom {
     autoFit(true);
   }, [editMode, autoFit]);
 
-  // Keyboard — Escape exits edit, Space arms the pan-grab cursor.
+  // Keyboard — Escape exits edit, Space arms the pan-grab cursor. When the
+  // canvas root itself holds focus, arrow keys pan and +/- zoom: the keyboard
+  // alternative to space+drag / pinch-zoom (WCAG 2.5.7 Dragging Movements).
   useEffect(() => {
     const down = (e: KeyboardEvent) => {
       if (e.key === 'Escape' && editMode) {
@@ -147,6 +152,42 @@ export function usePanZoom(args: UsePanZoomArgs): UsePanZoom {
         canvasRef.current.style.cursor = 'grab';
         e.preventDefault();
       }
+      // Arrow-pan / +/- zoom only when the canvas surface itself is focused,
+      // so widget-internal controls keep their own arrow-key semantics.
+      if (keyboardPan && canvasRef.current && document.activeElement === canvasRef.current) {
+        // 24 canvas units per step, scaled so the on-screen nudge feels
+        // consistent at any zoom level.
+        const PAN_STEP = 24;
+        const ZOOM_STEP = 0.1;
+        switch (e.key) {
+          case 'ArrowUp':
+            setPan((p) => ({ ...p, y: p.y + PAN_STEP * p.scale }));
+            e.preventDefault();
+            break;
+          case 'ArrowDown':
+            setPan((p) => ({ ...p, y: p.y - PAN_STEP * p.scale }));
+            e.preventDefault();
+            break;
+          case 'ArrowLeft':
+            setPan((p) => ({ ...p, x: p.x + PAN_STEP * p.scale }));
+            e.preventDefault();
+            break;
+          case 'ArrowRight':
+            setPan((p) => ({ ...p, x: p.x - PAN_STEP * p.scale }));
+            e.preventDefault();
+            break;
+          default:
+            // '=' shares the key with '+'; both Equal and NumpadAdd zoom in.
+            if (e.code === 'Equal' || e.code === 'NumpadAdd') {
+              setPan((p) => ({ ...p, scale: Math.min(2, p.scale + ZOOM_STEP) }));
+              e.preventDefault();
+            } else if (e.code === 'Minus' || e.code === 'NumpadSubtract') {
+              setPan((p) => ({ ...p, scale: Math.max(0.2, p.scale - ZOOM_STEP) }));
+              e.preventDefault();
+            }
+            break;
+        }
+      }
     };
     const up = (e: KeyboardEvent) => {
       if (e.code === 'Space') {
@@ -160,7 +201,7 @@ export function usePanZoom(args: UsePanZoomArgs): UsePanZoom {
       window.removeEventListener('keydown', down);
       window.removeEventListener('keyup', up);
     };
-  }, [editMode, onEditModeChange, onSelectionChange]);
+  }, [editMode, keyboardPan, onEditModeChange, onSelectionChange]);
 
   const beginPan = useCallback((clientX: number, clientY: number) => {
     const p = panRef.current;

package/src/index.ts

@@ -7,6 +7,7 @@ export * from './iyke.js';
 export * from './artifact.js';
 export * from './registry.js';
 export * from './browser.js';
+export * from './pa-actions.js';
 
 /** This package's own version. */
 export const CONTRACT_PACKAGE_VERSION = '0.5.0' as const;

package/src/manifest.test.ts

@@ -2,9 +2,14 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 
 import {
+  HttpCapabilitySchema,
+  IKENGA_API_VERSION,
+  InvokeCapabilitySchema,
   ManifestSchema,
+  NamedSecretSchema,
   RequiresEntrySchema,
   RequireSourceSchema,
+  SecretsCapabilitySchema,
 } from './manifest.js';
 
 // ─── WP-11 — `requires` field (ADR-015 §3) ──────────────────────────────────
@@ -82,6 +87,96 @@ test('Manifest: requires defaults to [] when absent (pre-Phase-4 manifest)', ()
   assert.deepEqual(m.requires, []);
 });
 
+// ─── WP-01 — trusted-cap tier (ADR-017): http / secrets / invoke + signature ─
+
+test('IKENGA_API_VERSION is 3 (ADR-017 soft bump)', () => {
+  assert.equal(IKENGA_API_VERSION, 3);
+});
+
+test('HttpCapability: auth_header defaults to Authorization; auth_secret optional', () => {
+  const h = HttpCapabilitySchema.parse({});
+  assert.equal(h.auth_header, 'Authorization');
+  assert.equal(h.auth_secret, undefined);
+});
+
+test('HttpCapability: .strict rejects unknown field (mirrors Rust deny_unknown_fields)', () => {
+  assert.throws(() => HttpCapabilitySchema.parse({ bogus: true }));
+});
+
+test('NamedSecret: full shape parses; required defaults false', () => {
+  const s = NamedSecretSchema.parse({ name: 'twenty', vault_key: 'TWENTY_API_KEY' });
+  assert.equal(s.required, false);
+  const r = NamedSecretSchema.parse({
+    name: 'k',
+    vault_key: 'K',
+    required: true,
+    format: 'bearer',
+  });
+  assert.equal(r.required, true);
+  assert.equal(r.format, 'bearer');
+});
+
+test('NamedSecret: .strict rejects unknown field', () => {
+  assert.throws(() =>
+    NamedSecretSchema.parse({ name: 'k', vault_key: 'K', bogus: true }),
+  );
+});
+
+test('SecretsCapability: declarations default to []', () => {
+  const s = SecretsCapabilitySchema.parse({});
+  assert.deepEqual(s.declarations, []);
+});
+
+test('InvokeCapability: empty object parses; commands defaults to [] (presence gate)', () => {
+  assert.deepEqual(InvokeCapabilitySchema.parse({}), { commands: [] });
+});
+
+test('InvokeCapability (D-06): commands allowlist parses + survives', () => {
+  const i = InvokeCapabilitySchema.parse({ commands: ['pa_actions_commit', 'pa_actions_reject'] });
+  assert.deepEqual(i.commands, ['pa_actions_commit', 'pa_actions_reject']);
+});
+
+test('InvokeCapability: .strict rejects unknown field (mirrors Rust deny_unknown_fields)', () => {
+  assert.throws(() => InvokeCapabilitySchema.parse({ commands: [], bogus: true }));
+});
+
+test('Manifest: fully-populated trusted-cap manifest round-trips (G-MANIFEST DoD)', () => {
+  // The contract-side half of the round-trip parse-fixture: a manifest carrying
+  // ALL FOUR new fields — top-level `signature`, `capabilities.http` (with
+  // auth_secret + custom header), `capabilities.secrets` (with a declaration),
+  // and the presence-gate `capabilities.invoke` — parses and the values survive.
+  const m = ManifestSchema.parse({
+    ...BASE,
+    ikenga_api: '3',
+    signature: 'ed25519:Zm9vYmFyYmF6',
+    permissions: { net: ['https://api.twenty.com/'], 'vault.keys': ['TWENTY_API_KEY'] },
+    capabilities: {
+      http: { auth_secret: 'twenty', auth_header: 'X-Api-Key' },
+      secrets: {
+        declarations: [
+          { name: 'twenty', vault_key: 'TWENTY_API_KEY', required: true, format: 'bearer' },
+        ],
+      },
+      invoke: { commands: ['pa_actions_commit'] },
+    },
+  });
+  assert.equal(m.signature, 'ed25519:Zm9vYmFyYmF6');
+  assert.equal(m.capabilities?.http?.auth_secret, 'twenty');
+  assert.equal(m.capabilities?.http?.auth_header, 'X-Api-Key');
+  assert.equal(m.capabilities?.secrets?.declarations.length, 1);
+  assert.equal(m.capabilities?.secrets?.declarations[0].vault_key, 'TWENTY_API_KEY');
+  assert.equal(m.capabilities?.secrets?.declarations[0].required, true);
+  assert.ok(m.capabilities?.invoke !== undefined);
+  // D-06: the invoke command allowlist survives the round-trip.
+  assert.deepEqual(m.capabilities?.invoke?.commands, ['pa_actions_commit']);
+});
+
+test('Manifest: api=1 manifest without new fields parses (back-compat)', () => {
+  const m = ManifestSchema.parse({ ...BASE });
+  assert.equal(m.signature, undefined);
+  assert.equal(m.capabilities, undefined);
+});
+
 test('Manifest: retired bundling fields are no longer part of the type (WP-17)', () => {
   // ADR-015 decision 4: `skills`/`commands`/`agents` were hard-retired from the
   // schema (lockstep with the Rust `deny_unknown_fields` Manifest, which REJECTS

package/src/manifest.ts

@@ -13,7 +13,10 @@ import { EngineProvidesSchema } from './engine/index.js';
 
 // v2 (WP-05): added capabilities.sqlite + permissions["sqlite.tables"];
 // permissions["supabase.tables"] kept as a compat alias for api=1 manifests.
-export const IKENGA_API_VERSION = 2 as const;
+// v3 (ADR-017): added capabilities.http / .secrets / .invoke (trusted-cap tier)
+// + top-level optional `signature`. All additive; api=1/2 manifests parse
+// unchanged. Elevated caps are inert unless the pkg is trusted.
+export const IKENGA_API_VERSION = 3 as const;
 export const IKENGA_API_MIN_SUPPORTED = 1 as const;
 
 // ---------- Sub-schemas ----------
@@ -183,6 +186,65 @@ export type WebviewCapability = z.infer<typeof WebviewCapabilitySchema>;
 export const AgentOpsCapabilitySchema = z.object({});
 export type AgentOpsCapability = z.infer<typeof AgentOpsCapabilitySchema>;
 
+/** host.fetch capability (ADR-017, TRUSTED-only). Host-mediated HTTP proxy;
+ *  the shell makes the request and attaches auth from Stronghold — the key
+ *  never enters the iframe. URL allowlist = `permissions.net`. Mirrors
+ *  `HttpCapability` in `shell/src-tauri/src/pkg/manifest.rs`. */
+export const HttpCapabilitySchema = z
+  .object({
+    /** Name of a `capabilities.secrets` declaration whose resolved value the
+     *  shell attaches as the auth header. Omit = unauthenticated proxy. */
+    auth_secret: z.string().optional(),
+    /** Header name for the auth secret. Default "Authorization". */
+    auth_header: z.string().default('Authorization'),
+  })
+  .strict();
+export type HttpCapability = z.infer<typeof HttpCapabilitySchema>;
+
+/** One named-secret declaration. `vault_key` is resolved host-side and never
+ *  reaches the iframe; the iframe sees only `hostContext.secrets[name]`.
+ *  Mirrors `NamedSecret` in `shell/src-tauri/src/pkg/manifest.rs`. */
+export const NamedSecretSchema = z
+  .object({
+    name: z.string(),
+    /** Vault key (must be within permissions["vault.keys"]). Host-only. */
+    vault_key: z.string(),
+    /** When true, mount fails if the key is missing (Supabase `required`). */
+    required: z.boolean().default(false),
+    /** Optional value-format hint: "jwt" | "bearer" | "raw". String, not enum. */
+    format: z.string().optional(),
+  })
+  .strict();
+export type NamedSecret = z.infer<typeof NamedSecretSchema>;
+
+/** Named-secret injection capability (ADR-017, TRUSTED-only). Generalizes the
+ *  Supabase hostContext handshake. Mirrors `SecretsCapability` in
+ *  `shell/src-tauri/src/pkg/manifest.rs`. */
+export const SecretsCapabilitySchema = z
+  .object({
+    declarations: z.array(NamedSecretSchema).default([]),
+  })
+  .strict();
+export type SecretsCapability = z.infer<typeof SecretsCapabilitySchema>;
+
+/** Scoped Tauri invoke passthrough (ADR-017, TRUSTED-only). Presence gates
+ *  `host.invoke`; `commands` is the named-command allowlist matched (glob) by
+ *  `permissions_check::check_shell_execute` against the `host.invoke` command.
+ *
+ *  D-06: the allowlist is `invoke`'s OWN field, NOT `permissions["shell.execute"]`.
+ *  Reusing `shell.execute` would trip `requires_trust` → the pkg only ever reaches
+ *  user-`Granted`, never `AutoTrusted`, so `is_trusted_for_elevated()` is false and
+ *  `host.invoke` would always deny. Keeping the allowlist here lets a signed/builtin
+ *  pkg declare invokable commands while leaving `shell.execute` empty → AutoTrusted →
+ *  elevated. POLICY: named commands only, never `*` (not a general shell).
+ *  Mirrors `InvokeCapability` in `shell/src-tauri/src/pkg/manifest.rs`. */
+export const InvokeCapabilitySchema = z
+  .object({
+    commands: z.array(z.string()).default([]),
+  })
+  .strict();
+export type InvokeCapability = z.infer<typeof InvokeCapabilitySchema>;
+
 export const WindowBlockSchema = z.object({
   label: z.string(),
   url: z.string(),
@@ -283,6 +345,12 @@ export const ManifestSchema = z.object({
     sqlite: SqliteCapabilitySchema.optional(),
     webview: WebviewCapabilitySchema.optional(),
     agentOps: AgentOpsCapabilitySchema.optional(),
+    /** host.fetch proxy (ADR-017). Inert unless the pkg is trusted. */
+    http: HttpCapabilitySchema.optional(),
+    /** Named-secret injection (ADR-017). Inert unless trusted. */
+    secrets: SecretsCapabilitySchema.optional(),
+    /** host.invoke passthrough (ADR-017). Inert unless trusted. */
+    invoke: InvokeCapabilitySchema.optional(),
   }).optional(),
 
   /**
@@ -310,6 +378,13 @@ export const ManifestSchema = z.object({
    * (`pkg/manifest.rs`) — keep in lockstep (`deny_unknown_fields`).
    */
   requires: z.array(RequiresEntrySchema).default([]),
+
+  /** Optional ed25519 signature over the normalized manifest JSON (sort keys,
+   *  strip `signature` before signing). Format `"ed25519:<base64>"`. Present
+   *  on notarized registry pkgs; verified at install against the publisher key
+   *  the signed registry index named. Absent → pkg isn't trusted (no elevated
+   *  caps). Mirrors `signature: Option<String>` on the Rust `Manifest`. */
+  signature: z.string().optional(),
 });
 
 export type Manifest = z.infer<typeof ManifestSchema>;

package/src/pa-actions.test.ts

@@ -0,0 +1,92 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { type ApproveGateMeta, type DraftItem, draftPreview, fromDraftItem } from './pa-actions.js';
+
+const META: ApproveGateMeta = {
+	actionId: 'com.ikenga.skill-mail/reply',
+	actionName: 'Reply',
+	agent: 'PA',
+	model: 'Opus 4.7',
+};
+
+function item(over: Partial<DraftItem> = {}): DraftItem {
+	return {
+		id: 'd1',
+		recipient: 'Valentim de Carvalho',
+		recipientEmail: 'valentim@valentimdc.pt',
+		subject: 'Re: Catalog import',
+		body: 'Olá Valentim,\n\nRecebido.   Vou processar agora.',
+		channel: 'smtp',
+		senderAddress: 'chinedum@royalti.io',
+		fromProvider: 'SMTP · Fastmail',
+		scheduledIso: null,
+		scheduledLabel: 'today',
+		...over,
+	};
+}
+
+// Anchor everything to LOCAL time so the day-bucketing assertions are
+// timezone-independent (new Date(y, m, d, h) is local-time construction).
+const NOW = new Date(2026, 5, 7, 11, 0, 0).getTime(); // 11:00 local, 2026-06-07
+const TODAY_ISO = new Date(2026, 5, 7, 17, 0, 0).toISOString(); // same local day, future
+const OVERDUE_ISO = new Date(2026, 5, 5, 9, 0, 0).toISOString(); // two days earlier
+
+test('fromDraftItem maps producer fields + meta', () => {
+	const d = fromDraftItem(item(), META, NOW);
+	assert.equal(d.id, 'd1');
+	assert.equal(d.agent, 'PA');
+	assert.equal(d.model, 'Opus 4.7');
+	assert.equal(d.channel, 'smtp');
+	assert.equal(d.consequence.channel, 'SMTP');
+	assert.equal(d.consequence.target, 'Valentim de Carvalho');
+	assert.equal(d.consequence.recipients, 1);
+	assert.equal(d.consequence.undoMs, 10_000);
+	assert.equal(d.everEdited, false);
+	assert.equal(d.cold, false);
+});
+
+test('fromDraftItem buckets an overdue draft', () => {
+	const d = fromDraftItem(item({ scheduledIso: OVERDUE_ISO }), META, NOW);
+	assert.equal(d.overdue, true);
+	assert.equal(d.timeVariant, 'is-overdue');
+	assert.equal(d.section, 'Overdue');
+	assert.equal(d.status, 'overdue');
+});
+
+test('fromDraftItem buckets a same-day draft as today', () => {
+	const d = fromDraftItem(item({ scheduledIso: TODAY_ISO }), META, NOW);
+	assert.equal(d.overdue, false);
+	assert.equal(d.timeVariant, 'is-today');
+	assert.equal(d.section, 'Today');
+	assert.equal(d.status, 'awaiting');
+});
+
+test('an explicit section overrides time bucketing', () => {
+	const d = fromDraftItem(item({ scheduledIso: OVERDUE_ISO, section: 'This week' }), META, NOW);
+	assert.equal(d.section, 'This week');
+	assert.equal(d.overdue, true); // overdue flag still reflects the clock
+});
+
+test('sequence recipient count flows into the consequence', () => {
+	const d = fromDraftItem(
+		item({
+			recipients: 388,
+			sequence: { name: 'L5 Winback', step: 3, total: 5, recipients: 388 },
+		}),
+		META,
+		NOW
+	);
+	assert.equal(d.consequence.recipients, 388);
+	assert.equal(d.sequence?.step, 3);
+});
+
+test('undoMs falls back to 10s when meta omits it', () => {
+	const d = fromDraftItem(item(), { ...META, undoMs: undefined }, NOW);
+	assert.equal(d.consequence.undoMs, 10_000);
+});
+
+test('draftPreview collapses whitespace and truncates', () => {
+	assert.equal(draftPreview('a   b\n\nc'), 'a b c');
+	assert.ok(draftPreview('x'.repeat(300)).length <= 160);
+	assert.ok(draftPreview('x'.repeat(300)).endsWith('…'));
+});

package/src/pa-actions.ts

@@ -0,0 +1,252 @@
+/**
+ * Approve-gate draft types — the run-then-pause (`ux_mode: approve`) payload.
+ *
+ * An approve-aware action does its work, then — instead of performing the
+ * external side effect — hands the shell a batch of `DraftItem`s plus an
+ * `ApproveGateMeta` via the (forthcoming) `host.paActionsPause` verb. The shell
+ * persists them to `pa_action_drafts` (ikenga.db), emits `pa-action-paused`, and
+ * mounts the approve-gate panel
+ * (`shell/src/shell/atelier/surfaces/approve-gate-panel.tsx`) at
+ * `/outbox/approvals`. The panel renders the rich `PausedDraft` view-model;
+ * `fromDraftItem` derives it from the lean producer `DraftItem` so producers
+ * stay simple (they never hand-build display state).
+ *
+ * Scope: `plans/atelier/10-approve-gate-seam.md` (WP-1); behaviour:
+ * `07-fe-button-renderer.md` §3.5. Plain-TS by convention (mirrors
+ * `host-verbs.ts`) — runtime validation, when needed, lives at the host boundary.
+ */
+
+/** Outbound channel an approve gate commits to. Locked to provider identity. */
+export type DraftChannel = 'smtp' | 'resend' | 'listmonk' | 'buffer';
+
+/** Human channel label (display). */
+export const CHANNEL_LABEL: Record<DraftChannel, string> = {
+	smtp: 'SMTP',
+	resend: 'Resend',
+	listmonk: 'Listmonk',
+	buffer: 'Buffer',
+};
+
+/** A draft's position inside an outreach sequence/drip, if any. */
+export interface DraftSequence {
+	name: string;
+	step: number;
+	total: number;
+	/** Audience size for this step (e.g. a 388-recipient newsletter section). */
+	recipients: number;
+}
+
+/**
+ * What an approve-aware action emits per draft — the lean, authoritative
+ * producer shape. The shell derives the panel's `PausedDraft` from this via
+ * `fromDraftItem` (computes preview, time bucketing, consequence), so an action
+ * never hand-builds display state.
+ */
+export interface DraftItem {
+	id: string;
+	/** Recipient display (a person, or a broadcast target like "L5 Winback · 388 recipients"). */
+	recipient: string;
+	recipientEmail: string | null;
+	tenantId?: string | null;
+	subject: string;
+	body: string;
+	channel: DraftChannel;
+	/** Sending address, e.g. "chinedum@royalti.io" or "ned@getroyalti.com". */
+	senderAddress: string;
+	/** Sending route display, e.g. "SMTP · Fastmail". */
+	fromProvider: string;
+	/** Cold outreach (separate sender domain / reputation). */
+	cold?: boolean;
+	/**
+	 * Audience size for the consequence line; defaults to 1.
+	 * Kept for display (e.g. "388 recipients"); use `recipientsList` for the actual
+	 * per-recipient send list on direct-email channels.
+	 */
+	recipients?: number;
+	/**
+	 * Actual recipient list for direct-email channels (smtp, resend).
+	 * Adapters iterate this for per-recipient sends + partial-success tracking (DEC-9).
+	 * Broadcast channels (listmonk, buffer) address a list/channel audience and
+	 * ignore this field.
+	 */
+	recipientsList?: { name?: string; email: string }[];
+	/**
+	 * Body content type — adapters set the MIME part accordingly.
+	 * Defaults to `'text'` when absent.
+	 */
+	bodyFormat?: 'html' | 'text';
+	/** Reply-To header for direct-email channels (smtp, resend). */
+	replyTo?: string;
+	/** Machine schedule time (ISO) for overdue/today bucketing; null = unscheduled. */
+	scheduledIso: string | null;
+	/** Row time display, e.g. "scheduled 17:00" / "today" / "2d late". */
+	scheduledLabel: string;
+	/** Detail-chip schedule display, e.g. "Scheduled · today 17:00". Falls back to scheduledLabel. */
+	scheduledChip?: string;
+	sequence?: DraftSequence | null;
+	deal?: string | null;
+	threadCount?: string;
+	/** Explicit section bucket; otherwise derived from `scheduledIso`. */
+	section?: string;
+}
+
+/**
+ * Partial-success result returned by a `ChannelAdapter.send()` call (DEC-9).
+ * `ok` is true when at least one recipient was accepted; `failed` lists
+ * per-recipient errors so callers can surface them without dropping success.
+ * Shared here so the contract module is the single SoT; the daemon's
+ * `lib/channels/types.ts` imports it directly from `@ikenga/contract`.
+ */
+export interface SendResult {
+	/** False only when ALL recipients failed (or a batch-level error occurred). */
+	ok: boolean;
+	/** Provider message/campaign/post id — write around the network call where supported (G-05). */
+	externalId?: string;
+	/** Addresses the provider accepted (partial success — DEC-9). */
+	sent?: string[];
+	/** Per-recipient failures for partial-success scenarios. */
+	failed?: { email: string; error: string }[];
+	/** Batch-level error message (to error_text column) when ok is false. */
+	error?: string;
+	/** True for transient errors (5xx/429/network) — drives in-worker retry vs permanent fail. */
+	retryable?: boolean;
+}
+
+/** Batch-level metadata for one approve-mode run (the gate header + undo window). */
+export interface ApproveGateMeta {
+	/** `<pkgId>/<verb>` that produced the batch. */
+	actionId: string;
+	/** Human action name for the gate header. */
+	actionName: string;
+	/** Drafting agent label, e.g. "PA" / "CMO" / "CBO". */
+	agent: string;
+	/** Engine/model that drafted, e.g. "Opus 4.7". */
+	model: string;
+	/** Undo window before commit, ms. Defaults to 10_000. */
+	undoMs?: number;
+}
+
+/**
+ * The rich view-model the approve-gate panel renders. Kept byte-identical to the
+ * panel's prior local definition so the panel just imports it. Derived from a
+ * `DraftItem` + `ApproveGateMeta` via `fromDraftItem`; the panel flips
+ * `everEdited`/`status` locally as the operator edits.
+ */
+export interface PausedDraft {
+	id: string;
+	recipient: string;
+	recipientEmail: string | null;
+	tenantId: string | null;
+	subject: string;
+	body: string;
+	bodyPreview: string;
+	channel: DraftChannel;
+	agent: string;
+	senderAddress: string;
+	cold: boolean;
+	/**
+	 * Panel display status. `'failed'` means the send worker exhausted retries
+	 * and the draft needs operator attention (see `errorMessage` / `attempts`).
+	 */
+	status: 'awaiting' | 'edited' | 'overdue' | 'failed';
+	scheduledAt: string;
+	scheduledLabel: string;
+	timeVariant: 'is-today' | 'is-overdue' | null;
+	overdue: boolean;
+	everEdited: boolean;
+	section: string;
+	sequence: DraftSequence | null;
+	fromProvider: string;
+	model: string;
+	threadCount: string;
+	deal: string | null;
+	consequence: {
+		target: string;
+		recipients: number;
+		channel: string;
+		time: string;
+		undoMs: number;
+	};
+	/** Last error surfaced by the send worker (from pa_action_drafts.error_text). */
+	errorMessage?: string;
+	/** Number of send attempts so far (from pa_action_drafts.attempts). */
+	attempts?: number;
+}
+
+const PREVIEW_MAX = 160;
+const DEFAULT_UNDO_MS = 10_000;
+
+/** Collapse whitespace + truncate `body` for the row preview line. */
+export function draftPreview(body: string, max = PREVIEW_MAX): string {
+	const flat = body.replace(/\s+/g, ' ').trim();
+	return flat.length > max ? `${flat.slice(0, max - 1).trimEnd()}…` : flat;
+}
+
+function sameLocalDay(a: number, b: number): boolean {
+	const da = new Date(a);
+	const db = new Date(b);
+	return (
+		da.getFullYear() === db.getFullYear() &&
+		da.getMonth() === db.getMonth() &&
+		da.getDate() === db.getDate()
+	);
+}
+
+/**
+ * Derive the panel's `PausedDraft` from a producer `DraftItem` + the batch
+ * `ApproveGateMeta`. `now` is injectable for deterministic tests; it only affects
+ * time bucketing (overdue / today / section). Pure + side-effect-free.
+ *
+ * `errorMessage` and `attempts` are not derivable from a `DraftItem` (they live
+ * on the DB row after worker runs); callers that reconstruct a `PausedDraft` from
+ * a stored row should set them on the returned object directly.
+ */
+export function fromDraftItem(
+	item: DraftItem,
+	meta: ApproveGateMeta,
+	now: number = Date.now()
+): PausedDraft {
+	const scheduledMs = item.scheduledIso ? Date.parse(item.scheduledIso) : null;
+	const hasTime = scheduledMs !== null && !Number.isNaN(scheduledMs);
+	const overdue = hasTime && (scheduledMs as number) < now;
+	const today = hasTime && !overdue && sameLocalDay(scheduledMs as number, now);
+	const timeVariant: PausedDraft['timeVariant'] = overdue
+		? 'is-overdue'
+		: today
+			? 'is-today'
+			: null;
+	const section = item.section ?? (overdue ? 'Overdue' : today ? 'Today' : 'This week');
+
+	return {
+		id: item.id,
+		recipient: item.recipient,
+		recipientEmail: item.recipientEmail,
+		tenantId: item.tenantId ?? null,
+		subject: item.subject,
+		body: item.body,
+		bodyPreview: draftPreview(item.body),
+		channel: item.channel,
+		agent: meta.agent,
+		senderAddress: item.senderAddress,
+		cold: item.cold ?? false,
+		status: overdue ? 'overdue' : 'awaiting',
+		scheduledAt: item.scheduledLabel,
+		scheduledLabel: item.scheduledChip ?? item.scheduledLabel,
+		timeVariant,
+		overdue,
+		everEdited: false,
+		section,
+		sequence: item.sequence ?? null,
+		fromProvider: item.fromProvider,
+		model: meta.model,
+		threadCount: item.threadCount ?? '',
+		deal: item.deal ?? null,
+		consequence: {
+			target: item.recipient,
+			recipients: item.recipients ?? 1,
+			channel: CHANNEL_LABEL[item.channel],
+			time: item.scheduledLabel,
+			undoMs: meta.undoMs ?? DEFAULT_UNDO_MS,
+		},
+	};
+}