@synapsor/runner 1.6.1 → 1.6.3

package/docs/supervised-automatic-apply.md

@@ -0,0 +1,267 @@
+# Operator-Supervised Automatic Apply
+
+Synapsor separates two decisions that are often incorrectly combined:
+
+1. Who or what may approve a proposal?
+2. Who or what may execute an approved proposal?
+
+The model answers neither question. It supplies a bounded request through a
+reviewed capability. Human-reviewed policy may approve that exact immutable
+proposal, and a separately operated Runner worker may apply it only after
+revalidating the complete guarded-write boundary.
+
+Supervised automatic apply is additive and disabled by default. Upgrading does
+not start a worker, change existing `AUTO APPROVE` behavior, or apply an
+already-approved proposal.
+
+## The Four Supported Modes
+
+| Approval | Execution | Behavior |
+| --- | --- | --- |
+| Human | Manual | Default: a qualified operator approves and explicitly runs `apply`. |
+| Human | Supervised worker | A qualified operator approves; the trusted worker may apply. |
+| Policy auto-approval | Manual | Reviewed policy approves; an operator still runs `apply`. This is the legacy `AUTO APPROVE` behavior. |
+| Policy auto-approval | Supervised worker | Reviewed policy approves; an independently enabled worker may guardedly apply. |
+
+The default remains human approval plus manual apply.
+
+## Dual Opt-In
+
+Automatic execution requires both:
+
+1. Contract permission, included in the canonical contract digest.
+2. Deployment permission for the exact capability and exact active digest.
+
+Public DSL (Domain-Specific Language):
+
+```sql
+CREATE CAPABILITY billing.propose_small_credit
+  ...
+  AUTO APPROVE WHEN amount_cents <= 2500
+  LIMIT 20 PER DAY
+  ALLOW SUPERVISED WORKER APPLY;
+```
+
+The final clause compiles to:
+
+```json
+{
+  "execution": {
+    "supervised_worker": "allowed"
+  }
+}
+```
+
+That permission alone applies nothing. The operator must separately configure
+an exact deployment allowlist:
+
+```json
+{
+  "supervised_worker": {
+    "enabled": true,
+    "profile": "production",
+    "capabilities": [
+      {
+        "capability": "billing.propose_small_credit",
+        "contract_digest": "sha256:REPLACE_WITH_THE_ACTIVE_DIGEST",
+        "mode": "supervised_worker",
+        "concurrency": 1,
+        "queue_limit": 100,
+        "lease_seconds": 60,
+        "max_attempts": 5,
+        "proposal_ttl_seconds": 3600,
+        "rate_limit": {
+          "executions": 20,
+          "window_seconds": 60
+        },
+        "write_url_env": "BILLING_POSTGRES_WRITE_URL",
+        "worker_identity": "billing_worker",
+        "control_role": "runner_operator",
+        "require_least_privilege_writer": true,
+        "writer_posture_fingerprint": "sha256:REPLACE_WITH_REVIEWED_POSTURE_DIGEST"
+      }
+    ]
+  }
+}
+```
+
+Use environment-variable names in config, never database URLs or credentials.
+Production also requires verified `signed_key` or `jwt_oidc` operator identity
+for worker controls.
+
+If either opt-in is absent, stale, revoked, or mismatched, the proposal remains
+unapplied. Enabling the worker globally does not enable another capability or a
+new contract version.
+
+## Initial Eligible Write Shapes
+
+The hardened supervised path is intentionally narrower than manual apply. It
+accepts only direct-SQL, single-row proposal capabilities whose complete effect
+Runner can validate:
+
+- `UPDATE` with trusted tenant scope and an exact non-weak conflict/version
+  guard;
+- `INSERT` with trusted tenant scope and a reviewed deterministic
+  deduplication key.
+
+It currently refuses:
+
+- `DELETE`;
+- reversible actions;
+- bounded-set and other multi-row writes;
+- app-owned executors or external effects;
+- arbitrary or model-generated SQL;
+- a missing trusted tenant boundary;
+- an unavailable receipt authority;
+- a shared, privileged, owner, `BYPASSRLS`, or otherwise unverifiable writer
+  when hardened posture is required.
+
+These operations remain available through their documented manual review/apply
+or app-owned executor paths. The narrower worker eligibility does not remove
+existing Runner write capabilities.
+
+## What The Worker Rechecks
+
+Immediately before leasing and applying, Runner rechecks:
+
+- proposal state, immutable hash, version, approval, expiry, and exact active
+  contract digest;
+- contract permission, deployment allowlist, worker identity, control state,
+  profile, generation lock, and current approval-policy snapshot;
+- trusted tenant and principal scope;
+- target row and required supporting-evidence freshness;
+- current source version and exact reviewed before-state;
+- operation, allowed columns, bounds, transitions, row count, and expected
+  effect;
+- approval and execution count/value limits under concurrency;
+- writer credential separation, least-privilege posture, grants, and
+  PostgreSQL RLS posture where configured;
+- operation identity, deduplication, receipt authority, and active lease.
+
+A policy-approved proposal does not gain permanent authority. If the target row
+or mandatory supporting evidence changes before execution, the worker fails
+closed with the established conflict/freshness outcome. A refreshed diff is a
+new proposal with a new hash and needs its own approval.
+
+Manual and supervised execution converge on the same guarded apply
+implementation. The queue is durable work coordination, not a second mutation
+engine.
+
+## Run And Operate The Worker
+
+Validate first:
+
+```bash
+synapsor-runner config validate --config ./synapsor.runner.json
+synapsor-runner doctor --config ./synapsor.runner.json
+```
+
+Run one supervised claim:
+
+```bash
+synapsor-runner worker run --supervised --once --yes \
+  --worker-id billing_worker \
+  --config ./synapsor.runner.json
+```
+
+Run continuously:
+
+```bash
+synapsor-runner worker run --supervised --yes \
+  --worker-id billing_worker \
+  --config ./synapsor.runner.json
+```
+
+Inspect without copying proposal IDs:
+
+```bash
+synapsor-runner worker status --config ./synapsor.runner.json
+synapsor-runner attention show --config ./synapsor.runner.json
+```
+
+Operator controls:
+
+```bash
+synapsor-runner worker pause --yes --config ./synapsor.runner.json
+synapsor-runner worker resume --yes --config ./synapsor.runner.json
+synapsor-runner worker drain --yes --config ./synapsor.runner.json
+
+synapsor-runner worker disable billing.propose_small_credit \
+  --digest sha256:EXACT_DIGEST --yes --config ./synapsor.runner.json
+synapsor-runner worker enable billing.propose_small_credit \
+  --digest sha256:EXACT_DIGEST --yes --config ./synapsor.runner.json
+synapsor-runner worker revoke billing.propose_small_credit \
+  --digest sha256:EXACT_DIGEST --yes --config ./synapsor.runner.json
+```
+
+`revoke` is terminal for that digest. Pause, drain, disable, and revoke stop new
+leasing but preserve queued proposals and durable history. They do not interrupt
+a transaction that already committed.
+
+Dead-letter recovery remains explicit and identity-verified:
+
+```bash
+synapsor-runner worker dead-letter list --config ./synapsor.runner.json
+synapsor-runner worker dead-letter show wrp_... --config ./synapsor.runner.json
+synapsor-runner worker dead-letter requeue wrp_... --retry-budget 3 --yes \
+  --config ./synapsor.runner.json --identity alice --identity-key ./alice.pem
+```
+
+Use the secured Workbench for the same queue, pause/drain, exact-digest,
+dead-letter, and reconciliation controls.
+
+## Retry And Crash Boundary
+
+Runner may retry only a classified transient failure with a proven non-commit
+outcome. Version conflict, stale authority, scope failure, limit failure,
+validation failure, and receipt mismatch do not retry automatically.
+
+Delivery may repeat; mutation must not. Worker leases are fenced, and source
+operation identity plus receipts prevent duplicate effects.
+
+When the database outcome is unknown, Runner does not guess:
+
+- source-receipt mode resolves a known committed operation from the source-side
+  receipt;
+- genuinely ambiguous runner-ledger outcomes enter
+  `reconciliation_required`;
+- automatic retry stops until a verified operator inspects and resolves the
+  established reconciliation record.
+
+This is safe retry and explicit ambiguity handling, not a claim of distributed
+exactly-once execution.
+
+## Optional Supervision-Health Gate
+
+An exact capability policy may name `required_attention_sinks`:
+
+```json
+{
+  "required_attention_sinks": ["operations"]
+}
+```
+
+When present, the worker leaves eligible work queued until every named,
+enabled sink has a healthy delivery record. Sink health never approves a
+proposal and never bypasses either execution opt-in. This gate is off unless a
+capability explicitly names required sinks.
+
+See [Human Attention And Notifications](human-attention-notifications.md) for
+quiet defaults, signed webhooks, routing, and the Workbench inbox.
+
+## Accurate Model-Facing Claim
+
+Without supervised execution:
+
+> This call creates a proposal and does not change the source database.
+
+With exact supervised execution enabled:
+
+> This call creates a proposal. If it satisfies the reviewed automatic-approval
+> policy, a separately trusted Runner worker may automatically apply it without
+> a per-request human click. The model cannot approve, apply, start the worker,
+> or change that policy.
+
+The model can therefore cause a bounded request to enter a pre-authorized
+production pipeline. It still cannot choose the authority, approve the
+proposal, control the worker, or commit a mutation directly.

