No Undo

1Three modes, three different ways to be wrong

We sent one freight invoice to Nutrient's extraction API three times — once in each mode, seconds apart. All three responses are committed in this repo. The cheapest one was the only one that behaved safely.

What understand mode returned

The failure is structural, not bad luck. Grounding answers is this value where the model says it is — which was true; it read the right box on the page. It cannot answer were the glyphs read correctly, which is what failed. recognitionScore is the only signal that measures that, and it was the only one that dissented.

What agentic mode did instead

Parcel 1   qty 2   $14.50
Parcel 2   qty 1   $39.99

"Parcel"   qty 1
"Parcel"   qty 2

The descriptions collapsed and the row numbers shifted into the quantity column. Two wrong fields either way — the expensive mode just moved them somewhere less visible, and removed the signal that would have flagged them.

2The routing decisionshipped

Routing is a nine-step ordered walk, not a confidence cutoff (mcp/nutrient/extraction-adapter.mjs). The match label decides first — fuzzy_match, not_found and id_match_partial route to a human regardless of any score. Only then does the composite confidence act as a tie-break, and only then do grounding and recognition act as vetoes.

The last two steps, on the wrong total

Router verdict: human review of this extraction. The extraction result — including the wrong total — is not allowed to flow onward unattended; a person has to look at it. Applying redactions is separately gated behind its own approval (alwaysRequireApproval: true), and the single pipeline (prompt → optional Nutrient enrichment → Foxit assembly → gate → eSign) now shares one PlanStore and one approval queue (P6). When Nutrient keys are absent, the pipeline reproduces with a single Foxit credential pair — the Foxit track's judged path — with Nutrient as optional enrichment.

3The signal the documented walk can't seeshipped

When the API cannot ground a field, it omits that field from output.data while leaving its citation — carrying match: "not_found" — in output.metadata.

Nutrient's own published iter_citations example walks data. So it structurally cannot see the single most important routing signal there is: the API telling you it failed. A field that silently vanishes reads, to any code walking data, exactly like a field that was never requested.

We walk the union of both. In all three committed fixtures, due_date and po_number are exactly this case.

4The document that looks redacted and isn'tshipped

Same gate, a second irreversible action. Staging redactions with createRedactions is reversible and runs unattended. applyRedactions destroys content permanently, so it sits behind alwaysRequireApproval: true — approval-gated in its own right, by the same mechanism the eSign stage uses for the send. The single pipeline shares one PlanStore and one approval queue across prompt → optional Nutrient enrichment → Foxit assembly → gate → eSign (P6).

Searching the raw bytes is not a sufficient check. Nutrient re-compresses the content stream, so the PII string is absent from all three files — the naive verification passes on a document that is still dangerous. Decompressing every FlateDecode stream shows what is actually there:

The staged document looks redacted and is not. The gap between a check that passes and a document that is still dangerous is precisely what the approval gate guards — and it is why applying redactions is treated as irreversible rather than as cleanup.

Verified live on 2026-08-20; the byte-level walk is recorded in docs/nutrient-stage-aug20.md. The staged artifact is committed at docs/fixtures/probe-staged.pdf — deliberately unredacted, because it is the evidence, not an accident.

5A preset that returns 200 and redacts nothingshipped

Same API, the opposite failure. Extraction lies about a number with high confidence; redaction lies about having removed one at all. preset: "vin" is in the adapter's CONFIRMED_PRESETS list because probing it against a live document returned HTTP 200 — a valid PDF came back. Testing it in isolation against a document containing the well-formed VIN 1FUJGLDR8CLBP8834 tells a different story:

Both calls succeed. Both return a document that opens. One did nothing to the VIN, and the only difference visible to a caller is a byte count — not something anyone thresholds on. A preset name recorded which identifiers the API accepts; that's a different question from which ones it matches, and the name had been carrying more weight than the probe behind it.

So the pipeline stopped trusting the apply call for any target. It re-reads the redacted document through /extraction/parse and confirms each value is gone before anything reaches the gate — the same verification step this page's previous finding rests on. `mcp/nutrient/pipeline-redaction.mjs` fails the run if a target can't be confirmed absent; the VIN preset itself now ships flagged non-functional and surfaced on the approval card, rather than quietly doing nothing.

