@osolmaz/pi-workflows 0.12.0 → 0.13.0

package/docs/SQLITE_STATE.md

@@ -0,0 +1,219 @@
+# SQLite state
+
+Pi Workflows stores all live durable state in one database:
+
+```text
+~/.pi/agent/workflows/state.sqlite
+```
+
+There is one database for the user installation. Project and run IDs separate data inside it. Workflow targets do not read or write this database.
+
+## Storage boundary
+
+The database stores:
+
+- workflow definitions, runs, events, node attempts, outputs, and updates
+- captured Pi session entries and events
+- run and controller queues, claims, retries, and continuations
+- human-decision requests, submissions, resolutions, and cancellations
+- controller resources, finalizers, effects, and child workflows
+- notifications and deferred turns
+- nonsecret channel cursors, inbox records, messages, and settlement receipts
+- canonical JSON, text, and large text values
+
+Credentials and raw secrets must not enter the database. Channel credential files stay in their existing private configuration directory.
+
+The implementation does not create live run directories, artifact files, decision directories, project databases, controller databases, or channel databases.
+
+## Database settings
+
+Every writer enables:
+
+```sql
+PRAGMA foreign_keys = ON;
+PRAGMA journal_mode = WAL;
+PRAGMA synchronous = FULL;
+PRAGMA busy_timeout = 5000;
+```
+
+The database also uses:
+
+- `STRICT` tables
+- application ID `0x50495746`
+- user version `1`
+- a bounded WAL checkpoint and journal size
+- directory mode `0700`
+- database and backup mode `0600`
+
+Read-only tools open the same file with SQLite read-only mode and `PRAGMA query_only = ON`.
+
+Opening code verifies the application ID, user version, schema metadata, compiled DDL digest, and exact SQLite schema shape. An incompatible database fails with an instruction to clear the incompatible alpha state. Pi Workflows does not import, reinterpret, or delete that state.
+
+## Shared records
+
+Four record groups provide the common lifecycle rules.
+
+### Resources
+
+`resources` identifies each mutable aggregate and holds its current revision. Runs, decisions, controller resources, effects, channels, notifications, deferred turns, and session segments have stable resource identities.
+
+Every accepted domain command compares its expected revision and increments it once.
+
+### Leases
+
+`leases` holds the current owner, a hash of its random claim token, lease times, and a monotonically increasing generation.
+
+A new owner always receives a new generation. Releasing a lease clears the owner fields but does not reduce or reuse the generation. A stale token or generation cannot write after ownership changes.
+
+### Events
+
+`events` is the immutable audit history. Each event records the resource revision, event type, actor class, private local actor ID when applicable, lease generation, payload blob, and commit time.
+
+A domain row and its event are written in one transaction. Normal APIs never update or delete events.
+
+### Effects
+
+`effects` is the transactional outbox. A domain transaction records required follow-up work before it commits. Each effect has:
+
+- a deterministic effect ID
+- a source resource and exact source revision
+- an effect type and idempotency key
+- a canonical payload blob
+- an owner scope
+- a status and retry time
+- a result, error, external reference, and settlement time when applicable
+
+`effect_attempts` records each application attempt and ownership generation. A matching repeated request adopts the existing effect. A different request under the same key is a conflict.
+
+Local effects use deterministic transactions. Run queue settlement effects are created only for runs that have a `run_queue` row; direct engine and controller-child runs do not create phantom queue work. External effects use provider idempotency or observation when available. An uncertain result becomes `ambiguous` and is not repeated without evidence.
+
+## Domain tables
+
+The shared records do not replace domain schemas. The following `STRICT` tables keep the state explicit:
+
+| Area                | Tables                                                                                           |
+| ------------------- | ------------------------------------------------------------------------------------------------ |
+| Schema and projects | `schema_meta`, `projects`                                                                        |
+| Content             | `blobs`                                                                                          |
+| Shared lifecycle    | `resources`, `leases`, `events`                                                                  |
+| Workflows           | `workflow_definitions`, `runs`, `run_bindings`, `run_queue`, `node_attempts`, `workflow_updates` |
+| Session capture     | `session_segments`, `session_entries`, `session_events`                                          |
+| Human decisions     | `human_decisions`, `human_decision_resolutions`, `human_decision_submissions`, `continuations`   |
+| Controllers         | `controller_resources`, `controller_finalizers`, `controller_queue`, `controller_workflows`      |
+| Effects             | `effects`, `effect_attempts`                                                                     |
+| Pi delivery         | `notifications`, `turn_intents`                                                                  |
+| Channels            | `channels`, `channel_cursors`, `channel_inbox`, `channel_messages`, `channel_message_parts`      |
+
+Foreign keys join projects, runs, attempts, decisions, controllers, effects, and channel records. Partial unique indexes enforce one active node attempt per run, one queued or running reservation per Pi session, one decision winner, and one deterministic effect key. A parked waiting parent does not block its continuation. Reserving that continuation settles the parked parent queue in the same transaction, so a failed reservation leaves the parent recoverable.
+
+## Content-addressed values
+
+`blobs` stores canonical JSON and UTF-8 text as bytes. Its primary key is the 32-byte SHA-256 digest of the bytes.
+
+Insertion verifies the digest, media type, byte length, and exact bytes. Repeated content adopts the existing row. This replaces separate artifact files while keeping large prompts, outputs, errors, session payloads, and rendered channel text deduplicated.
+
+### Assistant-message attempts
+
+An agent definition records `expectedOutput` as either a submitted-output description or `{ "kind": "assistant-message", "maxChars"?: number }`. Omitted `maxChars` means that Pi Workflows adds no character limit.
+
+A completed assistant-message attempt stores the exact text through the normal output blob. Its result record also stores a receipt with the text digest, final Pi session entry ID when available, optional author-supplied limit, and whether recovery adopted an existing response. Session tables keep the prompt-to-response entry range and the normal Pi message events.
+
+An interrupted assistant-message attempt keeps its attempt ID when the origin Pi session resumes it. The executor adopts a matching completed assistant child from the active Pi branch instead of displaying the response twice. Submitted and non-agent attempts keep their normal fresh-attempt resume behavior.
+
+## Write contract
+
+A write command uses this order:
+
+```text
+BEGIN IMMEDIATE
+verify the exact schema
+verify the actor and operation
+verify the expected resource revision
+verify the claim token, generation, and expiry when ownership is required
+verify the domain transition
+write content-addressed values
+increment the resource revision
+write the immutable event
+update the domain row
+insert deterministic follow-up effects
+COMMIT
+```
+
+Any failed check rolls back the complete command.
+
+A TypeScript write permit carries the expected facts between layers. It is not authority by itself. The store verifies durable ownership and revision data again inside the transaction.
+
+## Ownership
+
+Reading or finding a row never gives write authority.
+
+- A run owner may advance the run, apply automatic decision policy, create its continuation, settle its parent, and complete its queue work.
+- A controller claim owner may update controller status, reserve effects, and start child workflows for that resource.
+- A verified human channel actor may submit one answer candidate for the named decision. It does not gain run ownership.
+- A channel lease owner may update only its channel cursor, inbox, delivery, and settlement records.
+- Control commands have narrow explicit operations, such as requesting cancellation or deletion.
+- Model-originated workflow answers cannot resolve protected human decisions.
+
+Stores check ownership in the same transaction as the write. Shared scans, status commands, lists, viewers, and the Rust `piw` program are read-only.
+
+## Competing outcomes
+
+Each domain has one atomic winning fact.
+
+Human answers, timeout policy, explicit cancellation, and no-default expiry compete through `human_decision_resolutions`. Its decision primary key allows one immutable winner.
+
+A deadline with a validated default response is timeout-policy acceptance. It cannot become an expiry cancellation. Expiry cancellation is valid only when there is no default response.
+
+Late or repeated commands return or adopt the durable winner. They do not overwrite it.
+
+The same rule applies to run terminal outcomes, continuation admission, queue settlement, controller effects, retry scheduling, and channel settlement through their domain constraints and expected revisions.
+
+## Read contract
+
+Status is a pure projection of domain rows, immutable facts, current leases, and effect receipts.
+
+- A terminal run fact overrides stale queue presentation.
+- An accepted decision is accepted even if its continuation effect is still pending.
+- A cancelled decision is cancelled even if parent cleanup is still pending.
+- A stale owner is not shown as current.
+- An ambiguous external effect is shown as unresolved.
+
+Read paths do not repair state. Owner reconcilers apply pending effects and write receipts.
+
+## Projects and concurrency
+
+All projects use the same file. `projects` stores a stable ID and canonical path. Project-scoped controller and run queries use that key. Standalone host lock and child-process registry files use a project hash under the workflow state directory, so different projects can run hosts concurrently while two hosts for one project still conflict.
+
+SQLite WAL permits concurrent readers while one writer commits. Writers are serialized by SQLite and must keep transactions short. Hashing, model calls, shell work, and external requests happen outside write transactions.
+
+This contract is for local storage on one machine. It does not claim distributed consensus or network-filesystem safety.
+
+## Backup and verification
+
+An active database must be backed up with the SQLite backup API. Copying only `state.sqlite` while WAL writes are active is not supported.
+
+Verification checks:
+
+```sql
+PRAGMA integrity_check;
+PRAGMA foreign_key_check;
+```
+
+A backup is opened read-only and checked before it is accepted.
+
+Supported commands are:
+
+```bash
+pi-workflows state status
+pi-workflows state verify
+pi-workflows state backup /absolute/path/to/state-backup.sqlite
+```
+
+`status` reports only safe counts, file size, active leases, and unsettled effects.
+It does not print actor IDs, channel references, payloads, or credentials.
+
+## Alpha cutover
+
+This is a hard cut. Pi Workflows has no normal reader or writer for older live storage. It does not use dual reads, dual writes, aliases, versioned state roots, or automatic import.
+
+Older state remains untouched. If it is present when a new database would be created, Pi Workflows fails with a clear instruction instead of guessing or deleting data.

