@startsimpli/integrations 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Provider-agnostic types, API clients, hooks, and UI primitives for email + calendar integrations across StartSimpli apps.",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/__tests__/connections.test.tsx

@@ -204,6 +204,7 @@ function stubApi(overrides: Partial<ConnectionsApi> = {}): ConnectionsApi {
     }),
     connectionRuns: vi.fn().mockResolvedValue({ results: [] }),
     updateConnection: vi.fn().mockResolvedValue(CONNECTED.results[0]),
+    rotateCredential: vi.fn().mockResolvedValue(CONNECTED.results[0]),
     ...overrides,
   } as ConnectionsApi;
 }
@@ -383,6 +384,181 @@ describe('capabilities are the admin’s choice, and the page has to ask', () =>
   });
 });
 
+// --------------------------------------------------------------------------
+//  a card an admin can actually maintain (bd startsim-768w.22.24)
+// --------------------------------------------------------------------------
+
+/**
+ * WHAT A CONNECTED CARD COULD DO BEFORE THIS: test it, discover its workflows,
+ * change its capabilities, wire and fire a target. That is the whole list. It
+ * could not have its KEY REPLACED and it could not be REMOVED — the two things
+ * an admin holding a freshly-minted API key actually needs.
+ *
+ * `POST /connections/<id>/credential/` has done a checked, non-destructive
+ * rotation since the endpoint was designed, and `DELETE /connections/<id>/` has
+ * done a transactional disconnect for just as long. `disconnect` was even
+ * declared on this page's own api contract. NOTHING RENDERED EITHER ONE. So an
+ * admin with a new key had exactly one control that looked like it would take
+ * one — the connect form — and using it hit a duplicate-credential collision
+ * that came back as a Django HTML 500 (the server half is bd
+ * startsim-768w.22.24 too). The missing button is the actual bug; the 500 is
+ * only where it surfaced.
+ */
+describe('replacing the key on a connection that already exists', () => {
+  async function openReplaceForm(api = stubApi()) {
+    render(<ConnectionsPage api={api} foundrySlug="acme" />);
+    await screen.findByText('Ops n8n');
+    await userEvent.click(screen.getByRole('button', { name: /replace key|new key/i }));
+    return api;
+  }
+
+  it('offers a way to replace the key on a connected card', async () => {
+    render(<ConnectionsPage api={stubApi()} foundrySlug="acme" />);
+    await screen.findByText('Ops n8n');
+    expect(
+      screen.getByRole('button', { name: /replace key|new key/i }),
+    ).toBeInTheDocument();
+  });
+
+  it('renders the connector’s OWN credential fields, from the catalog row', async () => {
+    // Same schema-driven renderer as the connect form. A bespoke "paste your
+    // key" box would be the per-vendor branch this layer exists to refuse: the
+    // fixture connector takes a url + a secret + a select, and the replace form
+    // has to show the ones that are credentials.
+    await openReplaceForm();
+    expect(await screen.findByLabelText(/Public API key/i)).toBeInTheDocument();
+  });
+
+  it('says the current key survives a bad paste, where the admin can read it', async () => {
+    // The reassurance someone pasting a production key wants, and it is TRUE:
+    // rotation runs check() against the vendor and writes only on success, so a
+    // wrong key leaves the working one live. Saying nothing here is what makes
+    // people go looking for a "safer" path — which is the connect form.
+    await openReplaceForm();
+    expect(
+      screen.getByText(/before it replaces|until the new one|only if it works|nothing changes/i),
+    ).toBeInTheDocument();
+  });
+
+  it('sends the pasted key to the ROTATE endpoint, not to connect', async () => {
+    const api = await openReplaceForm();
+    await userEvent.type(screen.getByLabelText(/Public API key/i), 'n_new_key_123');
+    await userEvent.click(screen.getByRole('button', { name: /^replace$|test and replace/i }));
+
+    await waitFor(() => expect(api.rotateCredential).toHaveBeenCalledWith('acme', 'c1', {
+      api_key: 'n_new_key_123',
+    }));
+    expect(api.connect).not.toHaveBeenCalled();
+  });
+
+  it('reports a rejected key instead of claiming the rotation landed', async () => {
+    const rejected = Object.assign(new Error('Invalid API key format'), { status: 401 });
+    const api = stubApi({ rotateCredential: vi.fn().mockRejectedValue(rejected) });
+    await openReplaceForm(api);
+    await userEvent.type(screen.getByLabelText(/Public API key/i), 'bad');
+    await userEvent.click(screen.getByRole('button', { name: /^replace$|test and replace/i }));
+
+    expect(await screen.findByText(/Invalid API key format/)).toBeInTheDocument();
+  });
+
+  it('does not offer to replace a key when manage is false', async () => {
+    const api = stubApi({
+      connections: vi.fn().mockResolvedValue({
+        ...CONNECTED,
+        permissions: { view: true, manage: false, issue_tokens: false },
+      }),
+    });
+    render(<ConnectionsPage api={api} foundrySlug="acme" />);
+    await screen.findByText('Ops n8n');
+    expect(
+      screen.queryByRole('button', { name: /replace key|new key/i }),
+    ).not.toBeInTheDocument();
+  });
+});
+
+describe('removing a connection', () => {
+  it('offers disconnect on a connected card', async () => {
+    render(<ConnectionsPage api={stubApi()} foundrySlug="acme" />);
+    await screen.findByText('Ops n8n');
+    expect(screen.getByRole('button', { name: /disconnect/i })).toBeInTheDocument();
+  });
+
+  it('CONFIRMS first, and says what stops', async () => {
+    // Disconnect is not an edit. It stops the scheduled fetches, stops the
+    // outbound sends and revokes every token issued for this account, in one
+    // transaction. A single misclick doing all of that silently is not a
+    // control an admin can use with confidence.
+    const api = stubApi();
+    render(<ConnectionsPage api={api} foundrySlug="acme" />);
+    await screen.findByText('Ops n8n');
+    await userEvent.click(screen.getByRole('button', { name: /^disconnect$/i }));
+
+    expect(api.disconnect).not.toHaveBeenCalled();
+    expect(screen.getByText(/stop|revoke/i)).toBeInTheDocument();
+  });
+
+  it('disconnects once confirmed, and refreshes the list', async () => {
+    const api = stubApi();
+    render(<ConnectionsPage api={api} foundrySlug="acme" />);
+    await screen.findByText('Ops n8n');
+    await userEvent.click(screen.getByRole('button', { name: /^disconnect$/i }));
+    await userEvent.click(screen.getByRole('button', { name: /yes, disconnect|confirm disconnect/i }));
+
+    await waitFor(() => expect(api.disconnect).toHaveBeenCalledWith('acme', 'c1'));
+    // Two loads: the mount, and the one after the card changed.
+    await waitFor(() => expect(
+      (api.connections as ReturnType<typeof vi.fn>).mock.calls.length,
+    ).toBeGreaterThan(1));
+  });
+
+  it('lets an admin back out of the confirmation', async () => {
+    const api = stubApi();
+    render(<ConnectionsPage api={api} foundrySlug="acme" />);
+    await screen.findByText('Ops n8n');
+    await userEvent.click(screen.getByRole('button', { name: /^disconnect$/i }));
+    await userEvent.click(screen.getByRole('button', { name: /cancel/i }));
+
+    expect(api.disconnect).not.toHaveBeenCalled();
+    expect(
+      screen.queryByRole('button', { name: /yes, disconnect|confirm disconnect/i }),
+    ).not.toBeInTheDocument();
+  });
+
+  it('does not offer disconnect when manage is false', async () => {
+    const api = stubApi({
+      connections: vi.fn().mockResolvedValue({
+        ...CONNECTED,
+        permissions: { view: true, manage: false, issue_tokens: false },
+      }),
+    });
+    render(<ConnectionsPage api={api} foundrySlug="acme" />);
+    await screen.findByText('Ops n8n');
+    expect(screen.queryByRole('button', { name: /disconnect/i })).not.toBeInTheDocument();
+  });
+});
+
+describe('the connect form knows what is already connected', () => {
+  it('says so, and names the card, before an admin fills the form in again', async () => {
+    // The server now answers a duplicate connect with a 409 that names the card
+    // (bd startsim-768w.22.24) instead of an IntegrityError. Saying it HERE
+    // costs a round trip less and, more to the point, catches the admin before
+    // they have pasted a production key into the wrong form.
+    render(<ConnectionsPage api={stubApi()} foundrySlug="acme" />);
+    await userEvent.click(await screen.findByRole('button', { name: /^connect$/i }));
+    expect(screen.getByText(/already connected/i)).toBeInTheDocument();
+    expect(screen.getAllByText(/Ops n8n/).length).toBeGreaterThan(1);
+  });
+
+  it('still allows a SECOND account on the same vendor', async () => {
+    // Two workspaces on one vendor are two accounts and two cards — the server
+    // says so in `Connection`'s own constraint. The warning is a warning, never
+    // a lock.
+    render(<ConnectionsPage api={stubApi()} foundrySlug="acme" />);
+    await userEvent.click(await screen.findByRole('button', { name: /^connect$/i }));
+    expect(screen.getByRole('button', { name: /test and save/i })).toBeInTheDocument();
+  });
+});
+
 describe('the catalog envelope, as the server actually ships it', () => {
   // REGRESSION. The first browser drive of this page died on
   // `(entry.credential_schema ?? []) is not iterable`, because these fixtures

package/src/__tests__/corpus-extract.test.ts

@@ -431,6 +431,28 @@ describe('extractCommitments', () => {
     expect(result.created).toBeGreaterThan(0);
   });
 
+  it('slices a sweep so one call fits the gateway, and says where to resume', async () => {
+    // A deployed tenant closes a request at 60s and one call over the whole
+    // corpus does not finish inside it (measured on tandem — 504). The sweep is
+    // therefore BATCHED INTO CALLS THAT FIT, never one call per document.
+    const corpus = createFixtureCorpusApi({ scope: TANDEM, documents: FIXTURE_TRACKED_DOCUMENTS });
+    const extractor = createFixtureExtractor();
+    const spy = vi.spyOn(extractor, 'extract');
+
+    const first = await extractCommitments({ scope: TANDEM, limit: 2 }, { corpus, extractor });
+    expect(first.documentsProcessed).toBe(2);
+    expect(first.totalDocuments).toBe(FIXTURE_TRACKED_DOCUMENTS.length);
+    expect(first.nextOffset).toBe(2);
+    expect(spy.mock.calls[0][0].documents).toHaveLength(2); // still N per call
+
+    const second = await extractCommitments(
+      { scope: TANDEM, offset: first.nextOffset!, limit: 2 },
+      { corpus, extractor },
+    );
+    expect(second.documentsProcessed).toBe(1);
+    expect(second.nextOffset).toBeNull();
+  });
+
   it('refuses outright when the session carries no workspace claim', async () => {
     const corpus = createFixtureCorpusApi({ leakScope: true, documents: FIXTURE_TRACKED_DOCUMENTS });
     const listDocuments = vi.spyOn(corpus, 'listDocuments');

package/src/__tests__/corpus-tracker.test.tsx

@@ -196,6 +196,8 @@ describe('TrackerPage — what is outstanding', () => {
 describe('TrackerPage — running the extraction', () => {
   const RESULT = {
     documentsProcessed: 16,
+    totalDocuments: 16,
+    nextOffset: null,
     fromRules: 24,
     fromModel: 11,
     created: 30,

package/src/components/pages/ConnectionsPage.tsx

@@ -9,7 +9,8 @@
  *
  * WHAT IT RENDERS, in the order the job actually happens:
  *
- *   1. connected accounts, each saying what it is and whether it is healthy
+ *   1. connected accounts, each saying what it is and whether it is healthy —
+ *      and each MAINTAINABLE: test it, replace its key, disconnect it
  *   2. the catalog — everything connectable, including rows that cannot load
  *   3. per connection: DISCOVER what the credential reaches -> WIRE a choice ->
  *      CONFIRM the derived config -> FIRE it, and the run history of both legs
@@ -18,6 +19,14 @@
  * and the CONFIRM step exists because a derived URL is a guess about the
  * vendor's own settings until a human agrees with it.
  *
+ * THE MAINTENANCE CONTROLS IN STEP 1 ARE NOT A DETAIL (bd startsim-768w.22.24).
+ * Without them a card is a dead end in both directions: an admin with a rotated
+ * vendor key cannot install it, and an admin who is done with a vendor cannot
+ * remove it. Both endpoints existed and worked; nothing rendered them, so the
+ * only control that looked like it would take a new key was the connect form —
+ * which makes a second card, not a replacement, and collided on a unique
+ * constraint that reached a live foundry as a Django HTML 500.
+ *
  * NOTHING HERE NAMES A VENDOR. Every difference between two vendors arrives as
  * data — the field schema, the capability list, the choice rows and their
  * reasons. A `if (connector === ...)` in this file would undo the DB-driven
@@ -135,12 +144,13 @@ export function ConnectionsPage({ api, foundrySlug, classNames = {} }: Connectio
             api={api}
             foundrySlug={foundrySlug}
             connection={connection}
-            // What the CONNECTOR declares, so the card can offer a capability
-            // this connection does not have yet — which is the only way an
-            // account connected before the picker existed ever gets one.
-            declared={
-              catalog.find((entry) => entry.key === connection.connector_key)?.capabilities
-            }
+            // The CONNECTOR's own catalog row. It carries the capability list,
+            // so the card can offer a capability this connection does not have
+            // yet — the only way an account connected before the picker existed
+            // ever gets one — and the credential schema, so replacing the key
+            // renders the same schema-driven form the connect path does rather
+            // than a bespoke "paste your key" box per vendor.
+            entry={catalog.find((row) => row.key === connection.connector_key)}
             canManage={permissions.manage}
             classNames={cn}
             onChanged={reload}
@@ -156,6 +166,11 @@ export function ConnectionsPage({ api, foundrySlug, classNames = {} }: Connectio
             api={api}
             foundrySlug={foundrySlug}
             entry={entry}
+            // What this foundry ALREADY has on this connector. A second vendor
+            // account is legitimate and stays possible; an admin who is really
+            // trying to install a new key is not, and they are the ones this
+            // form used to swallow.
+            existing={connections.filter((c) => c.connector_key === entry.key)}
             canManage={permissions.manage}
             classNames={cn}
             onConnected={reload}
@@ -240,11 +255,13 @@ function orderCapabilities(declared: string[], selected: Iterable<string>): stri
 // --------------------------------------------------------------------------
 
 function CatalogCard({
-  api, foundrySlug, entry, canManage, classNames: cn, onConnected,
+  api, foundrySlug, entry, existing, canManage, classNames: cn, onConnected,
 }: {
   api: ConnectionsApi;
   foundrySlug: string;
   entry: ConnectorCatalogEntry;
+  /** Cards this foundry already holds on this connector. */
+  existing: Connection[];
   canManage: boolean;
   classNames: typeof DEFAULTS;
   onConnected: () => void;
@@ -325,6 +342,23 @@ function CatalogCard({
 
       {open ? (
         <div className="mt-4 space-y-3">
+          {/* SAID BEFORE THE KEY IS PASTED, not after the server refuses.
+              Connecting again makes a SECOND account, which is legitimate and
+              stays available — but it is almost never what an admin holding a
+              rotated key wants, and it was the only thing this page offered
+              them. The server now answers the indistinguishable case with a 409
+              naming the card; this catches it a round trip earlier. */}
+          {existing.length > 0 ? (
+            <p className={cn.muted} data-already-connected={entry.key}>
+              Already connected as{' '}
+              <strong className="text-gray-900">
+                {existing.map((c) => c.name).join(', ')}
+              </strong>
+              . To install a new key, use <em>Replace key</em> on that
+              connection — it is tested before it replaces the working one.
+              Connecting here adds a SECOND account.
+            </p>
+          ) : null}
           <CredentialSchemaForm
             fields={fields}
             values={values}
@@ -375,17 +409,119 @@ function CatalogCard({
   );
 }
 
+// --------------------------------------------------------------------------
+//  replacing the key on a connection that already exists
+// --------------------------------------------------------------------------
+
+/**
+ * ROTATION, rendered from the same schema as the connect form.
+ *
+ * Two things make this safe to put in front of a non-engineer, and both are
+ * properties of the endpoint rather than of this component:
+ *
+ *   * the pasted credential is run through `check()` against the vendor BEFORE
+ *     anything is written, so a wrong key changes nothing and the working
+ *     connection stays up. That is said in the copy, because someone about to
+ *     paste a production key is entitled to know it;
+ *   * a PARTIAL map is legal. A connector with a url + a key + a select takes
+ *     just the key here, and the stored values fill in the rest — so replacing
+ *     a secret never means re-typing the settings around it.
+ *
+ * Only the CREDENTIAL fields render. `config` is not a credential and is edited
+ * through the connection's own settings; mixing them here would make a
+ * rotation quietly a config change.
+ */
+function ReplaceKeyForm({
+  api, foundrySlug, connection, entry, classNames: cn, onDone,
+}: {
+  api: ConnectionsApi;
+  foundrySlug: string;
+  connection: Connection;
+  entry?: ConnectorCatalogEntry;
+  classNames: typeof DEFAULTS;
+  onDone: () => void;
+}) {
+  const [values, setValues] = React.useState<Record<string, string>>({});
+  const [busy, setBusy] = React.useState(false);
+  const [error, setError] = React.useState('');
+
+  const fields = schemaFields(entry?.credential_schema);
+  const warnings = patternWarnings(fields, values);
+  // NOT `missingRequired`. A rotation is partial by design — the whole point is
+  // to replace one secret without re-typing the fields around it — so the gate
+  // is "something was actually typed", and the server decides the rest.
+  const submitted = React.useMemo(() => {
+    const out: Record<string, unknown> = {};
+    for (const spec of fields) {
+      const value = values[isSecret(spec) ? `${spec.key}__draft` : spec.key];
+      if (value) out[spec.key] = value;
+    }
+    return out;
+  }, [fields, values]);
+  const empty = Object.keys(submitted).length === 0;
+
+  return (
+    <div className="mt-3 space-y-3 border-t pt-3" data-replace-key={connection.id}>
+      <p className={cn.muted}>
+        The new key is tested against the vendor before it replaces the current
+        one. If it is rejected, nothing changes and this connection keeps
+        working on the key it has.
+      </p>
+      {fields.length === 0 ? (
+        <p className={cn.muted}>
+          This connector holds no credential of ours, so there is nothing to
+          replace.
+        </p>
+      ) : (
+        <CredentialSchemaForm
+          fields={fields}
+          values={values}
+          warnings={warnings}
+          idPrefix={`replace-${connection.id}`}
+          onChange={(key, value) => {
+            const spec = fields.find((f) => f.key === key);
+            setValues((prev) => ({
+              ...prev, [spec && isSecret(spec) ? `${key}__draft` : key]: value,
+            }));
+          }}
+        />
+      )}
+      {error ? <p className={cn.error} role="alert">{error}</p> : null}
+      <button
+        type="button"
+        className={cn.button}
+        disabled={busy || empty}
+        onClick={() => {
+          setBusy(true);
+          setError('');
+          api.rotateCredential(foundrySlug, connection.id, submitted)
+            .then(() => { setValues({}); onDone(); })
+            // The server's typed answer, verbatim: it already scrubbed itself of
+            // the values just submitted, and "the vendor rejected this key" is
+            // not something the browser could work out on its own.
+            .catch((err: unknown) => setError(
+              (err as { message?: string })?.message || 'Could not replace the key.'))
+            .finally(() => setBusy(false));
+        }}
+      >
+        {busy ? 'Testing…' : 'Test and replace'}
+      </button>
+    </div>
+  );
+}
+
 // --------------------------------------------------------------------------
 //  a connected account: discover -> wire -> confirm -> fire
 // --------------------------------------------------------------------------
 
 function ConnectionCard({
-  api, foundrySlug, connection, declared, canManage, classNames: cn, onChanged,
+  api, foundrySlug, connection, entry, canManage, classNames: cn, onChanged,
 }: {
   api: ConnectionsApi;
   foundrySlug: string;
   connection: Connection;
-  declared?: string[];
+  /** This connector's catalog row: its capabilities AND its field schema. */
+  entry?: ConnectorCatalogEntry;
   canManage: boolean;
   classNames: typeof DEFAULTS;
   onChanged: () => void;
@@ -396,7 +532,10 @@ function ConnectionCard({
   const [busy, setBusy] = React.useState('');
   const [error, setError] = React.useState('');
   const [notice, setNotice] = React.useState('');
+  const [replacing, setReplacing] = React.useState(false);
+  const [confirmingDisconnect, setConfirmingDisconnect] = React.useState(false);
 
+  const declared = entry?.capabilities;
   const enabled = React.useMemo(
     () => connection.capabilities_enabled ?? [], [connection.capabilities_enabled]);
   // The catalog's declaration first, then anything this connection holds that
@@ -444,7 +583,7 @@ function ConnectionCard({
           ) : null}
         </div>
         {canManage ? (
-          <div className="flex gap-2">
+          <div className="flex flex-wrap justify-end gap-2">
             <button
               type="button"
               className={cn.button}
@@ -457,6 +596,21 @@ function ConnectionCard({
             >
               Test
             </button>
+            {/* THE CONTROL THIS PAGE WAS MISSING. A vendor key gets rotated —
+                that is normal operations, not an exception — and the only place
+                to put the new one was a form that creates a second account. */}
+            <button
+              type="button"
+              className={cn.button}
+              disabled={Boolean(busy)}
+              onClick={() => {
+                setConfirmingDisconnect(false);
+                setError('');
+                setReplacing((v) => !v);
+              }}
+            >
+              {replacing ? 'Cancel' : 'Replace key'}
+            </button>
             <button
               type="button"
               className={cn.button}
@@ -470,10 +624,74 @@ function ConnectionCard({
             >
               {busy === 'discover' ? 'Loading…' : 'Workflows'}
             </button>
+            <button
+              type="button"
+              className={cn.button}
+              disabled={Boolean(busy) || confirmingDisconnect}
+              onClick={() => {
+                setReplacing(false);
+                setError('');
+                setConfirmingDisconnect(true);
+              }}
+            >
+              Disconnect
+            </button>
           </div>
         ) : null}
       </div>
 
+      {replacing ? (
+        <ReplaceKeyForm
+          api={api}
+          foundrySlug={foundrySlug}
+          connection={connection}
+          entry={entry}
+          classNames={cn}
+          onDone={() => { setReplacing(false); setNotice('New key installed.'); onChanged(); }}
+        />
+      ) : null}
+
+      {confirmingDisconnect ? (
+        <div className="mt-3 space-y-2 border-t pt-3" role="group"
+             aria-label="Confirm disconnect">
+          {/* Disconnect is one sentence to an admin and four writes to the
+              server, three of which cannot be undone by reconnecting: the
+              tokens this vendor holds against us are revoked and the stored
+              credential is deleted. Naming them is the difference between a
+              control someone uses deliberately and one they regret. */}
+          <p className={cn.muted}>
+            Disconnecting <strong className="text-gray-900">{connection.name}</strong>{' '}
+            will stop its scheduled fetches, stop anything it sends out, revoke
+            every token issued for it and delete the stored key. The card stays
+            here, marked disabled, and you can connect it again later with a new
+            key.
+          </p>
+          <div className="flex gap-2">
+            <button
+              type="button"
+              className={cn.button}
+              disabled={Boolean(busy)}
+              onClick={() => void guard('disconnect', async () => {
+                await api.disconnect(foundrySlug, connection.id);
+                setConfirmingDisconnect(false);
+                setNotice('Disconnected.');
+                onChanged();
+              })}
+            >
+              {busy === 'disconnect' ? 'Disconnecting…' : 'Yes, disconnect'}
+            </button>
+            <button
+              type="button"
+              className={cn.button}
+              disabled={Boolean(busy)}
+              onClick={() => setConfirmingDisconnect(false)}
+            >
+              Cancel
+            </button>
+          </div>
+        </div>
+      ) : null}
+
       {/* THE FIX FOR THE CARDS THAT ALREADY EXIST. A connection written before
           the connect form asked holds an empty list and can do nothing; the
           connect form can never reach it. Turning `poll` on here is what makes

package/src/components/pages/types.ts

@@ -181,6 +181,31 @@ export interface ConnectionsApi {
   checkConnection(slug: string, id: string): Promise<{
     ok: boolean; account_label: string; detail: string;
   }>;
+
+  /**
+   * REPLACE THE KEY on a connection that already exists.
+   *
+   * The endpoint has always done this well — the new credential is run through
+   * `check()` against the vendor FIRST and written only if it passes, so a bad
+   * paste leaves the working key live and the card untouched. It was simply not
+   * on this interface, so the page could not reach it and an admin holding a
+   * fresh key had only the connect form to try (bd startsim-768w.22.24). That
+   * form creates a SECOND card, which is a different thing entirely and, until
+   * the same bead, a 500.
+   *
+   * A PARTIAL map is legal and is the normal case: send the one field being
+   * replaced, and the stored values fill in the rest.
+   */
+  rotateCredential(slug: string, id: string, credentials: Record<string, unknown>):
+    Promise<Connection>;
+
+  /**
+   * DISCONNECT, not delete. One transaction stops the scheduled fetches, stops
+   * the outbound sends, revokes every token issued for this account and deletes
+   * the stored credential. The card survives, marked `disabled`, so the record
+   * that this vendor was ever connected is not thrown away — and it can be
+   * connected again later.
+   */
   disconnect(slug: string, id: string): Promise<void>;
   connectionChoices(slug: string, id: string, params?: {
     kind?: string; cursor?: string;

package/src/corpus/extract.ts

@@ -235,6 +235,17 @@ export interface ExtractRequest {
   scope: CorpusScope;
   /** Narrow the run to specific records. Omit to sweep the corpus. */
   documentIds?: string[];
+  /**
+   * Where this call starts in the in-scope corpus, and how many documents it
+   * may take. Omit both to do the whole thing in one model call.
+   *
+   * This exists for a deployment fact, not a design preference: the tandem ALB
+   * closes a request at 60 seconds, and one batched call over all sixteen real
+   * documents does not finish inside it (measured — 504). Slicing keeps every
+   * call batched over N documents while letting the caller walk the corpus.
+   */
+  offset?: number;
+  limit?: number;
 }
 
 export interface ExtractDeps {
@@ -258,12 +269,24 @@ export async function extractCommitments(
 
   const { documents: candidates, matched } = await readDocuments(corpus, documentLimit, maxPages);
   const { kept, dropped } = enforceScope(candidates, request.scope);
-  const documents = request.documentIds?.length
+  const inScope = request.documentIds?.length
     ? kept.filter((document) => request.documentIds!.includes(document.id))
     : kept;
 
+  // The slice this call handles. `listDocuments` orders stably (the tenant's
+  // (org_id, entity_type, -created_at) index), so an offset means the same thing
+  // between calls of one sweep.
+  const offset = Math.max(0, request.offset ?? 0);
+  const documents = request.limit ? inScope.slice(offset, offset + request.limit) : inScope.slice(offset);
+  const consumed = offset + documents.length;
+  const nextOffset = consumed < inScope.length ? consumed : null;
+
   if (documents.length === 0) {
-    return { ...empty(extractor, 'nothing in scope'), droppedOutOfScope: dropped.length };
+    return {
+      ...empty(extractor, 'nothing in scope'),
+      totalDocuments: inScope.length,
+      droppedOutOfScope: dropped.length,
+    };
   }
 
   // 3. rules first, so the model can be told what not to repeat.
@@ -317,6 +340,8 @@ export async function extractCommitments(
 
   return {
     documentsProcessed: documents.length,
+    totalDocuments: inScope.length,
+    nextOffset,
     fromRules: ruleDrafts.length,
     fromModel: modelDrafts.length,
     created: reconciled.created,
@@ -325,8 +350,8 @@ export async function extractCommitments(
     needsReview: resolutions.needsReview,
     droppedOutOfScope: dropped.length,
     provider: extractor.describe(),
-    ...(matched > candidates.length ? { } : {}),
   };
+  void matched;
 }
 
 /**
@@ -424,6 +449,8 @@ function empty(extractor: CorpusExtractorLlm, _why: string): ExtractionResult {
   void _why;
   return {
     documentsProcessed: 0,
+    totalDocuments: 0,
+    nextOffset: null,
     fromRules: 0,
     fromModel: 0,
     created: 0,

package/src/corpus/types.ts

@@ -565,12 +565,30 @@ export interface CommitmentTrackerApi extends CommitmentApi {
    * Run extraction over documents that have not been processed. Optional: a
    * read-only deployment omits it and the control does not render.
    */
-  extract?(input: { scope: CorpusScope; documentIds?: string[] }): Promise<ExtractionResult>;
+  extract?(input: {
+    scope: CorpusScope;
+    documentIds?: string[];
+    /** Resume point for a batched sweep. See `ExtractionResult.nextOffset`. */
+    offset?: number;
+    limit?: number;
+  }): Promise<ExtractionResult>;
 }
 
 export interface ExtractionResult {
-  /** Documents read and sent to the extractor. */
+  /** Documents read and sent to the extractor IN THIS CALL. */
   documentsProcessed: number;
+  /** Documents in scope altogether, so a partial sweep can say what it is of. */
+  totalDocuments: number;
+  /**
+   * Where a resumed sweep should start, or `null` when the corpus is done.
+   *
+   * A run is RESUMABLE because it has to be: a deployed tenant sits behind a
+   * gateway with a request timeout (60s on the tandem ALB, measured — a single
+   * call over sixteen documents 504s), and one model call per document is
+   * forbidden. So the sweep is batched into calls that fit, and the caller walks
+   * the offsets. Still N documents per model call; just not always all of them.
+   */
+  nextOffset: number | null;
   /** Items the vendor's own structure produced, with no model involved. */
   fromRules: number;
   /** Items only the model found. */