@osolmaz/pi-workflows 0.12.0 → 0.13.0

package/docs/CONTROLLERS.md

@@ -159,11 +159,11 @@ Mutation policy stays in deterministic effect drivers. Agent workflows return fi
 
 ## Child workflows
 
-`ctx.workflows.ensure()` creates or finds a workflow run by a stable request key and input fingerprint. Repeated reconciliations find the same active or completed request. A changed input must use a new key. The controller store reserves and saves each attempt's run ID before the scheduler starts it, so restart recovery can find the bundle.
+`ctx.workflows.ensure()` creates or finds a workflow run by a stable request key and input fingerprint. Repeated reconciliations find the same active or completed request. A changed input must use a new key. An asynchronous child completion validates the reserved request and run IDs through a separate scheduler-completion command; it never reuses the controller claim that launched the child. The controller transaction reserves and saves each attempt's run ID before the scheduler starts it, so recovery can find the run row.
 
-A child run is one immutable attempt. Its existing run bundle remains the execution record. The parent resource points to the current run, and workflow completion enqueues the parent key. A host restart can record an abandoned attempt and create another attempt for the same stable request.
+A child run is one immutable attempt. Its existing SQLite run state remains the execution record. The parent resource points to the current run, and workflow completion enqueues the parent key. A host restart can record an abandoned attempt and create another attempt for the same stable request.
 
-The workflow scheduler records an abandoned running bundle as `failed` with a final `run_interrupted` trace event. The controller store treats that child attempt as `interrupted`, so the next reconciliation starts another immutable attempt. Compute work can run again, while consequential external actions belong in the effect API so recovery observes them before retrying.
+The workflow scheduler records an abandoned running run as `failed` with a final `run_interrupted` event. The controller store treats that child attempt as `interrupted`, so the next reconciliation starts another immutable attempt. Compute work can run again, while consequential external actions belong in the effect API so recovery observes them before retrying.
 
 ## Deletion and cleanup
 
@@ -183,7 +183,7 @@ The Pi extension starts local workers during `session_start` and closes them dur
 
 Every reconciliation emits structured records with the controller name, resource key, generation, reconcile ID, outcome and duration, plus the requeue reason. Effect state changes and child workflow links are also recorded. Logs and viewer projections remain secondary to the resource and effect stores.
 
-`pi-workflows controllers` lists resources and their current readiness condition. `pi-workflows controller <controller> <key>` prints one resource together with its effects, child workflows, and recent events. Existing run views continue to read immutable bundles.
+`pi-workflows controllers` lists resources and their current readiness condition. `pi-workflows controller <controller> <key>` prints one resource together with its effects, child workflows, and recent events. Run views read the same database through query-only connections.
 
 ## Safety rules
 
@@ -196,7 +196,7 @@ A production controller must follow these rules:
 - Reconcile again after each consequential external effect.
 - Keep model output separate from mutation authority.
 - Bound worker counts and retry rates. Also bound timeouts and stored payload sizes.
-- Redact credentials and private provider responses from logs and run bundles.
+- Redact credentials and private provider responses from logs and SQLite runs.
 
 ## Package and Pi integration
 
@@ -204,11 +204,13 @@ The controller API is exported from `@osolmaz/pi-workflows/controllers`. Control
 
 The implementation uses documented Pi extension APIs only. Commands and tools use `registerCommand` and `registerTool`. Session lifecycle uses `session_start` and `session_shutdown`. Workflow prompts use `sendUserMessage`, while status uses `setWidget` and `setStatus`.
 
-The `/controller` command lists and inspects resources, applies specs, requests reconciliation or deletion, and starts or stops local workers. Stopping workers records an active child as interrupted, so starting workers again can create another attempt. Project stores live under `~/.pi/agent/workflows/controllers/projects/<scope>/controller.sqlite`. The scope is a hash of the canonical project directory. `PI_WORKFLOWS_CONTROLLER_DIR` overrides the controller root while preserving project scopes.
+The `/controller` command lists and inspects resources, applies specs, requests reconciliation or deletion, and starts or stops local workers. Stopping workers records an active child as interrupted, so a later worker can create another attempt.
 