6The gateshipped

What a human actually sees

Rendered by a custom renderPlan hook — the prompt, the recipients, how the extraction routed each field, what was redacted and the proof it's gone, the document hash, and an explicit irrevocability warning. Not JSON.stringify on the raw payload.

Verbatim field labels and values from a real run against --doc messy, reformatted for layout — the full card is in the README. The regex redaction target is deliberately described by shape, not printed: a pattern embeds the values it hides, so putting it on the review screen would leak them.

The crash-safe lifecycle

The industry pattern is consume() — mark the plan used, then make the API call. Both orderings lose on a crash: mark-then-call leaves an audit log claiming a send that never happened; call-then-mark re-sends the document on retry. The dangerous window straddles the call, and most designs don't model it.

beginExecute() journals executing and fsyncs before the send. Only host confirmation writes executed. A process that dies mid-send leaves a plan visibly stuck in executing — a queryable state, not a forgotten one. On restart the journal replays and the core asks the gateway the only question that matters:

The journal is append-only, fsync'd per record, mode 0o600, with a parent-directory fsync so a fresh journal survives power loss. Replaying it reconstructs exactly the state the system was in when it died. dataDigest is re-checked on beginExecute and fails closed, so an approval cannot be replayed against changed content.

Verbatim from the recorded demo

Real folder IDs, against the live eSign API. NO_UNDO_CRASH_AFTER_FSYNC=1 forces the same SIGKILL the journal is designed to survive, at the exact point after the fsync and before the gateway is called:

$ NO_UNDO_CRASH_AFTER_FSYNC=1 node agent/esign-agent-loop.mjs --auto-approve --doc messy \
    --prompt "Take this freight invoice, redact the PII, and send it to Alice and Bob for signature."
[agent] Draft: folderId=35704250 planToken=7c61234a… documentSha256=491d5ef8070b98b3…
[esign-audit] executing token=7c61234a... tool=esign_send
[crash-injection] SIGKILL after beginExecute fsync (token=7c61234a...) before the gateway send

# same command, no crash flag
$ node agent/esign-agent-loop.mjs --auto-approve --doc messy --prompt "Take this freight invoice…"
[agent] Recovered 1 stuck-executing plan(s) (reconciled on load):
  - planToken=7c61234a... folderId=35704250 → folderStatus=DRAFT → confirmed not executed → released for retry
[agent] Plan is executing — calling gateway sendDraftFolder…
[agent] Send succeeded — plan executed (verified SHARED)
[agent] Result: { "status": "executed", "verifiedStatus": "SHARED", "folderId": 35704276 }

The crash landed on the DRAFT side of the window: the gateway had never been called, so folder 35704250 was released rather than left stuck. This CLI has no flag to resume a specific plan, so the second command — a fresh invocation, not a retry of the first — drafts and sends a different folder (35704276) instead; the released draft just sits there for a human to act on later, never auto-resent. Had the crash landed on the other side of the window, the same query returns SHARED and recovery records the send instead of repeating it — the branch is chosen by the system of record, not by a guess, and no plan is ever sent twice.

The reconciliation callback and the three-way branch are implemented in mcp/foxit/esign-adapter.mjs and unit-tested against the Gate 0 fixtures, in addition to this live run. What the audit sink does not yet record: the post-send poll-and-download step that retrieves the signed document logs to the console but never writes to the hash-chained journal — the send itself is fully audited, that later step isn't.

7We audited our own gate and it failedshipped

The approval card above was written carefully to show only the folder name and recipients — no payload dump, because this is a PII demo. Then we checked the endpoint behind it.

GET /api/plans returned the raw payload anyway — a social security number and the full recipient list, straight past the redaction the card was performing. A host's careful renderPlan hook was being silently bypassed by the API serving it.

Filed upstream as safe-write-mcp-core issue #18, fixed in PR #19, published as v0.3.0 — the raw payload field is now dropped by default and available only via an explicit exposeRawPayload opt-in. This project consumes the fix by version bump. Two other servers built on the same core inherit it.

The second gap in the same server was authentication, not redaction: the approval server bound loopback and checked Host/Origin/Sec-Fetch-Site, which stops a malicious web page but not a hostile local process. Filed as issue #20, fixed upstream in v0.4.0 — every route now requires a per-session bearer token, carried in the approval URL's ?token=. This project runs on 0.4.0 today; both prior gaps are closed at the core, not patched around downstream.