package/docs/WORKFLOW_COMPOSITION.md

@@ -72,29 +72,29 @@ import repair from "./repair.workflow.js";
 export default defineWorkflow({
   source: import.meta.url,
   name: "monitor-with-repair",
-  startAt: "check",
+  startAt: "observe",
   includes: {
     repair: includeWorkflow(repair, {
       input: ({ outputs }) => ({
-        task: (outputs.check as { issue: string }).issue,
+        task: (outputs.observe as { action: { issue: string } }).action.issue,
       }),
     }),
   },
   nodes: {
-    check: agent({ prompt: () => "Check the target." }),
+    observe: agent({ prompt: () => "Observe the target without changing it." }),
     wait: compute({ run: () => ({}) }),
-    finish: compute({ run: ({ outputs }) => outputs.check }),
+    finish: compute({ run: ({ outputs }) => outputs.observe }),
   },
   edges: [
     {
-      from: "check",
+      from: "observe",
       switch: {
         on: "$.route",
-        cases: { continue: "wait", repair: "repair", stop: "finish" },
+        cases: { wait: "wait", act: "repair", stop: "finish" },
       },
     },
-    { from: "wait", to: "check" },
-    { from: "repair.fixed", to: "check" },
+    { from: "wait", to: "observe" },
+    { from: "repair.fixed", to: "observe" },
     { from: "repair.blocked", to: "finish" },
   ],
 });
