@synapsor/runner 0.1.14 → 0.1.16

package/docs/README.md

@@ -41,6 +41,10 @@ no-database demo, wire your database, then read deeper concepts.
 - [Capability Authoring](capability-authoring.md): define read/proposal
   capabilities, model-facing descriptions, result envelopes, trusted context,
   and writeback guards.
+- [DSL Reference](dsl-reference.md): complete supported grammar, clause order,
+  compiled meaning, and constraints.
+- [Runner Config Reference](runner-config-reference.md): every public wiring
+  key, default, environment binding, and path-resolution rule.
 - [Recipes](recipes.md): starter business-capability templates.
 - [JSON Schema](../schemas/synapsor.runner.schema.json): editor validation for
   `synapsor.runner.json`.

package/docs/capability-authoring.md

@@ -5,9 +5,18 @@ source of truth for trusted context, resources, capabilities, evidence,
 proposal shape, and writeback intent.
 
 ```text
-contract.synapsor -> synapsor.contract.json -> synapsor.runner.json
+contract.synapsor.sql -> synapsor.contract.json -> synapsor.runner.json
 ```
 
+Use `.synapsor.sql` as the preferred DSL source extension because editors can
+provide generic SQL highlighting. Legacy `.synapsor` files remain supported;
+the suffix does not change DSL semantics or generated canonical JSON.
+
+For exact clause grammar, ordering, constraints, fixed-string patches, and the
+primary-key-only lookup rule, see the [DSL Reference](dsl-reference.md). For all
+local wiring keys and path rules, see the
+[Runner Config Reference](runner-config-reference.md).
+
 Use `synapsor.runner.json` for local wiring: database env var names, SQLite
 store path, MCP transport settings, and local development flags. The model sees
 semantic capabilities such as `billing.inspect_invoice`, not raw SQL, table
@@ -69,7 +78,7 @@ END
 Compile and validate:
 
 ```bash
-synapsor-runner dsl compile ./contract.synapsor --out ./synapsor.contract.json --strict
+synapsor-runner dsl compile ./contract.synapsor.sql --out ./synapsor.contract.json --strict
 synapsor-runner contract validate ./synapsor.contract.json
 synapsor-runner contract bundle ./synapsor.contract.json --out ./synapsor-runner-bundle
 synapsor-runner cloud push ./synapsor.contract.json --dry-run

package/docs/conformance.md

@@ -2,6 +2,11 @@
 
 Conformance fixtures prove behavior, not just JSON shape.
 
+The conformance artifacts are canonical JSON. When authoring a source contract
+for these checks, prefer `.synapsor.sql` for generic editor SQL highlighting;
+`.synapsor` remains backward compatible and the filename does not affect the
+compiled contract semantics.
+
 `@synapsor/spec` owns the fixtures under:
 
 ```text
@@ -33,6 +38,9 @@ fixture directories:
 - `docs/dsl-json-parity.md`, DSL/spec tests, and the
   `numeric-bounds-transition` C++ export fixture cover richer DSL/JSON parity
   fields such as `returns_hint`, numeric bounds, and transition guards.
+- `packages/dsl/fixtures/invalid/non-primary-lookup.synapsor.sql` proves the
+  DSL rejects a lookup meaning that canonical spec 0.1 cannot represent,
+  instead of silently rewriting it to primary-key access.
 - The main Synapsor repo script `scripts/verify_contract_cloud_push.sh`
   verifies real Cloud push, retrieval, idempotent versioning, unauthorized
   rejection, and runner-bundle download against a live local control-plane.

package/docs/doctor.md

@@ -63,9 +63,9 @@ The target-table probe uses fixed schema/table/column identifiers from the
 reviewed config. It does not accept model SQL, user SQL, arbitrary table names,
 or arbitrary column names. It runs inside a transaction and rolls back.
 