-The same store also backs the standalone host (`pi-workflows host`). The host reconciles controllers without a Pi session and claims parked interactive runs from the `workflow_run_queue` table. Conversation children execute in headless `pi --mode rpc` sessions. A Pi session and the host can share one store safely because claims and compare-and-swap writes arbitrate, but run only one set of controller workers at a time to avoid competing work. The host takes an advisory lock against other hosts; the embedded runner in Pi does not take it.
+Controller resources use the canonical [SQLite state](SQLITE_STATE.md) database. `projects` separates repository-local resources by canonical project path. Controller claims use the shared lease generation, token, expiry, and expected resource revision. Effects and child workflows use the shared transactional outbox and deterministic receipts.
 
-Normal workflow prompts, tool calls, and replies remain part of the Pi session. Controller resources, queue rows, and effects live in the controller store. No Pi internal type, private API, or persistent Pi schema changes.
+The same database backs the standalone host (`pi-workflows host`). The host reconciles controllers without a Pi session and claims parked interactive runs from `run_queue`. Conversation children execute in headless `pi --mode rpc` sessions. A Pi session and the host can share the database safely because SQLite transactions and durable leases arbitrate ownership, but only one owner can mutate a resource at a time.
+
+Normal workflow prompts, tool calls, and replies remain part of the Pi session. No Pi internal type, private API, or persistent Pi schema changes.
 
 ## Exclusions
 

package/docs/DEFERRED_TURNS.md

@@ -246,7 +246,7 @@ Store leases prevent concurrent processes from sending the same resolution. Bran
 
 ## Claim transfer
 
-Claim loss stops the old runner's work and all fenced run-bundle writes. The intent stays pending and fallback-ineligible while another runner can resume the run.
+Claim loss stops the old runner's work and all fenced SQLite writes. The intent stays pending and fallback-ineligible while another runner can resume the run.
 
 The new runner's next workflow prompt can resolve the intent. If durable state later proves a terminal outcome with no natural successor, terminal handling makes the intent eligible for fallback to its target session.
 
@@ -281,7 +281,7 @@ This is an alpha hard cutover.
 - Add `workflow_turn_intents` to the existing database.
 - Remove the launch-trigger runtime path.
 - Add no v2 schema, compatibility reader, dual write, alias, or feature flag.
-- Keep historical terminal run bundles readable because their contract does not change.
+- Keep historical terminal SQLite runs readable because their contract does not change.
 
 ## Conformance
 

package/docs/DESIGN_PHILOSOPHY.md

@@ -16,7 +16,7 @@ Shared behavior should usually start as a data format or pure helper used by a w
 
 ## Explicit behavior
 
-The graph should show what runs and where it can go. Agent results should be structured and validated. Commands and other side effects should be declared by the workflow author.
+The graph should show what runs and where it can go. Use structured, validated agent results when the graph must inspect fields or choose a route. Use a declared assistant-message result when exact visible text belongs inside the graph. Commands and other side effects should be declared by the workflow author.
 
 Avoid hidden polling, implicit retries, automatic command generation, and state changes that the graph cannot explain.
 
@@ -30,7 +30,9 @@ A notification should not start a model turn unless the workflow explicitly requ
 
 Runs should survive interruption and remain safe to resume. Save the run input and every accepted output. Save attempts and events along with enough evidence of side effects for replay and diagnosis.
 
-The trace is the record of what happened. Viewers and state projections should derive their answers from that record instead of creating a second source of truth.
+Immutable SQLite events are the record of what happened. Domain rows are current projections written in the same transaction. Viewers derive their answers from those facts instead of creating another source of truth.
+
+Reading shared state never gives mutation authority. Every durable write checks its actor, expected resource revision, and current lease generation when ownership is required. Follow-up work uses deterministic effects and idempotent receipts so partial failure can converge safely.
 
 ## Boundaries
 

package/docs/HUMAN_DECISIONS.md