@@ -204,11 +204,11 @@ A checkpoint inside a child uses the normal continuation behavior and resumes at
 
 ### Reports and presentation
 
-Notify nodes and updates keep qualified node identities. Only the root workflow produces final presentation. A child's `presentationPrompt` applies when the child runs alone and is ignored when included.
+Notify nodes and updates keep qualified node identities. Only the root workflow produces final `presentationPrompt` output. A child's `presentationPrompt` applies when the child runs alone and is ignored when included. An agent with `expectedOutput: assistantMessage()` is part of the graph, so its normal assistant response remains visible when included. The parent continues only after that turn settles.
 
 ## Persistence
 
-Composition extends the existing run bundle.
+Composition extends the existing SQLite run state.
 
 The manifest and state record:
 
@@ -259,13 +259,13 @@ monitor
 
 ## Autoplan, autodoc, and autoimplement
 
-`autoplan` accepts the problem, scope, constraints, an optional previous plan, and new evidence. It automatically selects the best practical in-scope solution. The ideal end state can win when it is feasible, but an unavailable upstream change cannot block a valid practical solution. It exits through `ready` or `blocked` and returns a plan digest and change status.
+`autoplan` accepts the problem, scope, constraints, an optional previous plan, and new evidence. It records two through four practical candidates plus the ideal, automatically selects the best in-scope solution, and records one rejection reason for every other explicit candidate. It includes `plain-summary` on ready and blocked routes, so the user sees one short normal assistant response before the parent continues. The response calls the choice a plan selected for approval and cannot satisfy the later human decision. Autoplan exits through `ready` or `blocked` and returns the full candidates, selection, detailed plan when ready, plain summary, plan digest, and change status.
 
 `autodoc` accepts an already selected plan or finds it in the active conversation and referenced canonical documents. It adopts current documentation or updates the canonical specification and implementation plan, runs documentation checks, and returns a documented-plan record. It never selects a solution or implements one.
 
 `autoimplement` requires a clear existing plan, but the structured `plan` input is optional because the plan can already be in conversation context or canonical documentation. It blocks when it cannot find a clear plan. It skips autodoc when documentation is current and includes autodoc when documentation is missing or stale. The absence of `input.plan` never routes to initial autoplan.
 