-The receipt-table probe can create `synapsor_writeback_receipts` if the writer
-has permission. If your policy does not allow Runner to create tables in the
-application schema, pre-create the table and grant access:
+An administrator must pre-create `synapsor_writeback_receipts` and grant the
+steady-state writer access. The doctor probe does not execute DDL or require
+schema `CREATE`:
 
 ```bash
 synapsor-runner writeback migration --engine postgres --schema synapsor

package/docs/dsl-reference.md

@@ -0,0 +1,197 @@
+# Synapsor DSL Reference
+
+The Synapsor DSL is a reviewable SQL-like authoring format that compiles to the
+canonical `@synapsor/spec` contract. Prefer `.synapsor.sql`; legacy `.synapsor`
+files remain valid. The filename does not change semantics.
+
+Validate and compile with strict safety warnings enabled:
+
+```bash
+synapsor-runner dsl validate ./contract.synapsor.sql --strict
+synapsor-runner dsl compile ./contract.synapsor.sql \
+  --out ./synapsor.contract.json --strict
+```
+
+Keywords are case-insensitive. Blocks start with `CREATE ...` and end with
+`END` or `END;`. Lines may end in semicolons. `--` starts a line comment.
+Unsupported clauses fail explicitly.
+
+## Agent context
+
+```sql
+CREATE AGENT CONTEXT local_operator
+  BIND tenant_id FROM ENVIRONMENT SYNAPSOR_TENANT_ID REQUIRED
+  BIND principal FROM ENVIRONMENT SYNAPSOR_PRINCIPAL REQUIRED
+  TENANT BINDING tenant_id
+  PRINCIPAL BINDING principal
+END
+```
+
+| Clause | Meaning |
+| --- | --- |
+| `BIND name FROM source key [REQUIRED]` | Defines trusted context. Sources: `SESSION`, `ENV`/`ENVIRONMENT`, `CLOUD_SESSION`, `STATIC_DEV`, `HTTP_CLAIM`. Model tool arguments cannot set these bindings. |
+| `TENANT BINDING name` | Selects the binding used for tenant scope. Defaults to a binding named `tenant_id`. |
+| `PRINCIPAL BINDING name` | Selects the actor binding. Defaults to a binding named `principal`. |
+
+At least one `BIND` is required. The selected tenant/principal bindings must be
+provided by the trusted runtime environment, not by the model.
+
+## Capability identity and target
+
+```sql
+CREATE CAPABILITY billing.inspect_invoice
+  DESCRIPTION 'Inspect one invoice in the trusted tenant.'
+  RETURNS HINT 'Returns reviewed fields and an evidence handle.'
+  USING CONTEXT local_operator
+  SOURCE billing_postgres
+  ON public.invoices
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  CONFLICT GUARD updated_at
+  ...
+END
+```
+
+| Clause | Requirement and compiled meaning |
+| --- | --- |
+| `CREATE [AGENT] CAPABILITY namespace.name` | Starts a qualified capability. |
+| `DESCRIPTION 'text'` | Model-facing `tools/list` description. Recommended for every tool and required by strict review for proposal quality. |
+| `RETURNS HINT 'text'` | Model-facing result guidance. |
+| `USING CONTEXT name` | Required. References an agent context. |
+| `SOURCE name` | Source key that must match `synapsor.runner.json.sources`. |
+| `ON schema.table` | Required fixed target. Table/schema are never model inputs. |
+| `PRIMARY KEY column` | Fixed single-row target key. Defaults to `id` in DSL 0.1. Declare it explicitly. |
+| `TENANT KEY column` | Required in DSL 0.1. Adds trusted tenant scope to every read/write. |
+| `CONFLICT GUARD column` | Captures the row-version value for exact guarded writeback. Prefer a monotonic version or native-precision timestamp. |
+
+## Arguments and lookup
+
+```sql
+  LOOKUP invoice_id BY id
+  ARG invoice_id STRING REQUIRED MAX LENGTH 128 DESCRIPTION 'Invoice id.'
+  ARG amount_cents NUMBER REQUIRED MIN 1 MAX 2500 DESCRIPTION 'Amount in cents.'
+  ARG confirmed BOOLEAN REQUIRED
+```
+
+Argument types are `STRING`/`TEXT`, `NUMBER`, and `BOOLEAN`/`BOOL`.
+
+- `REQUIRED` makes the model-facing argument mandatory.
+- `DESCRIPTION 'text'` documents the argument in MCP `tools/list`.
+- `MIN n` and `MAX n` are numeric bounds for `NUMBER`.
+- `MAX LENGTH n` bounds `STRING`/`TEXT`. Legacy text `MAX n` remains accepted.
+- `LOOKUP arg BY column` binds one argument to the target row lookup.
+
+In spec 0.1, lookup is primary-key-only. The `BY` column must equal the declared
+`PRIMARY KEY`. A different column fails with `LOOKUP_COLUMN_UNSUPPORTED`; Runner
+never silently rewrites it. List/filter queries require a reviewed view or a
+different capability design.
+
+## Read surface and evidence
+
+```sql
+  ALLOW READ id, tenant_id, status, amount_cents, updated_at
+  KEEP OUT card_token, private_notes
+  REQUIRE EVIDENCE
+  MAX ROWS 1
+```
+
+`ALLOW READ` is required and becomes the visible-field allowlist. `KEEP OUT`
+records fields that must remain outside the model/evidence surface. Keep-out
+fields must not also be visible. `REQUIRE EVIDENCE` records the scoped read and
+query audit. `MAX ROWS n` bounds the result; local 0.1 capabilities are designed
+around one primary-key row.
+
+## Proposal and patch
+
+Read capabilities end after the read clauses. A proposal capability adds:
+
+```sql
+  PROPOSE ACTION waive_late_fee
+  ALLOW WRITE late_fee_cents, waiver_reason
+  PATCH late_fee_cents = 0
+  PATCH waiver_reason = ARG reason
+  PATCH status = 'approved'
+  PATCH reviewed = TRUE
+  PATCH obsolete_note = NULL
+```
+
+`PROPOSE ACTION` must precede proposal-only clauses. `ALLOW WRITE` is the exact
+patch-column allowlist. Each `PATCH` uses one of:
+
+- `ARG name`: value comes from a validated model argument;
+- a quoted fixed string;
+- a fixed number;
+- `TRUE`, `FALSE`, or `NULL`.
+
+Fixed strings such as `PATCH status = 'approved'` are supported. The patch is
+saved as a proposal; it is not executed by the model-facing tool.
+
+## Bounds and transitions
+
+```sql
+  BOUND amount_cents 1..2500
+  BOUND discount_cents ..500
+  BOUND score 1..
+  TRANSITION status ALLOW reported -> approved|rejected
+  TRANSITION status FROM current_status ALLOW open -> closed, held -> open
+```
+
+`BOUND column min..max` applies to a patched numeric column. Either side may be
+open, but not both. Strict mode warns when a numeric argument reaches a patch
+without argument bounds or a patch bound.
+
+`TRANSITION patched_column [FROM source_column] ALLOW from -> to|to, ...`
+allowlists state changes. Without `FROM`, the current value is read from the
+patched column. Values may be identifiers or quoted strings.
+
+## Approval and writeback
+
+```sql
+  APPROVAL ROLE billing_lead
+  AUTO APPROVE WHEN amount_cents <= 2500
+  WRITEBACK DIRECT SQL
+```
+
+`APPROVAL ROLE role` records the required local reviewer role. Local OSS
+approval identity is operator-provided; enterprise identity/RBAC belongs to the
+Cloud boundary.
+
+`AUTO APPROVE WHEN field <= non_negative_integer` is supported only for a
+numeric patched field and must follow `APPROVAL ROLE`. Its maximum cannot exceed
+the field's `BOUND`. Policy approval still does not apply the write.
+
+Writeback forms:
+
+| Clause | Meaning |
+| --- | --- |
+| `WRITEBACK DIRECT SQL` | Runner performs one guarded single-row update after approval. |
+| `WRITEBACK APP HANDLER EXECUTOR name` | Runner calls a configured app-owned executor after approval. URL/token wiring stays outside the contract. |
+| `WRITEBACK CLOUD WORKER` | Delegates approved execution to Cloud worker infrastructure. |
+| `WRITEBACK NONE` | Proposal-only; local apply is intentionally unavailable. |
+
+## Workflow declarations
+
+```sql
+CREATE AGENT WORKFLOW support.refund_review
+  USING CONTEXT local_operator
+  ALLOW CAPABILITY support.inspect_order
+  ALLOW CAPABILITY support.propose_refund
+  REQUIRE EVIDENCE
+  APPROVAL REQUIRED ROLE support_lead
+  CHECKPOINT PROPOSAL ONLY
+END
+```
+
+`USING CONTEXT` and at least one `ALLOW CAPABILITY` are required. Optional
+clauses are `REQUIRE EVIDENCE`, `APPROVAL REQUIRED ROLE role`, and `CHECKPOINT
+NONE|EVERY STEP|PROPOSAL ONLY`. Contracts can declare workflows; Runner 0.1 does
+not execute arbitrary Cloud workflow DAGs, settlement, branching, or auto-merge.
+
+## Unsupported syntax
+
+Unknown clauses fail instead of being ignored. Cloud-generated concepts such as
+`ROOT EXTERNAL`, `JOIN EXTERNAL`, `RETURN ANSWER WITH CITATIONS`, `AUTO BRANCH`,
+and `AUTO MERGE` are not local DSL 0.1 clauses.
+
+The canonical JSON output, not parser implementation details, is the portable
+contract. Validate generated JSON with `synapsor-runner contract validate`.

package/docs/migrating-to-synapsor-spec.md

@@ -138,10 +138,13 @@ synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapso
 You can also compile from the SQL-like authoring layer:
 
 ```bash