package/docs/troubleshooting-first-run.md

@@ -12,6 +12,41 @@ Use JSON for automation:
 npx -y -p @synapsor/runner synapsor-runner doctor --first-run --json
 ```
 
+## Guided Recovery Contract
+
+Runner 1.6.3 failures should tell you what failed, why the boundary stopped,
+what state remains, and one next action. Do not delete the project or add
+`--force` merely to recover.
+
+| Failure | State preserved | One next action |
+| --- | --- | --- |
+| Database connection or metadata inspection failed | Existing project/review files and source rows | Fix the exported URL/network without printing the credential, then rerun `npx -y @synapsor/runner@latest start --from-env DATABASE_URL`. |
+| Read role is writable, owner, superuser, `BYPASSRLS`, or unverifiable | Disabled metadata draft; no source-row Explore | Supply a verifiably SELECT-only non-owner staging role, then rerun the same `start` command. |
+| Schema or project choice is ambiguous | Existing files; no authority activation | Rerun with the exact reviewed schema, for example `npx -y @synapsor/runner@latest start --from-env DATABASE_URL --schema public`. |
+| Tenant or principal scope is unresolved | Conservative blocked resource decisions | Open the same Workbench URL and resolve the highlighted scope exception. |
+| Sensitive field remains unresolved | Field stays kept out; active tools unchanged | Open Workbench **Exceptions** and record one reviewed field decision. |
+| Row identifier is missing/composite/ambiguous | Resource remains blocked | Select a source-proven single-column primary/unique identity or keep the resource blocked. |
+| Trusted context environment is missing | Boundary and ledger remain intact; query did not run | Export the named tenant/principal variable locally, then rerun the displayed Try action. |
+| Generated output already exists | Existing files are not overwritten | Rerun the original `start` command and choose **Resume existing review**. |
+| Generation lock is stale | Existing active named capability and review history | Run `synapsor-runner boundary diff --json`, then choose **Rescan and review changes**. |
+| Config JSON is malformed | Config and source database are unchanged | Correct the reported file/line/column, then run `synapsor-runner config validate --config ./synapsor.runner.json --json`. |
+| Config mode is missing/invalid | Config and source database are unchanged | Set `mode` to `read_only`, `shadow`, `review`, or `cloud`, then rerun `synapsor-runner config validate --json`. |
+| Config contains an unknown field | Config and source database are unchanged | Remove or correct the reported JSON path, then rerun `synapsor-runner config validate --json`. |
+| Workbench port is occupied | Review files, ledger, and source database | Rerun `synapsor-runner ui --open`; the default selects a free loopback port. |
+| Writeback setup fails | Config and reviewed plan; transactional setup rolls back | Rerun `synapsor-runner writeback setup --profile staging --json` and review the reported prerequisite. |
+| Writer role/setup URL is missing | No DDL or grant was applied | Rerun the preview with `--writer-role <role> --setup-url-env <ADMIN_URL_ENV>`. |
+| No supported write candidate exists | Read boundary remains active; no write authority | Use **Add a safe action** on a writable base table with a proven identity/version field, or retain read-only mode. |
+| MCP client installation is unavailable | Project and reviewed authority; client config unchanged | Run `synapsor-runner mcp config --absolute-paths` and use the generic stdio snippet manually. |
+| Supervised work remains queued | Approved proposal and queue state; source unchanged | Run `synapsor-runner worker status --json`, then follow its exact digest, posture, policy, freshness, limit, pause, or required-sink finding. |
+| Required attention sink is unhealthy | Approved proposal remains queued; no source mutation | Repair the operator-owned sink, run `synapsor-runner notifications test --sink <id>`, then dispatch and let the worker revalidate from the beginning. |
+| Notification delivery is dead-lettered | Authoritative event and proposal state are preserved | Repair/test the sink, then run `synapsor-runner notifications replay latest --yes --reason "sink repaired"` with the configured verified operator identity; this resends only the redacted event. |
+| Apply outcome is UNKNOWN | Intent, receipt evidence, and queue state are preserved | Open the latest critical attention item and use the verified reconciliation flow; never rerun the mutation blindly. |
+
+For machine output, a process-level failure emits one redacted JSON object to
+stdout and diagnostics to stderr. `recovery.source_database_changed` is `null`
+when a generic exception cannot establish an operation-specific mutation
+outcome; inspect the durable receipt/reconciliation state rather than guessing.
+
 ## Fresh Start Did Not Enter Auto Boundary
 
 Auto Boundary is the default only for a fresh interactive `start --from-env`

package/examples/fitflow-guided-onboarding/README.md

@@ -0,0 +1,43 @@
+# FitFlow Guided Onboarding Fixture
+
+FitFlow is a synthetic multi-tenant fitness application used to verify the
+Runner 1.6.3 first-time developer journey.
+
+Its live PostgreSQL schema contains 41 relations: six seeded core relations,
+34 realistic surrounding application subsystems, and one readiness marker.
+The broader catalog proves that review by exception can narrow a real
+application-sized schema to a small active agent pack without blind bulk
+approval.
+
+The fixture deliberately separates two reviewed authority packs:
+
+- `organization_analytics`: organization-scoped, aggregate-only analysis over
+  check-ins and locations;
+- `trainer_members`: exact member reads and proposal-first member updates,
+  restricted to the assigned trainer.
+
+The source includes planted fields that must never become visible by default:
+`payment_method`, `home_address`, and `medical_waiver_notes`.
+
+The PostgreSQL fixture provides separate roles:
+
+- `fitflow_analytics_reader`: read-only, organization-scoped analytics;
+- `fitflow_trainer_reader`: read-only, organization and trainer scoped;
+- `fitflow_writer`: guarded member updates under the same trusted scope;
+- `fitflow_setup`: development/staging receipt-table setup only.
+
+Start the database:
+
+```bash
+docker compose up -d --wait postgres
+```
+
+Use the organization analytics role for the first onboarding journey:
+
+```bash
+export DATABASE_URL='postgresql://fitflow_analytics_reader:fitflow_analytics_reader_password@127.0.0.1:55463/fitflow'
+export SYNAPSOR_TENANT_ID='org-fitflow'
+npx -y @synapsor/runner@latest start --from-env DATABASE_URL
+```
+
+Use only synthetic data. The fixture is not a production deployment template.

package/examples/fitflow-guided-onboarding/app/page.tsx

@@ -0,0 +1,8 @@
+export default function FitFlowOverview() {
+  return (
+    <main>
+      <h1>FitFlow operations</h1>
+      <p>Synthetic member, trainer, class, and check-in data for Synapsor onboarding tests.</p>
+    </main>
+  );
+}

package/examples/fitflow-guided-onboarding/docker-compose.yml

@@ -0,0 +1,16 @@
+services:
+  postgres:
+    image: postgres:16
+    environment:
+      POSTGRES_DB: fitflow
+      POSTGRES_USER: fitflow_admin
+      POSTGRES_PASSWORD: fitflow_admin_password
+    ports:
+      - "127.0.0.1:55463:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "test \"$(psql -U fitflow_admin -d fitflow -tAc \"SELECT pg_postmaster_start_time() > initialized_at FROM public.synapsor_fixture_ready LIMIT 1\" 2>/dev/null | xargs)\" = t"]
+      interval: 1s
+      timeout: 3s
+      retries: 40
+    volumes:
+      - ./seed/postgres.sql:/docker-entrypoint-initdb.d/001-schema.sql:ro

package/examples/fitflow-guided-onboarding/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "synapsor-fitflow-guided-onboarding",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev"
+  },
+  "dependencies": {
+    "@prisma/client": "^6.0.0",
+    "next": "^15.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "prisma": "^6.0.0",
+    "typescript": "^5.8.0"
+  }
+}

package/examples/fitflow-guided-onboarding/prisma/schema.prisma

@@ -0,0 +1,98 @@
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model Organization {
+  id        String     @id
+  name      String
+  locations Location[]
+  trainers  Trainer[]
+  members   Member[]
+  classes   Class[]
+  checkIns  CheckIn[]
+
+  @@map("organizations")
+}
+
+model Location {
+  id             String       @id
+  organizationId String       @map("organization_id")
+  name           String
+  region         String
+  organization   Organization @relation(fields: [organizationId], references: [id])
+  members        Member[]
+  classes        Class[]
+  checkIns       CheckIn[]
+
+  @@unique([organizationId, name])
+  @@map("locations")
+}
+
+model Trainer {
+  id             String       @id
+  organizationId String       @map("organization_id")
+  displayName    String       @map("display_name")
+  organization   Organization @relation(fields: [organizationId], references: [id])
+  members        Member[]
+  classes        Class[]
+
+  @@map("trainers")
+}
+
+model Member {
+  id                  String       @id
+  organizationId      String       @map("organization_id")
+  locationId          String       @map("location_id")
+  assignedTrainerId   String       @map("assigned_trainer_id")
+  membershipStatus    String       @map("membership_status")
+  membershipTier      String       @map("membership_tier")
+  loyaltyBalance      Int          @map("loyalty_balance")
+  version             Int
+  paymentMethod       String       @map("payment_method")
+  homeAddress         String       @map("home_address")
+  medicalWaiverNotes  String       @map("medical_waiver_notes")
+  organization        Organization @relation(fields: [organizationId], references: [id])
+  location            Location     @relation(fields: [locationId], references: [id])
+  assignedTrainer     Trainer      @relation(fields: [assignedTrainerId], references: [id])
+  checkIns            CheckIn[]
+
+  @@index([organizationId, assignedTrainerId])
+  @@map("members")
+}
+
+model Class {
+  id             String       @id
+  organizationId String       @map("organization_id")
+  locationId     String       @map("location_id")
+  trainerId      String       @map("trainer_id")
+  classType      String       @map("class_type")
+  startsAt       DateTime     @map("starts_at") @db.Timestamptz(6)
+  organization   Organization @relation(fields: [organizationId], references: [id])
+  location       Location     @relation(fields: [locationId], references: [id])
+  trainer        Trainer      @relation(fields: [trainerId], references: [id])
+  checkIns       CheckIn[]
+
+  @@map("classes")
+}
+
+model CheckIn {
+  id             String       @id
+  organizationId String       @map("organization_id")
+  locationId     String       @map("location_id")
+  memberId       String       @map("member_id")
+  classId        String       @map("class_id")
+  outcome        String
+  checkedInAt    DateTime     @map("checked_in_at") @db.Timestamptz(6)
+  organization   Organization @relation(fields: [organizationId], references: [id])
+  location       Location     @relation(fields: [locationId], references: [id])
+  member         Member       @relation(fields: [memberId], references: [id])
+  fitnessClass   Class        @relation(fields: [classId], references: [id])
+
+  @@index([organizationId, checkedInAt])
+  @@map("check_ins")
+}