@osolmaz/pi-workflows 0.9.1 → 0.11.0

package/docs/HUMAN_DECISIONS.md

@@ -0,0 +1,371 @@
+# Human decisions
+
+Pi Workflows needs a reusable way to stop at a proposal and wait for a person. The same decision must appear in Pi and Telegram, and either channel must be able to continue the run. Workflows must be able to offer plain choices, choices that collect text, and choices that route back to planning.
+
+This document defines that behavior. The implementation is tracked in the [human decision gates plan](plans/2026-08-19-human-decision-gates-plan.md).
+
+The [human decision presentation contract](HUMAN_DECISION_PRESENTATIONS.md)
+separates canonical subject data from the complete readable message shown in Pi
+and Telegram. Its [implementation plan](plans/2026-08-19-human-decision-presentations-plan.md)
+preserves v1 records without rewriting them.
+
+## Goals
+
+A workflow author can:
+
+- add a typed human decision without writing channel code;
+- route every choice exhaustively;
+- collect exact text with a choice such as `replan`;
+- address a logical audience instead of a Telegram chat or Pi session;
+- reuse a standard plan approval workflow; and
+- rely on one accepted answer and one continuation after a crash or concurrent reply.
+
+The feature uses the existing checkpoint execution primitive. It does not add another engine node type.
+
+## Authoring API
+
+`humanDecision()` is the human counterpart to the existing model-driven `decision()` helper. It returns a checkpoint definition with a typed request and response contract.
+
+```typescript
+import {
+  choice,
+  defineHumanChoices,
+  humanDecision,
+  humanDecisionEdge,
+  textInput,
+} from "@osolmaz/pi-workflows";
+
+const planChoices = defineHumanChoices({
+  continue: choice({ label: "Yes, continue" }),
+  stop: choice({ label: "No, stop" }),
+  replan: choice({
+    label: "Replan",
+    input: textInput({
+      name: "instructions",
+      prompt: "What should change?",
+      minLength: 1,
+      maxLength: 4_000,
+    }),
+  }),
+});
+
+export default defineWorkflow({
+  name: "approve-example",
+  startAt: "propose",
+  nodes: {
+    propose: agent({
+      prompt: "Prepare a proposal.",
+      expectedOutput: '{ "summary": "text", "plan": {} }',
+    }),
+    approve: humanDecision({
+      audience: "operator",
+      choices: planChoices,
+      request: ({ outputs }) => ({
+        title: "Approve the implementation plan",
+        subject: outputs.propose,
+        presentation: {
+          schema: "pi-workflows.decision-presentation.v1",
+          summary: "Review the implementation plan.",
+          blocks: [
+            { kind: "section", title: "Changes" },
+            { kind: "paragraph", text: "Implement the proposed changes." },
+          ],
+        },
+      }),
+    }),
+    implement: agent({ prompt: "Implement the approved proposal." }),
+    revise: agent({
+      prompt: ({ outputs }) => `Revise the plan: ${JSON.stringify(outputs.approve)}`,
+    }),
+    stopped: compute({ run: () => ({ status: "stopped" }) }),
+  },
+  edges: [
+    { from: "propose", to: "approve" },
+    humanDecisionEdge({
+      from: "approve",
+      choices: planChoices,
+      cases: {
+        continue: "implement",
+        stop: "stopped",
+        replan: "revise",
+      },
+    }),
+    { from: "revise", to: "approve" },
+  ],
+});
+```
+
+The accepted result is a discriminated union:
+
+```typescript
+type PlanDecision =
+  | { choice: "continue" }
+  | { choice: "stop" }
+  | { choice: "replan"; input: { instructions: string } };
+```
+
+`humanDecisionEdge()` requires one destination for every choice. A missing or extra case is a TypeScript error. Runtime validation applies the same choice and input contract before an answer can win.
+
+## Checkpoint behavior
+
+A human decision still has `nodeType: "checkpoint"`. The helper adds a human decision contract to that checkpoint.
+
+When the engine reaches the node, it:
+
+1. evaluates and validates the decision request;
+2. computes a canonical request digest from the subject, choices, audience, run, node, and attempt;
+3. writes an immutable decision request linked to the waiting run;
+4. asks the configured channels to deliver it; and
+5. parks the run in `waiting` state.
+
+When a valid answer is accepted, the continuation keeps the workflow's original input. The human answer becomes the checkpoint node's output in the continuation. Existing checkpoints keep their current behavior, where `/workflow answer` supplies the continuation input.
+
+This distinction preserves old workflow definitions and run bundles.
+
+## Request and response contracts
+
+A new decision request contains:
+
+- a decision ID;
+- the waiting run, node, and attempt IDs;
+- a short title;
+- a canonical structured subject;
+- a normalized human-readable presentation;
+- separate subject and presentation digests;
+- a positive decision revision;
+- the logical audience;
+- the complete choice contract;
+- the canonical request digest;
+- an optional expiry rule; and
+- the creation time.
+
+The presentation is an explicit display allowlist. A channel does not receive the subject and cannot infer operator text from it. The request digest binds the subject, visible presentation, title, revision, choices, and input prompts. Each choice has a stable ID and may have no input or one validated text input contract.
+
+The former `body` form remains available for existing workflow definitions. It creates a v1 request and uses a deterministic readable compatibility formatter. Oversized historical bodies receive a bounded readable prefix and an explicit omission notice with the full body digest and size. V1 request bytes and digests do not change.
+
+A submitted response contains:
+
+- the decision ID and request digest;
+- the selected choice;
+- the validated input, when required;
+- the channel and verified actor;
+- a channel event ID;
+- an idempotency key; and
+- the receipt time.
+
+A stale request digest, unknown choice, malformed input, unapproved actor, or model-originated answer is rejected before acceptance.
+
+## Human answer boundary
+
+The model-facing `workflow` tool cannot satisfy a human decision. Its `answer` action remains available for ordinary checkpoints, but returns an error when the waiting node requires a verified human channel.
+
+The accepted human sources are:
+
+- the Pi interactive decision view; and
+- a configured external decision channel such as Telegram.
+
+The host assigns the source. A workflow or model cannot claim that an answer came from a person. Pi non-interactive modes can wait for Telegram, but they cannot manufacture a Pi UI answer.
+
+## Audiences and channel profiles
+
+Workflows address a logical audience:
+
+```typescript
+humanDecision({ audience: "operator", ... });
+```
+
+Private configuration maps the audience to channels:
+
+```json
+{
+  "schema": "pi-workflows.channels.v1",
+  "audiences": {
+    "operator": {
+      "channels": ["pi", "telegram:default"],
+      "accept": "first-valid-answer"
+    }
+  },
+  "telegramProfiles": {
+    "default": {
+      "credential": "telegram-default",
+      "allowedUserIds": ["<telegram-user-id>"],
+      "allowedChatIds": ["<telegram-chat-id>"]
+    }
+  }
+}
+```
+
+The workflow never receives a bot token, user ID, chat ID, Telegram message ID, or Pi session detail. Channel profiles are private host configuration and are excluded from run presentation.
+
+Pi Workflows keeps credential references in a separate private file. A Telegram credential points to an existing absolute mode-`0600` token file:
+
+```json
+{
+  "schema": "pi-workflows.credentials.v1",
+  "telegram": {
+    "telegram-default": {
+      "tokenFile": "<absolute-mode-0600-token-file>"
+    }
+  }
+}
+```
+
+Run `/workflow-channel setup` in Pi TUI to verify and install a profile, `/workflow-channel status` to inspect whether profiles are active, and `/workflow-channel reload` after a private configuration change. Setup asks for the token file path, not the token. It updates mode-`0600` private files and does not copy the token. Token values never enter source files, workflow inputs, run bundles, logs, child environments, or model-visible tool results.
+
+The same Unix account can read a local credential file. This design prevents accidental propagation, not a hostile same-account process. A separately owned connector can implement the same channel interface later if stronger isolation becomes necessary.
+
+## Channel interface
+
+All decision channels implement one interface:
+
+```typescript
+interface HumanDecisionChannel {
+  readonly id: string;
+  start(): Promise<void>;
+  deliver(request: HumanDecisionRequest): Promise<DecisionDeliveryResult>;
+  settle(decision: AcceptedHumanDecision | HumanDecisionCancellation): Promise<void>;
+  stop(): Promise<void>;
+}
+```
+
+The context exposes a narrow answer submission function. It does not expose the workflow engine, arbitrary run mutation, or another channel's credentials.
+
+Channel delivery is independent from workflow routing. A failed Telegram delivery leaves the decision available in Pi. Audience policy decides whether one successful channel is enough or whether all configured channels are required before the request is considered delivered.
+
+### Pi channel
+
+The Pi channel uses documented extension UI APIs. It shows the request, lists the choices, and opens a text editor when the selected choice requires input. The host records the interactive session as the answer source.
+
+The waiting workflow remains durable before the UI opens. Closing Pi or cancelling the view cannot lose the checkpoint. A later Pi session can reopen pending decisions.
+
+### Telegram channel
+
+The Telegram channel uses the Bot API and private profile configuration. It sends one decision message with inline buttons.
+
+A choice without input submits from its button. A text choice such as `replan` works as follows:
+
+1. the operator presses **Replan**;
+2. the bot sends a `ForceReply` prompt tied to that decision and choice;
+3. the operator replies to that exact prompt;
+4. the channel verifies the numeric user ID, chat ID, reply message ID, decision ID, and request digest; and
+5. the exact received text becomes `input.instructions`.
+
+The adapter does not infer a choice from ordinary chat text. Callback payloads contain short opaque IDs because Telegram limits callback data. The private channel store maps each opaque ID to the full decision request.
+
+Telegram permits one long-polling consumer for a bot profile. Active Pi processes use a shared lease so one process owns polling and the others use the same private channel state. The lease owner can accept a verified reply, but only the Pi session that owns the waiting run creates its continuation. Active sessions inspect the durable accepted-answer fence and recover their own continuation. If no Pi process is running, Telegram delivery and reply collection resume when Pi starts again. Running an always-on service is outside this design.
+
+The Bot API does not provide an idempotency key for `sendMessage`. Pi Workflows therefore writes a delivery intent before sending and never blindly retries an ambiguous send. A timed-out send is recorded as `unknown`; Pi remains available and an operator can request another delivery. This avoids automatic duplicate messages while keeping decision acceptance exactly once.
+
+## Durable decision records
+
+Decision records live next to workflow run bundles under the Pi Workflows state root. They are additive and linked by run ID. A decision directory contains immutable records for:
+
+- the request;
+- channel delivery intents and results;
+- answer attempts;
+- the atomic accepted-or-cancelled resolution;
+- the accepted answer or cancellation detail;
+- channel settlement results; and
+- the continuation request and result.
+
+The resolution record uses a no-replace create. The first valid acceptance, cancellation, or expiry writer wins. Acceptance then materializes the matching accepted-answer detail. Cancellation or expiry materializes cancellation detail. A retry with the same response and idempotency key adopts the existing answer. A conflicting answer receives an `already decided` result.
+
+The continuation run ID is derived from the accepted decision ID. Recovery adopts an existing matching continuation or creates it once. A crash after answer acceptance cannot run the next workflow step twice. The continuation run carries a redacted receipt with the decision ID, request digest, gate node ID, choice, acceptance time, and answer digest. Actor, channel, event, and idempotency provenance stays only in the private decision records and never enters the run bundle or model context.
+
+SQLite may index pending decisions and channel leases, but immutable decision files remain the source of truth. The index is disposable and rebuildable.
+
+## Planning workflow composition
+
+Pi Workflows keeps solution choice, documentation, and implementation in separate built-ins:
+
+- `autoplan` chooses a solution or revises one after new evidence.
+- `autodoc` records an already selected solution in the canonical specification and implementation plan. It does not choose a solution or implement it.
+- `autoimplement` executes a clear existing plan.
+
+`autodoc` runs by itself and as an included workflow. It returns a documented-plan record with the plan, plan digest, document paths, document digests, and check results. If the canonical documents already describe the selected plan, it adopts them without rewriting files.
+
+`autoimplement` first finds the clear existing plan in its input, the conversation, or referenced canonical documents. It blocks when no clear plan exists. A caller can bypass discovery and autodoc only by supplying both the explicit plan and a `documentation` receipt whose plan digest matches it. A plan without that current-document evidence enters autodoc so the canonical documents are inspected and adopted or updated. The absence of a structured `plan` input never authorizes `autoplan`.
+
+If later implementation, verification, review, comments, or CI evidence invalidates the plan, autoimplement runs `autoplan`, sends the revised plan through `autodoc`, and then resumes implementation. An optional approval policy inserts `plan-approval` after the revised documentation.
+
+## Reusable plan approval workflow
+
+Pi Workflows ships a typed `plan-approval` workflow built on `humanDecision()`. Its input contains the documented plan, plan digest, audience, and display summary. It has three named exits:
+
+- `continue`, with the approval receipt;
+- `stop`, with the stop receipt; and
+- `replan`, with the exact instructions and receipt.
+
+A parent can include it without copying prompts or channel handling:
+
+```typescript
+includes: {
+  approval: includeWorkflow(planApproval, {
+    input: ({ outputs }) => ({
+      plan: outputs.devise.plan,
+      planDigest: outputs.devise.planDigest,
+      audience: "operator",
+    }),
+  }),
+},
+```
+
+A `replan` exit returns to `autoplan` with the previous plan and the exact human instructions as new evidence. The revised plan passes through `autodoc`, receives a new digest, and enters a new approval decision. Step limits bound repeated replanning.
+
+Monitor repair composes `autoplan`, `autodoc`, optional `plan-approval`, `autoimplement`, and a fresh target check. Autoimplement can mount the same approval workflow after evidence-driven redesign. Existing behavior stays unchanged when no approval policy is present.
+
+## Recovery and cancellation
+
+Recovery follows these rules:
+
+- missing channel deliveries can be attempted;
+- confirmed deliveries are adopted;
+- Telegram records intent and confirmed evidence for every multipart message;
+- Telegram resumes only when the next part is provably unsent;
+- ambiguous Telegram sends are not retried automatically;
+- duplicate channel updates are harmless;
+- stale responses are rejected;
+- one accepted response creates one continuation;
+- the winning channel dismisses any pending Pi dialog;
+- confirmed channel settlement is adopted without another remote call;
+- failed channel settlement has a bounded retry count and cannot create an unbounded record loop; and
+- cancellation resolves the owned waiting decision from durable state, even after restart, closes pending views, and prevents a later answer from continuing the run.
+
+A decision with no available channel remains waiting and reports the configuration problem. It does not silently continue or choose a default.
+
+## Compatibility
+
+Ordinary checkpoints, their continuation input behavior, and existing run bundles remain unchanged. V2 requests, accepted records, receipts, resolutions, and multipart delivery records are additive. Older viewers ignore them. Updated viewers label a human decision as a checkpoint, show the readable presentation and its fingerprint, and keep the canonical subject separate. Private channel configuration and transport identifiers remain hidden.
+
+The engine remains independent from Pi and Telegram. Core code owns decision contracts, validation, durable acceptance, and continuation. The Pi extension owns UI and channel lifecycle. The Telegram adapter owns Bot API translation. Workflow definitions own only the question, choices, audience, and routes.
+
+## Contract impact
+
+- **Session state:** Pi records normal workflow messages and interactive decision results.
+- **Other persistent data:** additive decision records, a rebuildable private channel index, and private channel configuration.
+- **Pi internals:** none.
+- **Public Pi API:** documented extension lifecycle and UI methods only.
+- **Public Pi Workflows API:** typed human choices, `humanDecision()`, `humanDecisionEdge()`, the channel interface, and the `plan-approval` workflow.
+
+## Verification requirements
+
+The implementation must test:
+
+- compile-time exhaustive choice routing;
+- choices with no input and choices with exact text input;
+- runtime choice and input validation;
+- legacy checkpoint continuation;
+- model-tool answer rejection;
+- Pi interactive answers;
+- Telegram callbacks and reply binding with a fake Bot API;
+- unauthorized users and chats;
+- stale request digests;
+- concurrent Pi and Telegram answers;
+- identical and conflicting retries;
+- crashes before and after answer acceptance and continuation creation;
+- ambiguous Telegram sends;
+- long-poll lease handoff between Pi processes;
+- decision cancellation and expiry;
+- included `plan-approval` routes and bounded replan loops;
+- viewer redaction; and
+- real Pi execution without real Telegram credentials or network calls.