-synapsor-runner dsl validate ./contract.synapsor
-synapsor-runner dsl compile ./contract.synapsor --out ./synapsor.contract.json --strict
+synapsor-runner dsl validate ./contract.synapsor.sql
+synapsor-runner dsl compile ./contract.synapsor.sql --out ./synapsor.contract.json --strict
 ```
 
+`.synapsor.sql` is the preferred editor-friendly source filename. Existing
+`.synapsor` files remain valid and compile to equivalent canonical JSON.
+
 ## Bundle For Local Runner
 
 Cloud/exported or hand-written contracts can become a local Runner bundle:

package/docs/production.md

@@ -56,8 +56,9 @@ Write credential for direct `sql_update`:
 
 - can update only the allowed business columns;
 - cannot modify primary-key or tenant columns;
-- can create/write the `synapsor_writeback_receipts` table, or the table is
-  pre-created and granted by an administrator;
+- can `SELECT`/`INSERT`/`UPDATE` the administrator-created
+  `synapsor_writeback_receipts` table;
+- does not need schema `CREATE` during doctor or apply;
 - is never exposed to MCP clients.
 
 Example config:
@@ -81,7 +82,7 @@ worker flows that do not pass a local config.
 ## Receipt Table
 
 Direct SQL writeback stores idempotency receipts in the source database. Runner
-creates this table if allowed:
+expects an administrator to create this table before steady-state operation:
 
 ```sql
 CREATE TABLE IF NOT EXISTS synapsor_writeback_receipts (...);