-Autoimplement includes `autoplan` only as evidence-driven `redesign`. When implementation, verification, review, comments, or CI proves that the approach is wrong, the revised plan passes through autodoc before implementation resumes. Local bugs go to a fix step instead.
+Autoimplement includes the shared plan-change workflow only as evidence-driven `redesign`. When implementation, verification, review, comments, or CI proves that the approach is wrong, the shared workflow runs Autoplan, Autodoc, the configured plan decision, and bounded replanning before implementation resumes. Local bugs go to a fix step instead. Existing supplied or discovered plans bypass the decision.
 
 Review rounds record findings at every severity from P0 through P2. P0 or P1 findings require another implementation and review round. A P2-only round can be addressed, but the workflow does not run the reviewer again solely because P2 work changed files.
 
@@ -277,36 +277,37 @@ Autoimplement prepares a ready PR by default. It merges only when its input expl
 
 ## Monitor repair
 
-Monitor remains observation-only unless its input explicitly authorizes mutation. An authorized repair path is:
+Monitor authorizes routine bounded repair by default. Set `repair: false` when a run must remain observation-only. The repair path is:
 
 ```text
 check
-  -> initialDesign: autoplan
-  -> documentation: autodoc
-  -> approval: plan-approval when requested
-       -> replan: initialDesign
+  -> planChange
+       -> autoplan
+       -> autodoc
+       -> plan-approval
+            -> replan: autoplan
   -> implementation: autoimplement
-       -> redesign: autoplan -> autodoc when needed
+       -> redesign: planChange when needed
   -> check
 ```
 
-The outer `autoplan` creates the first plan. Autodoc records it before implementation. An optional plan approval gate can continue, stop, or return exact replan instructions to autoplan. The inner redesign mount revises a plan only when new evidence invalidates it and records the revision through autodoc. The monitor checks the target again after implementation and does not trust a repair claim by itself.
+The shared plan-change workflow creates, records, and gates each repair plan. Its default policy asks the `operator` audience and continues after 10 minutes without an answer. Required mode waits for an explicit answer. Skip mode creates no decision. Monitor passes the selected plan into Autoimplement, so Autoimplement does not ask about that digest again. A later Autoimplement redesign uses the same shared workflow for the changed digest. The monitor checks the target again after implementation and does not trust a repair claim by itself.
 
 A protected change to model choice, benchmark method, credentials, hardware, spending authority, or another user decision exits as blocked. The workflow never changes the protected part of the task silently.
 
-## Compatibility and release
+## Compatibility
 