package/docs/HUMAN_DECISION_PRESENTATIONS.md

@@ -0,0 +1,323 @@
+# Human decision presentations
+
+This contract is implemented. New human decision requests separate their canonical
+subject from the complete readable message shown to an operator. Historical requests
+that use `body` remain compatible through a deterministic readable formatter.
+The implementation plan is in
+[the human decision presentations plan](plans/2026-08-19-human-decision-presentations-plan.md).
+
+A human decision contains machine data and a separate message for the operator.
+Pi Workflows stores and validates the machine data. Pi and Telegram render only
+the operator message, and future channels follow the same rule.
+
+## Minimal example
+
+```typescript
+approve: humanDecision({
+  audience: "operator",
+  choices,
+  request: () => ({
+    title: "Approve the implementation plan",
+    subject: {
+      task: "Add readable human decisions",
+      plan: selectedPlan,
+      planDigest,
+      revision: 1,
+    },
+    presentation: {
+      schema: "pi-workflows.decision-presentation.v1",
+      summary: "Replace raw JSON decisions with readable messages.",
+      blocks: [
+        { kind: "section", title: "Changes" },
+        {
+          kind: "bullets",
+          items: [
+            "Keep structured data as the durable source.",
+            "Show the same readable message in Pi and Telegram.",
+          ],
+        },
+        {
+          kind: "fields",
+          items: [{ label: "Plan revision", value: "1" }],
+        },
+      ],
+    },
+  }),
+});
+```
+
+The operator sees the summary and sections along with lists and fields. The operator does
+not see `subject` unless the workflow explicitly copies selected text into
+`presentation`.
+
+## Request contract
+
+A new request uses `pi-workflows.human-decision-request.v2`. It contains:
+
+| Field                | Required | Meaning                                         |
+| -------------------- | -------- | ----------------------------------------------- |
+| `title`              | Yes      | Short decision title shown by every channel.    |
+| `subject`            | Yes      | Canonical JSON data used by the workflow.       |
+| `presentation`       | Yes      | Human-readable content defined below.           |
+| `audience`           | Yes      | Named audience resolved by the host.            |
+| `choices`            | Yes      | Typed choices and optional input contracts.     |
+| `revision`           | Yes      | Positive decision revision.                     |
+| `subjectDigest`      | Yes      | SHA-256 digest of the canonical subject.        |
+| `presentationDigest` | Yes      | SHA-256 digest of the normalized presentation.  |
+| `requestDigest`      | Yes      | SHA-256 digest that binds the complete request. |
+
+The runtime adds the usual run binding and lifecycle fields as it does for
+current decisions.
+
+A request that supplies `subject` without `presentation` is invalid. A channel
+must not derive a presentation from `subject`.
+
+## Presentation contract
+
+`pi-workflows.decision-presentation.v1` is a small ordered document:
+
+```typescript
+type DecisionPresentation = {
+  schema: "pi-workflows.decision-presentation.v1";
+  summary: string;
+  blocks: DecisionPresentationBlock[];
+};
+```
+
+`summary` is required and non-empty. Every channel shows it first. `blocks` can be empty. Block
+order is meaningful and every channel preserves it.
+
+### Blocks
+
+The first version supports five flat block types.
+
+#### Paragraph
+
+```json
+{ "kind": "paragraph", "text": "This change affects active workflows." }
+```
+
+#### Section
+
+```json
+{ "kind": "section", "title": "Verification" }
+```
+
+A section labels the blocks that follow it until the next section. Sections do
+not contain nested blocks.
+
+#### Bullets
+
+```json
+{
+  "kind": "bullets",
+  "items": ["Run the unit tests.", "Run the real-Pi test."]
+}
+```
+
+#### Fields
+
+```json
+{
+  "kind": "fields",
+  "items": [
+    { "label": "Repository", "value": "pi-workflows" },
+    { "label": "Action", "value": "Update the decision contract" }
+  ]
+}
+```
+
+#### Preformatted text
+
+```json
+{
+  "kind": "preformatted",
+  "text": "npm run check\nnpm run test:e2e"
+}
+```
+
+Preformatted text preserves spacing and line breaks. It does not permit HTML,
+Markdown, terminal escape sequences, or executable channel instructions.
+
+## Validation and normalization
+
+The authoring API validates the presentation before it creates a pending
+request.
+
+- Unknown fields and unknown block kinds are invalid.
+- Display values are strings. Arbitrary nested objects are invalid.
+- The summary, section titles, labels, bullet items, and field values must not
+  be empty after whitespace checks.
+- The normalizer converts CRLF and CR line endings to LF.
+- The normalizer preserves block order, item order, Unicode text, and other
+  spacing.
+- Terminal control characters are invalid. Paragraph and preformatted text can
+  contain LF and tab. Titles and labels plus bullet items cannot contain control
+  characters.
+- The complete normalized presentation is limited to 64,000 UTF-16 code units.
+- A presentation can contain at most 256 blocks.
+- One bullets or fields block can contain at most 256 items.
+- One string can contain at most 16,000 UTF-16 code units.
+- A renderer can produce at most 20 transport parts for one recipient.
+
+If a presentation exceeds a limit, request creation fails with the exact limit
+and observed value. The runtime does not create a pending request and does not
+send a partial message.
+
+## Digests
+
+The runtime uses canonical JSON with a trailing newline, as defined by the run
+bundle contract.
+
+```text
+subjectDigest = sha256(canonicalJson(subject))
+presentationDigest = sha256(canonicalJson(normalizedPresentation))
+requestDigest = sha256(canonicalJson(requestBasis))
+```
+
+`requestBasis` contains the request schema and run binding. It also contains the
+audience, title, subject, normalized presentation, choices, typed input
+contracts, revision and optional expiry. It does not contain the three digest
+fields or the derived decision ID.
+
+An answer must match the exact request revision and request digest. A change to
+only the subject, visible text, choice label, or input prompt makes an older
+answer stale.
+
+Channels can show a short prefix of `presentationDigest` so an operator can
+compare the decision in Pi and Telegram. The viewer shows the same fingerprint.
+The complete digest remains in the durable request and accepted answer evidence.
+
+## Channel rendering
+
+The workflow creates one presentation. It does not contain channel names,
+Telegram markup, terminal colors, message limits, buttons, or callback data.
+
+Each channel can change spacing and wrapping as well as styling, navigation, or
+controls. It must preserve the title and summary together with block order and
+contents. It must also preserve every choice and input prompt. A channel must
+not omit or reinterpret approval-relevant content.
+
+### Telegram
+
+Telegram uses plain text without a parse mode. Text that resembles HTML,
+Markdown, a command, or a mention remains inert text.
+
+The renderer:
+
+1. Renders the complete normalized presentation.
+2. Splits at block and paragraph boundaries before splitting a line.
+3. Splits a long line at Unicode-safe boundaries only when required.
+4. Reserves space for `Part n/N` and a short presentation fingerprint.
+5. Keeps every Telegram message below the Telegram limit.
+6. Adds choice buttons only to the final part.
+7. Stores durable part indexes and content digests.
+8. Keeps chat and message IDs only in the private channel projection.
+
+The renderer never adds an ellipsis in place of omitted decision content.
+
+The channel records intent before sending. It records each part after an
+unambiguous response. If a send result is ambiguous, it marks delivery unknown
+and does not retry that part or later parts automatically. Another configured
+channel can still answer the decision.
+
+### Pi
+
+Pi uses the documented extension TUI API. A custom decision component shows the
+complete presentation and fingerprint together with the choices and optional
+text prompt. It wraps and scrolls while responding to resize, theme, cancellation,
+and `AbortSignal` events.
+
+When Telegram or another channel accepts the decision, the signal closes the Pi
+dialog. Pi Workflows does not modify Pi core or use undocumented TUI state.
+
+### Other channels
+
+A new channel consumes the normalized presentation and typed interaction
+contract. It must pass the same conformance tests. It cannot access the subject
+for display.
+
+## Plan presentation
+
+Pi Workflows provides a reusable plan presenter for built-in workflows. It
+derives a presentation from the same typed plan stored as the subject.
+
+The presenter uses these sections when data exists:
+
+1. Goal
+2. Proposed changes
+3. Verification
+4. Boundaries
+5. Risks and mitigations
+6. Evidence
+
+It omits absent sections. It never serializes the plan object. `plan-approval`,
+`monitor`, `autoplan`, `autodoc`, and `autoimplement` reuse this presenter where
+they ask a person to approve a plan.
+
+## Compatibility
+
+Current v1 requests remain immutable.
+
+- A v1 string body becomes one readable paragraph at delivery time.
+- A v1 object body uses a deterministic compatibility formatter. It converts
+  stable key order into readable labels and fields with sections and lists.
+- An oversized v1 body remains answerable. The formatter keeps a bounded readable
+  prefix and adds an explicit omission notice with the full body digest and size.
+  It never hides omitted content behind an ellipsis.
+- The compatibility formatter reads only the historical `body`, which was
+  already the display field. It never reads a new structured subject.
+- V1 request bytes and digests do not change.
+- Pending and accepted v1 decisions continue to use v1 validation and digest
+  rules.
+- New preferred authoring emits v2. The existing body form remains a deprecated
+  compatibility overload until a separate removal is approved.
+
+No migration rewrites run bundles or decision records.
+
+## Privacy and security
+
+The presentation is an explicit display allowlist. Data does not become visible
+because it exists in the subject.
+
+Channel adapters do not receive the subject. Durable public records do not
+contain Telegram chat IDs, message IDs, bot tokens, credential profile values,
+or private audience configuration. The private channel projection retains only
+the transport identifiers required for recovery and settlement.
+
+Workflow authors remain responsible for not putting a secret in the explicit
+presentation. Renderers treat all text as untrusted and inert.
+
+## Failure behavior
+
+- Invalid or excessive content fails before a request becomes pending.
+- A renderer that cannot represent every block fails closed.
+- Confirmed multipart delivery requires a receipt for every part.
+- Ambiguous Telegram delivery remains unknown and is not retried blindly.
+- A channel failure does not choose a default answer.
+- Rules for the first valid answer and stale answers remain unchanged, as do
+  cancellation and settlement rules together with exactly-once continuation.
+
+## Verification
+
+Implementation must pass:
+
+```bash
+npm run check
+npm run test:e2e
+cargo test --manifest-path tui/Cargo.toml
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+npx -y @simpledoc/simpledoc check
+```
+
+Tests must cover schema validation, canonical digests, readable legacy bodies,
+plan rendering, Pi and Telegram content parity, unsafe text, Unicode, multipart
+delivery, ambiguous sends, recovery, stale answers, viewer output, and proof
+that no channel serializes a subject as JSON.
+
+## Boundaries
+
+This contract does not add a new workflow node, template language, rich text
+framework, translation service, delivery relay, Telegram resource, credential,
+or Pi core change.