@@ -97,10 +98,9 @@ synapsor-runner doctor --config synapsor.runner.json --check-writeback
 
 For MySQL, replace `postgres` with `mysql`.
 
-If the writer should not create application-schema tables, pre-create the
-receipt table with an administrator role, grant only the needed receipt-table
-permissions to the writer, or use an app-owned executor that stores receipts in
-your application boundary.
+Grant only receipt-table `SELECT`/`INSERT`/`UPDATE` and schema usage to the
+writer; schema `CREATE` is not required by doctor or apply. Use an app-owned
+executor when receipt storage belongs inside your application boundary.
 
 ## Direct Writeback Vs App-Owned Executor
 
@@ -286,4 +286,3 @@ Before promoting a package or calling a build production-candidate:
 The release gate should cover typecheck, focused tests, packed-package install,
 quick demo, own-db fixture, MCP stdio/HTTP checks, direct writeback,
 app-owned executor paths, package dry-run, and docs/package consistency.
-

package/docs/release-notes.md

@@ -12,9 +12,38 @@ for the Synapsor Cloud CLI.
 
 ## Unreleased
 
-Prepared package version: `@synapsor/runner@0.1.12`. The already-published
-`@synapsor/spec@0.1.4` and `@synapsor/dsl@0.1.4` do not change and must not be
-republished for this release.
+## 0.1.16
+
+### Fleet-Lab Runner Hardening
+
+- Preserves Postgres microseconds in proposal conflict guards and proves normal
+  `now()` rows apply exactly once while genuinely stale rows conflict.
+- Allows a new proposal after conflict without deleting or rewriting the old
+  proposal, receipt, or replay history.
+- Returns semantic active-proposal errors and rejects non-primary DSL lookups.
+- Removes schema-creation requirements from steady-state writeback, aligns audit
+  paths and JSON Schema with contract configs, and creates local ledgers with
+  owner-only POSIX permissions.
+- Adds complete DSL, Runner config, and ledger inspection/security references.
+
+Prepared package versions: `@synapsor/dsl@0.1.6` and
+`@synapsor/runner@0.1.16`. `@synapsor/spec@0.1.4` remains unchanged.
+
+## 0.1.15
+
+### Editor-Friendly DSL Source Files
+
+- Prefers `.synapsor.sql` for DSL source files so editors can provide generic
+  SQL highlighting; `.synapsor` remains supported for compatibility.
+- The filename suffix does not change DSL semantics or generated canonical JSON.
+- Stages `@synapsor/dsl@0.1.5` and `@synapsor/runner@0.1.15`; `@synapsor/spec`
+  remains `0.1.4`.
+
+Prepared package versions: `@synapsor/dsl@0.1.5` and
+`@synapsor/runner@0.1.15`. The already-published `@synapsor/spec@0.1.4` does
+not change and must not be republished for this release.
+
+## 0.1.12
 
 ### Runner Version Invocation
 