-Workflows without inputs, exits, or includes run unchanged. Existing controller child workflows remain unchanged. Existing terminal run bundles remain readable.
+Workflows without inputs, exits, or includes run unchanged. Existing controller child workflows remain unchanged. Existing terminal SQLite runs remain readable.
 
-This is a compatible public API addition under the project's pre-1.0 policy. It targets `0.10.0` if no earlier release changes the next version.
+Composition and assistant-message output are compatible public API additions under the project's pre-1.0 policy.
 
 ## Contract impact
 
-- **Session state:** normal workflow messages and tool results only.
-- **Other persistent data:** additive source and mount data, definition digests, and include events in existing run bundles.
+- **Session state:** normal workflow messages, tool results, and visible assistant-message node outputs.
+- **Other persistent data:** additive source and mount data, definition digests, and include events in existing SQLite runs.
 - **Pi internals:** none.
 - **Public Pi API:** existing extension APIs only.
-- **Public pi-workflows API:** typed workflow inputs and exits, `includeWorkflow()`, direct imports, dynamic references, and `defineWorkflowRegistry()`.
+- **Public pi-workflows API:** typed workflow inputs and exits, `includeWorkflow()`, direct imports, dynamic references, `defineWorkflowRegistry()`, and `expectedOutput: assistantMessage()`.
 
 ## Required tests
 
@@ -328,6 +329,6 @@ The implementation must cover:
 - reviewer command correction;
 - P0 through P2 plus clean review routes;
 - five-minute CI wait and opportunistic testing routes;
-- monitor observation-only and authorized repair modes;
+- monitor default repair and explicit observation-only modes;
 - repeated repair with no progress;
 - real-Pi execution of nested monitor repair.

package/docs/WORKFLOW_STEP_MESSAGES.md

@@ -2,15 +2,13 @@
 
 This specification defines how pi-workflows shows agent-step instructions in an interactive Pi session. The model receives the complete step prompt, while the user sees a small workflow card that can be expanded.
 
-This contract is implemented for the release after `0.5.3`.
-
 ## Goal
 
-Agent-step prompts contain the task, workflow identity, attempt identity, output shape, and submission rules. This information is required by the model, but showing it as a large user message makes the conversation hard to read.
+Agent-step prompts contain the task, workflow identity, attempt identity, output form, and completion rules. Submitted steps call the workflow tool. Assistant-message steps reply normally. This information is required by the model, but showing it as a large user message makes the conversation hard to read.
 
-pi-workflows will send the same prompt as a custom Pi message. A custom renderer will show a compact summary by default and the full content when expanded.
+pi-workflows sends the same prompt as a custom Pi message. A custom renderer shows a compact summary by default and the full content when expanded.
 
-This is a presentation change. It does not add a workflow primitive, change graph execution, or change the step completion contract.
+Both output forms use the existing `agent` node. The completion form changes through `expectedOutput`; no new node type is added.
 
 ## Message contract
 