@@ -60,6 +60,10 @@ export default defineWorkflow({
     approve: humanDecision({
       audience: "operator",
       choices: planChoices,
+      onTimeout: {
+        afterMs: 10 * 60_000,
+        response: { choice: "continue" },
+      },
       request: ({ outputs }) => ({
         title: "Approve the implementation plan",
         subject: outputs.propose,
@@ -106,6 +110,8 @@ type PlanDecision =
 
 `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.
 
+`onTimeout` is optional. It supplies a positive duration and a response that satisfies the same choice contract. The request stores the resulting absolute deadline and validated response. When no human answer wins before the deadline, the decision recovery owner applies that response with `timeout` provenance. Omitting `onTimeout` keeps an indefinite wait. A request cannot combine `onTimeout` with a separate `expiresAt` value.
+
 ## Checkpoint behavior
 
 A human decision still has `nodeType: "checkpoint"`. The helper adds a human decision contract to that checkpoint.
@@ -118,9 +124,7 @@ When the engine reaches the node, it:
 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.
+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. Ordinary checkpoints keep their current behavior, where `/workflow answer` supplies the continuation input.
 
 ## Request and response contracts
 
@@ -136,12 +140,12 @@ A new decision request contains:
 - the logical audience;
 - the complete choice contract;
 - the canonical request digest;
-- an optional expiry rule; and
+- an optional absolute deadline and automatic response; 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 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, input prompts, deadline, and automatic response. 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.
+Human decisions use only `pi-workflows.human-decision-request.v1`. The former `body` request and all human-decision `v2` records are invalid. This is an alpha hard cutover: old waiting runs and decision state must be reset rather than migrated or reinterpreted.
 
 A submitted response contains:
 
@@ -210,7 +214,7 @@ pi-workflows keeps credential references in a separate private file. A Telegram
 }
 ```
 
-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.
+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, SQLite runs, 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.
 
@@ -250,29 +254,28 @@ A choice without input submits from its button. A text choice such as `replan` w
 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.
+The adapter does not infer a choice from ordinary chat text. Callback payloads contain short opaque IDs because Telegram limits callback data. Private local SQLite rows map each opaque ID to the validated decision presentation. Credentials remain outside the database.
 
-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.
+Telegram permits one long-polling consumer for a bot profile. Active Pi processes use the shared SQLite lease so one process owns polling and the others observe the same 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:
+Human decisions use the canonical [SQLite state](SQLITE_STATE.md) database:
 
-- 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.
+- `human_decisions` stores each immutable request;
+- `human_decision_submissions` records human, policy, channel, and control candidates;
+- `human_decision_resolutions` stores the one accepted-or-cancelled winner;
+- `continuations` links the parent and continuation runs;
+- `effects` records parent settlement, continuation, and presentation settlement work; and
+- channel tables store delivery and settlement receipts.
 
-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.
+A valid human answer, eligible timeout policy, explicit cancellation, or no-default expiry competes for the same resolution primary key. The winning transaction records the immutable resolution, audit event, and required effects together. A retry adopts the existing matching result. A conflicting or late answer receives the durable winner.
 
-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.
+A deadline with a validated default response is timeout-policy acceptance. It cannot become expiry cancellation. No-default expiry can cancel. Automatic policy and continuation creation require the current run owner's token and lease generation. A verified channel can submit a human candidate without gaining run ownership.
 
-SQLite may index pending decisions and channel leases, but immutable decision files remain the source of truth. The index is disposable and rebuildable.
+The continuation run ID is derived from the decision ID. The owner adopts an existing matching continuation or creates it once. The continuation record and redacted receipt carry the resolution provenance, decision ID, request digest, gate node ID, choice, acceptance time, and answer digest. Human actor, channel, event, and idempotency details remain private and do not enter model-visible status output.
 
 ## Planning workflow composition
 
@@ -286,33 +289,19 @@ pi-workflows keeps solution choice, documentation, and implementation in separat
 
 `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.
+If later implementation, verification, review, comments, or CI evidence invalidates the plan, Autoimplement enters the shared plan-change workflow. That workflow runs Autoplan, Autodoc, plan approval, and bounded exact-text replanning. Monitor uses the same workflow for each new repair plan and passes the selected plan into Autoimplement without a second decision.
 
 ## 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:
+pi-workflows ships a typed `plan-approval` workflow built on `humanDecision()`. Its policy has three modes:
 
-```typescript
-includes: {
-  approval: includeWorkflow(planApproval, {
-    input: ({ outputs }) => ({
-      plan: outputs.devise.plan,
-      planDigest: outputs.devise.planDigest,
-      audience: "operator",
-    }),
-  }),
-},
-```
+- `auto` asks the configured audience and continues after the configured deadline. It defaults to audience `operator` and 10 minutes.
+- `required` waits for an explicit human answer.
+- `skip` creates no human decision and continues immediately.
 
-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.
+The workflow has `continue`, `stop`, and exact-text `replan` exits. Continue reports `human`, `timeout`, or `skipped` provenance. Stop and replan always require a human answer.
 
-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.
+The internal plan-change workflow composes Autoplan, Autodoc, and plan approval once. It owns the replan count, plan digest, and positive revision. Autoimplement and Monitor include this workflow instead of copying approval routes. A plan supplied by the caller or already selected by Monitor bypasses another decision. Only a changed plan digest enters the gate.
 
 ## Recovery and cancellation
 
@@ -325,27 +314,27 @@ Recovery follows these rules:
 - 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;
+- one human or timeout response creates one continuation;
+- the winning human answer or timeout policy 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.
+A required decision with no available channel remains waiting and reports the configuration problem. An automatic decision does not need a channel to apply its saved response after the deadline. A skipped plan policy creates no decision.
 
 ## 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.
+This alpha change updates the current request, accepted-result, receipt, resolution, continuation, and snapshot contracts in place. Old active runs refuse resume through normal source and definition identity checks. There is no compatibility reader, migration, dual path, or new schema generation. Updated viewers label a human decision as a checkpoint, show its deadline and automatic action when present, 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.
+- **Other persistent data:** decision requests and resolutions can carry a deadline, automatic response, and resolution provenance in the existing decision store. The private channel index remains rebuildable.
 - **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.
+- **Public pi-workflows API:** typed human choices, `humanDecision().onTimeout`, `humanDecisionEdge()`, the channel interface, the plan approval policy, and the shared plan-change workflow.
 
 ## Verification requirements
 

package/docs/HUMAN_DECISION_PRESENTATIONS.md

@@ -1,8 +1,8 @@
 # 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.
+This contract is implemented. Human decision requests separate their canonical
+subject from the complete readable message shown to an operator. Human decisions use
+one v1 contract with no legacy body form or parallel schema version.
 The implementation plan is in
 [the human decision presentations plan](plans/2026-08-19-human-decision-presentations-plan.md).
 
@@ -52,7 +52,7 @@ not see `subject` unless the workflow explicitly copies selected text into
 
 ## Request contract
 
-A new request uses `pi-workflows.human-decision-request.v2`. It contains:
+A request uses `pi-workflows.human-decision-request.v1`. It contains:
 
 | Field                | Required | Meaning                                         |
 | -------------------- | -------- | ----------------------------------------------- |
@@ -255,25 +255,15 @@ 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
+## Alpha cutover
 
-Current v1 requests remain immutable.
+The human-decision request, accepted result, receipt, delivery, and resolution use one
+v1 schema family. The current structured subject and explicit presentation contract
+replaced the former body request and parallel v2 records in place.
 
-- 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.
+Old waiting runs and human-decision state are incompatible. The runtime fails with a
+reset instruction instead of reading, migrating, or silently reinterpreting them.
+There is no compatibility reader, dual path, alias, or migration.
 
 ## Privacy and security
 
@@ -311,10 +301,10 @@ 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,
+Tests must cover schema validation, canonical digests, structured-value formatting,
 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.
+delivery, ambiguous sends, recovery, stale answers, viewer output, incompatible-state
+failure, and proof that no channel serializes a subject as JSON.
 
 ## Boundaries