@@ -390,9 +419,9 @@ republished for this release.
   `SYNAPSOR_DATABASE_WRITE_URL`.
 - `SYNAPSOR_DATABASE_URL` is accepted only as a legacy fallback for older
   direct worker/apply flows without a local config.
-- Direct SQL writeback creates or writes `synapsor_writeback_receipts` for
-  idempotency and replay. The trusted writer needs permission for that receipt
-  table, or an administrator must pre-create the table and grant access.
+- Direct SQL writeback writes `synapsor_writeback_receipts` for idempotency and
+  replay. Current releases require an administrator-created table and grant the
+  trusted writer table access without schema `CREATE`.
 - Use `synapsor-runner writeback doctor`, `writeback migration`, and
   `writeback grants` to inspect and prepare the direct writeback path.
 - Use app-owned `http_handler` or `command_handler` executors for rich writes

package/docs/runner-config-reference.md

@@ -0,0 +1,194 @@
+# Runner Config Reference
+
+`synapsor.runner.json` wires portable reviewed contracts to one local runtime.
+It contains environment-variable names and fixed identifiers, never database
+URLs, passwords, bearer tokens, prompts, or model-selected tenant authority.
+
+Validate before serving:
+
+```bash
+synapsor-runner config validate --config ./synapsor.runner.json
+```
+
+Editor schema:
+
+```text
+schemas/synapsor.runner.schema.json
+```
+
+Unknown keys fail when `strict` is true (the default).
+
+## Top-level keys
+
+| Key | Required | Meaning |
+| --- | --- | --- |
+| `version` | Yes | Must be `1`. |
+| `mode` | Yes | `read_only`, `shadow`, `review`, or `cloud`. |
+| `result_format` | No | `1` legacy or `2` stable `ok/summary/data/proposal/error` envelope. Default `1`. |
+| `strict` | No | Reject unknown config keys. Default `true`. |
+| `storage` | Local | Local SQLite ledger. |
+| `sources` | Local | Named Postgres/MySQL source wiring. |
+| `trusted_context` | Conditional | Default trusted tenant/principal binding. |
+| `contexts` | No | Named trusted contexts referenced by capabilities/contracts. |
+| `contracts` | No | Portable contract file paths. Preferred for reviewed authoring. |
+| `capabilities` | Conditional | Embedded compatibility capabilities; may be `[]` with `contracts`. |
+| `policies` | No | Embedded reviewed policies; contract policies merge into the same catalog. |
+| `approvals` | No | Local approval overrides. |
+| `executors` | No | App-owned writeback wiring. |
+| `cloud` | Cloud mode | Scoped Cloud adapter configuration. |
+
+## Path resolution
+
+- `contracts` entries resolve relative to the directory containing the config
+  file. Every command uses this rule, including audit, validate, doctor, tools,
+  smoke, MCP serve, propose, and apply.
+- `storage.sqlite_path` is resolved by the Runner process working directory.
+  Pass an absolute path when an MCP client launches Runner from another CWD.
+- Executor paths/URLs come from environment variables, not relative contract
+  content.
+
+## Storage
+
+```json
+{ "storage": { "sqlite_path": "./.synapsor/local.db" } }
+```
+
+The ledger stores proposals, visible evidence copies, query audit, approvals,
+receipts, events, and replay. New POSIX stores are owner-only (`0600`). Protect
+the file like a database extract; see [Store Lifecycle](store-lifecycle.md).
+
+## Sources
+
+```json
+{
+  "sources": {
+    "billing_postgres": {
+      "engine": "postgres",
+      "read_url_env": "BILLING_POSTGRES_READ_URL",
+      "write_url_env": "BILLING_POSTGRES_WRITE_URL",
+      "read_only": false,
+      "statement_timeout_ms": 3000
+    }
+  }
+}
+```
+
+`engine` is `postgres` or `mysql`. `read_url_env` is required. Use a
+least-privilege read credential. `write_url_env` is optional unless direct SQL
+writeback must apply; it should name a separate restricted writer. `read_only:
+true` forbids direct SQL writeback. `statement_timeout_ms` is a positive read
+timeout. `ssl` carries adapter-specific reviewed SSL options when used.
+
+A contract's `SOURCE billing_postgres` must exactly match a `sources` key.
+
+## Trusted context
+
+```json
+{
+  "trusted_context": {
+    "provider": "environment",
+    "values": {
+      "tenant_id_env": "SYNAPSOR_TENANT_ID",
+      "principal_env": "SYNAPSOR_PRINCIPAL"
+    }
+  }
+}
+```
+
+Providers are `environment`, `static_dev`, `http_claims`, and `cloud_session`.
+`static_dev` is only for local fixtures. Named `contexts` use the same shape.
+Capabilities may reference a context by name. The model never receives tenant
+or principal as an overridable argument.
+
+## Contracts and embedded capabilities
+
+```json
+{
+  "contracts": ["./billing.contract.json"],
+  "capabilities": []
+}
+```
+
+Contracts are normalized `@synapsor/spec` JSON. Runner merges their contexts,
+capabilities, and policies into one runtime catalog. Duplicate names across
+embedded config and contracts fail; there is no silent shadowing.
+
+Embedded capabilities remain supported for generated/legacy configs. Their
+fields are documented in the JSON Schema and
+[Capability Authoring](capability-authoring.md): fixed target, args, primary-key
+lookup, visible fields, evidence, patch allowlist, bounds/transitions, conflict
+guard, approval, and writeback mode.
+
+## Executors
+
+```json
+{
+  "executors": {
+    "billing_handler": {
+      "type": "http_handler",
+      "url_env": "BILLING_HANDLER_URL",
+      "method": "POST",
+      "auth": {
+        "type": "bearer_env",
+        "token_env": "BILLING_HANDLER_TOKEN"
+      },
+      "signing_secret_env": "BILLING_HANDLER_SIGNING_SECRET",
+      "timeout_ms": 5000
+    }
+  }
+}
+```
+
+Types are `sql_update`, `http_handler`, and `command_handler`. HTTP handlers use
+`url_env`, optional `POST|PUT|PATCH`, bearer auth, signing secret, and timeout.
+Command handlers use `command_env` and timeout. Secrets stay in the environment.
+See [Writeback Executors](writeback-executors.md).
+
+## Policies and approvals
+
+`policies` is an array of reviewed policy objects. Local approval policies use
+`kind: "approval"` and numeric rules such as `{ "field": "amount_cents",
+"max": 2500 }`. `approvals.disable_auto_approval: true` disables local policy
+auto-approval without changing the reviewed contract. Approval never becomes an
+MCP tool.
+
+## Cloud mode
+
+Cloud mode omits local sources/capabilities and requires:
+
+```json
+{
+  "version": 1,
+  "mode": "cloud",
+  "cloud": {
+    "base_url_env": "SYNAPSOR_CLOUD_BASE_URL",
+    "runner_token_env": "SYNAPSOR_RUNNER_TOKEN",
+    "adapter_id": "mcp.billing",
+    "runner_id": "runner_local_1",
+    "project_id": "project_123",
+    "engines": ["postgres"],
+    "capabilities": ["adapter:read", "adapter:invoke"],
+    "session": {}
+  }
+}
+```
+
+`base_url_env`, `runner_token_env`, and `adapter_id` are required. Optional keys
+are `runner_id`, `runner_version`, `project_id`, `source_id`, `engines`, scoped
+capability permissions, and trusted session metadata.
+
+## Direct SQL readiness
+
+An administrator must apply `writeback migration` once. The steady-state writer
+needs target-table SELECT/allowed UPDATE plus receipt-table
+SELECT/INSERT/UPDATE; it does not need schema CREATE.
+
+```bash
+synapsor-runner writeback migration --engine postgres --schema synapsor
+synapsor-runner writeback grants --engine postgres \
+  --schema synapsor --writer-role synapsor_writer
+synapsor-runner doctor --config ./synapsor.runner.json --check-writeback
+```
+
+The doctor probe uses a rolled-back receipt insert and target-table check. It
+does not mutate business rows.