@@ -45,7 +43,7 @@ pi.sendMessage(
 
 `content` is the complete prompt that the existing executor would send as a user message. It remains available to the model and in session history.
 
-`details` contains structured display data. The renderer reads this object directly and never parses the prompt text. `AgentStepContract` remains the source of every identity field and the expected-output field.
+`details` contains structured display data. The renderer reads this object directly and never parses the prompt text. `AgentStepContract` remains the source of every identity field, the completion form, the submitted output description, and any explicit assistant character limit.
 
 `kind` distinguishes the first delivery from a reminder or a resume that must repeat the instructions. An ordinary resume that can continue without another prompt does not create a message.
 
@@ -53,7 +51,7 @@ pi.sendMessage(
 
 The workflow engine remains independent of Pi. It continues to produce an `AgentStepRequest` with a complete prompt and structured contract.
 
-The request gains optional presentation data for the run title and node status detail. The conversation executor passes the prompt, contract, presentation data, delivery kind, and streaming state to the Pi extension. The RPC executor sends the same complete prompt to headless Pi without TUI metadata.
+The request carries optional presentation data for the run title and node status detail. The conversation executor passes the prompt, contract, presentation data, delivery kind, and streaming state to the Pi extension. The RPC executor handles submitted steps. An assistant-message step parks for the origin Pi session; a detached run with no origin session fails before prompting.
 
 One pure formatter remains responsible for the model prompt used by both executors. Interactive delivery must not shorten, summarize, or rebuild the model prompt from display fields.
 
@@ -82,16 +80,17 @@ The expanded card shows:
 - node id
 - attempt id
 - delivery kind
-- expected output
+- completion form
+- expected output and optional character limit
 - full model prompt
 
 Expansion uses Pi's existing custom-message expansion state and keys. pi-workflows does not add another toggle or store separate expansion state.
 
 ## Reminders and resumes
 
-The existing bounded reminder behavior stays in place. A reminder uses the same custom message type and renderer. It keeps the contract and sets `kind: "reminder"`.
+The existing bounded reminder behavior stays in place for submitted steps. A reminder uses the same custom message type and renderer. It keeps the contract and sets `kind: "reminder"`. Assistant-message steps do not nudge or retry after a visible response.
 
-A resumed step uses `kind: "resume"` only when the executor must send the instructions again. The attempt id must still identify the active attempt. Stale attempts remain invalid.
+A resumed step uses `kind: "resume"` only when the executor must send the instructions again. An interrupted assistant-message step keeps its attempt id. If its matching prompt already has a completed assistant child on the active branch, the executor adopts that exact response instead of displaying it again. Stale attempts and responses from another branch remain invalid.
 
 ## Notifications
 
@@ -103,9 +102,9 @@ The two message types must not share delivery code that can accidentally change
 
 ## Session and persistence impact
 
-New interactive step deliveries replace `sendUserMessage` with `sendMessage`. Existing session entries remain readable and are not rewritten.
+Interactive step deliveries use `sendMessage` instead of `sendUserMessage`. Existing session entries remain readable and are not rewritten.
 
-The custom message is a normal documented Pi session message. pi-workflows adds no Pi session schema, private entry type, or separate persistent store. Run bundles keep the existing full prompt and structured step contract, so this change does not alter the run-bundle schema.
+The custom prompt and visible assistant response are normal documented Pi session messages. pi-workflows adds no Pi session schema, private entry type, or separate persistent store. SQLite stores the full prompt, exact assistant text, conversation range, and additive digest receipt in existing content-addressed records, so this behavior adds no durable format.
 
 If the renderer is unavailable, Pi still retains the custom message content. pi-workflows does not add a fallback path that sends a duplicate user message.
 
@@ -115,11 +114,11 @@ This design uses the documented `pi.sendMessage()` and `pi.registerMessageRender
 
 It does not require a Pi core change or private Pi API.
 
-The workflow package adds no node, graph action, tool action, or workflow-file field for this feature. Workflow authors do not configure message rendering.
+The workflow package adds `assistantMessage()` as an `expectedOutput` value for the existing `agent` node. It adds no node type, graph action, Pi tool, private API, or message-rendering option.
 
 ## Validation and tests
 
-The implementation must verify:
+Tests verify:
 
 - interactive and RPC executors give the model the same complete prompt
 - one step message starts one model turn
@@ -127,12 +126,15 @@ The implementation must verify:
 - expanded rendering shows the full prompt and exact contract ids
 - long and missing display fields render safely
 - reminders and resumed deliveries keep the active attempt id
-- stale attempts remain rejected after timeout or cancellation
-- session replay restores the same custom message
+- submitted steps still reject stale attempts after timeout or cancellation
+- assistant steps wait for `agent_settled` and capture only visible text
+- empty, failed, aborted, tool-only, and explicitly over-limit responses fail once
+- session replay restores the same custom prompt and adopts an existing response once
+- detached execution parks for the origin session or fails clearly when none exists
 - notifications still enter context without starting a model turn
-- no duplicate user message is sent
+- no duplicate prompt or assistant response is sent
 
-The end-to-end test must inspect the provider-facing prompt as well as the TUI message record. A correct card with missing model instructions is a failure.
+The end-to-end test inspects the provider-facing prompt as well as the TUI message record. A correct card with missing model instructions is a failure.
 
 ## Security
 

package/docs/WORKFLOW_UPDATES.md

@@ -50,7 +50,7 @@ An agent publishes the same update through the existing `workflow` tool:
 }
 ```
 
-The `update` tool action does not complete the agent step. The agent still calls `submit` once with the final step output.
+The `update` tool action does not complete the agent step. A submitted agent still calls `submit` once with its final output. An assistant-message agent completes with its settled visible reply instead.
 
 ## Place in the workflow model
 
@@ -176,7 +176,7 @@ Keys are case-sensitive. A publisher must reuse the same key for the same item t
 
 The generic update layer allows fields it does not understand inside `data`. A package-defined update type may reject unknown fields.
 
-The encoded object must not exceed 64 KiB. Large logs and binary data do not belong in updates. Nodes should return large final values through normal outputs, where the run-bundle artifact rules apply.
+The encoded object must not exceed 64 KiB. Large logs and binary data do not belong in updates. Nodes should return large final values through normal outputs, which the content-addressed SQLite blob store handles.
 
 ### Runtime-owned fields
 
@@ -256,7 +256,8 @@ Controller resource events remain controller events. They become workflow update
 
 ## Persistence
 
-Each accepted update appends one `update_published` event to `trace.ndjson`:
+Each accepted update transaction inserts one `workflow_updates` row and one
+`update_published` event:
 
 ```json
 {
@@ -282,17 +283,17 @@ Each accepted update appends one `update_published` event to `trace.ndjson`:
 }
 ```
 
-`state.json` adds an optional `updates` array containing only the latest record for each `(type, key)` pair. The array is sorted by `seq`. Omission means that the run has never published an update. New runs write an empty array from their first state projection. The trace remains the full history and source of truth.
+The `runs` state blob contains only the latest record for each `(type, key)` pair. The array is sorted by event revision. `workflow_updates` and `events` retain the complete history.
 
-A resumed run keeps its latest projection and appends new update events. A checkpoint continuation starts a new run with an empty update projection. Updates are scoped to one run and are not carried into continuation bundles.
+A continued run keeps its latest projection and appends new update events. A checkpoint continuation starts a new run with an empty update projection. Updates are scoped to one run and are not carried into continuation runs.
 
-The state projection supports at most 1,024 current `(type, key)` pairs. A publication that would exceed the limit is rejected. Trace history remains append-only.
+The state projection supports at most 1,024 current `(type, key)` pairs. A publication that would exceed the limit is rejected. Event history remains append-only.
 
-The update envelope is an additive part of `pi-workflows.trace-event.v1` and `pi-workflows.run-state.v1`. Existing bundles without `updates` remain valid under the omission rule. The implementation uses one current schema and does not add migration files, fallback formats, or dual writes. New bundles that contain updates are not required to work with older package releases.
+The update envelope remains part of `pi-workflows.run-state.v1`. The SQLite schema is the only live durable format.
 
 ## Ordering and limits
 
-Updates use the run store's existing serialized write chain and claim fence. Their trace sequence defines their total order.
+Updates use one `BEGIN IMMEDIATE` transaction with the run's expected revision and claim fence. Their accepted update sequence defines their total order.
 
 Default safety limits per run are:
 
@@ -442,6 +443,6 @@ Validation errors must identify the field and rule. They must not include unrela
 
 Updates are data. They do not grant permission to execute a command, retry work, change a target, publish an artifact, or increase spending.
 
-Run bundles are private and may contain update data from external systems. Existing bundle permissions and export warnings apply.
+SQLite runs are private and may contain update data from external systems. The database permission and export warnings in [SQLite state](SQLITE_STATE.md) apply.
 
 This feature does not add remote transports, a metrics database, global aggregation, automatic polling, or a new Pi core API. Workflow authors remain responsible for the trust and cost of their agent, action, shell, and controller code.

package/docs/development.md

@@ -6,7 +6,7 @@ authoring workflows, see [workflows.md](workflows.md).
 ## Layout and boundaries
 
 ```
-src/workflows/   finite graph engine: definitions, execution, bundles, loader
+src/workflows/   finite graph engine: definitions, execution, SQLite stores, loader
 src/builtins/    default workflows shipped at lowest discovery precedence
 src/controllers/ durable resources, queue, reconciliation, effects, child runs
 src/extension/   pi integration: commands, workflow tool, controller host, widget
@@ -22,14 +22,14 @@ package-owned definitions and imports only the public workflow engine.
 `src/controllers` may import the public workflow engine for child-run
 scheduling. `src/extension` and `src/host` may also import the built-in catalog.
 The extension and viewer never import each other. The viewer reads
-run bundles and opens the controller SQLite database read-only, so it works
+SQLite runs and opens the controller SQLite database read-only, so it works
 from any process.
 
 Within `src/render`, `graph.ts` computes a pure layered layout (ported from
 the acpx replay viewer: labelled switch expansion, DFS back-edge detection,
 longest-path layering, barycenter ordering, virtual pass-through cells for
 long edges), `canvas.ts` is a character grid that merges box-drawing
-characters by connectivity, and `graph-render.ts` turns a run bundle plus a
+characters by connectivity, and `graph-render.ts` turns a SQLite run state plus a
 replay position into the drawn graph in one of two node styles: `box`
 (bordered nodes, used by the viewer and the in-pi widget) or `line`
 (single-line nodes). The widget windows the boxed graph around the active
@@ -41,7 +41,7 @@ composes the full detail view (header, graph, step timeline, step inspector)
 and stays pure so tests can assert on rendered lines.
 
 The TypeScript and Rust viewers both show progress tracks, sample counts,
-confidence, update time, and ETA from bundle data. The Rust viewer also keeps
+confidence, update time, and ETA from SQLite data. The Rust viewer also keeps
 graph layout and plain rendering in parity with `src/render`, then applies
 ratatui-only presentation through semantic canvas
 roles and `tui/src/theme`. Catppuccin is the default. Theme colors must be
@@ -74,7 +74,7 @@ Pi's documented `turn_*`, `message_*`, and `tool_execution_*` hooks and
 normalizes them before passing records to `WorkflowRunStore`. The workflows layer owns persisted shapes and schema validation. It also owns
 ordered append chains but never imports Pi types. High-rate hooks only stamp and enqueue bounded records;
 disk writes run on a separate chain. Capture failures are explicit in
-`session/capture.json` and never fail workflow execution.
+the `session_segments` capture status and never fail workflow execution.
 
 `src/viewer/session-reducer.ts` and `tui/src/session.rs` implement the same
 sequence-ordered fold. Shared fixtures in `fixtures/session-events/` pin their
@@ -117,11 +117,11 @@ the real pi CLI from `devDependencies` in RPC mode with:
 
 - `PI_CODING_AGENT_DIR` pointed at a temp agent dir containing a `models.json`
   for the mock provider,
-- `PI_WORKFLOWS_RUNS_DIR` pointed at a temp runs dir,
+- `HOME` pointed at a temporary home containing the canonical workflow database,
 - the extension loaded from source with `-e src/extension/index.ts`.
 
-It drives `/workflow` over the RPC protocol and asserts on the resulting run
-bundle, including temporal events, final entry linkage, capture integrity, and
+It drives `/workflow` over the RPC protocol and asserts on the resulting SQLite
+rows, including temporal events, final entry linkage, capture integrity, and
 terminal immutability, then renders the finished run through the viewer CLI.
 Nothing outside the temp directories is touched, and no real model is called.
 
@@ -156,7 +156,7 @@ before publishing.
 
 - Conventional Commits for commit messages and PR titles.
 - Persisted JSON uses camelCase keys and versioned `schema` identifiers; see
-  [run-bundles.md](run-bundles.md). Breaking a persisted shape means bumping
+  [SQLITE_STATE.md](SQLITE_STATE.md). Breaking a persisted shape means bumping
   the schema version string.
 - Every exported API of the engine (`src/workflows/index.ts`) is covered by
   unit tests; new node types or edge semantics need tests in `test/` and a