Found by live reproduction, not by reading the code — a renderPlan hook surfacing only the folder name still returned the SSN over the API.

Architecture

Reversible steps run unattended. The irreversible ones — applying redactions, and sending for signature — stop at a human approval checkpoint that survives a crash without double-sending.

The gate itself is not Foxit-specific. safe-write-mcp-core owns only the plan lifecycle; preview rendering and reconciliation are host-supplied. Foxit and Nutrient are adapters, not dependencies — which is why the same kernel already sits behind two other servers.

Reproduce it

Every extraction claim on this page is backed by a committed API response. The fixtures and the test suite need no credentials; the probes make live billed calls and do.

No key required

Live, billed, needs a Nutrient key

By default probe output lands in an exclusive mode-0o600 temp directory, so nothing document-derived reaches the tracked repo unless --fixture is passed as an explicit decision to commit it. The probe schema deliberately asks for two fields the document does not contain — due_date and po_number — so not_found routing is exercised rather than assumed.

Gate 0's eSign entitlement transcript is committed at docs/fixtures/esign-probe-aug18.txt, and the Nutrient 403 we hit before the extraction product key landed is kept at nutrient-extraction-403.json as the entitlement record rather than deleted.

Progress

• safe-write-mcp-core@0.4.0 is published on npm and consumed here by version — not vendored, not a fork.
• Three upstream issues filed against our own core, all three fixed (#18/#19 the payload leak, #20 the missing bearer token) rather than patched around downstream, so the other two servers on the same kernel inherit every fix.
• The crash-safety redesign shipped and has been demoed live — consume() split into beginExecute() / confirmExecuted() / confirmFailed(), with a durable streamed-replay journal, and a real crash-and-recover run against the live eSign API produced a real SHARED folder.
• The audit trail is a hash-chained JSONL file. Every lifecycle event from both irreversible stages is appended with prevHash + sha256, fsync'd per line, and re-verified by streaming — tamper a record and verification names the line. Crash debris (a torn final write) is truncated on recovery, never chained over.
• Nutrient redaction is wired into the single pipeline and verified, not staged as a preview: /build applies the targets, then /extraction/parse reads the result back and confirms each value is actually gone before the plan reaches the gate.
• 283 tests, 48 suites, pass in CI — no live API calls — across the eSign adapter, extraction routing, redaction, the staged cache, and the audit sink.
• Every live finding is committed as a fixture, including the failures and the wrong-endpoint probe that preceded the right one.

Known gaps

Things we would want a reviewer to know without having to find them.

• The thresholds are not calibrated. All are marked calibrated: false and a test enforces that. They over-refer on purpose until there's a representative sample per document type — the recognition floor was raised once already, on Sep 3, after a live re-run auto-approved two wrong dollar amounts the previous floor had caught two weeks earlier.
• Redaction targets are a fixed list, not a detector. The default set covers email, North American phone, and a VIN regex, because those are what the demo invoice carries and what was actually probed to match. A passport number or an IBAN would pass through untouched, and verification would report success — it confirms the values it was told to remove are gone, not that the document is free of PII.
• One approval is enough. There's no N-of-M quorum — a single click authorizes the send. Building it needs upstream changes to safe-write-mcp-core (approvals as a recorded set, per-approver identity instead of a shared token), not a local patch; a shallow local version would look like multi-party approval while being satisfiable by one person clicking Approve twice, which is worse than leaving it cut.
• Redaction cannot be reconciled after a crash. The eSign side asks the gateway a real question — DRAFT or SHARED — and gets a real answer. The /build endpoint has no job ID and no server-side state to ask about, so reconcile returns unknown honestly, and a plan interrupted mid-apply stays visibly stuck for a human.
• The outgoing document carries a trial watermark. The Nutrient free trial stamps "For Evaluation Purposes Only" across every document /build returns — a licensing artifact, not a pipeline behavior, but it's on the redacted PDF that reaches the gate and the recipient.
• Verification reads the document once. It confirms the target values are absent from /extraction/parse output. A value rendered as an image, or split across text runs the parser rejoins differently, could evade both the redactor and the check.