package/docs/security-boundary.md

@@ -66,11 +66,11 @@ outside the model-facing MCP server and verifies:
 If any authority check cannot be verified, the write fails closed.
 
 For direct SQL writeback, the writer connection is the env var named by the
-source `write_url_env` in `synapsor.runner.json`. Direct SQL writeback also
-creates or writes `synapsor_writeback_receipts` for idempotency and replay, so
-the writer needs permission for that receipt table or an administrator must
-pre-create and grant it. If your database policy forbids Runner-managed receipt
-tables, use an app-owned `http_handler` or `command_handler` executor instead.
+source `write_url_env` in `synapsor.runner.json`. Direct SQL writeback writes an
+administrator-created `synapsor_writeback_receipts` table for idempotency and
+replay. The writer needs `SELECT`/`INSERT`/`UPDATE` on that table, but not schema
+`CREATE`. If your database policy forbids the receipt table, use an app-owned
+`http_handler` or `command_handler` executor instead.
 
 When a capability uses an `http_handler` or `command_handler` executor, the
 same approval boundary applies. The runner sends a structured proposal/job

package/docs/store-lifecycle.md

@@ -9,6 +9,44 @@ Default path:
 ./.synapsor/local.db
 ```
 
+## Data sensitivity and permissions
+
+The ledger contains copies of the business fields allowed by each capability:
+visible before/after evidence, proposal diffs, actor/tenant metadata, query
+fingerprints, approvals, receipts, and replay events. Treat it like a scoped
+database extract, not disposable cache data.
+
+Runner creates new POSIX store files with owner-only mode `0600` and tightens an
+owned existing store when it opens it. On Windows, use the operating system's
+file ACLs. Use encrypted disks, restrict OS accounts, and set a retention policy
+appropriate for the visible business data.
+
+`KEEP OUT` fields and redacted query parameters are not written to normal
+evidence records. They do not make the rest of the ledger non-sensitive.
+
+Direct SQLite inspection is supported **read-only** for independent verification:
+
+```bash
+sqlite3 -readonly ./.synapsor/local.db '.tables'
+```
+
+Do not mutate the database directly. Its internal tables may change between
+releases and are not a public storage API; use Runner commands for automation.
+
+## Inspect the ledger
+
+| Question | Command |
+| --- | --- |
+| What did the model propose? | `synapsor-runner proposals show <proposal-id> --details` |
+| What data supported it? | `synapsor-runner evidence list --proposal <proposal-id>` then `evidence show <evidence-id> --details` |
+| What query was run? | `synapsor-runner query-audit list --proposal <proposal-id>` |
+| Who approved or rejected it? | `synapsor-runner proposals show <proposal-id> --details` |
+| Did guarded writeback apply? | `synapsor-runner receipts list --proposal <proposal-id>` |
+| What happened end to end? | `synapsor-runner replay show --proposal <proposal-id> --details` |
+| What happened to one object? | `synapsor-runner activity search --object invoice:INV-3001` |
+| What are the latest events? | `synapsor-runner events tail` |
+| How large is the store? | `synapsor-runner store stats --store ./.synapsor/local.db` |
+
 ## Server leases
 
 MCP server modes write a small lease file next to the store:

package/docs/writeback-executors.md

@@ -65,9 +65,9 @@ npx -y -p @synapsor/runner synapsor-runner writeback grants --engine postgres --
 ```
 
 `writeback doctor --check-db` connects with the configured writer credential and
-checks the receipt table path. That check can create the receipt table if the
-writer has `CREATE`, so run it only against staging/disposable databases or
-after reviewing the printed migration/grants.
+checks the pre-created receipt table path in a rolled-back transaction. Apply
+the printed migration as an administrator first; the steady-state writer needs
+table `SELECT`/`INSERT`/`UPDATE`, not schema `CREATE`.
 
 ## `http_handler`