@synapsor/runner 1.6.2 → 1.6.3

package/docs/guided-onboarding.md

@@ -0,0 +1,331 @@
+# Guided Onboarding: Database To First Safe Tool
+
+This is the shortest path from an existing staging Postgres/MySQL database to
+one useful agent tool. It requires no Synapsor account, Cloud login, database
+replication, global install, MCP host, model API key, or hand-authored config,
+DSL, JSON, SQL, DDL, or grants.
+
+## The One-Minute Mental Model
+
+Synapsor is creating the small set of database powers your agent may use. It
+does not give the agent SQL access.
+
+- Reads return only fields a human reviewed, under tenant and principal scope
+  supplied outside model arguments.
+- Scoped Explore is a temporary local development/staging authoring tool.
+- Protect turns one useful analysis into a narrow named capability.
+- A model-facing write call creates an exact proposal. It does not commit.
+- The model cannot activate authority, approve a proposal, or apply a write.
+- A trusted operator or worker rechecks the effect and records a receipt.
+
+## Before You Start
+
+Use a disposable or staging database and a dedicated SELECT-only, non-owner
+credential. Keep row-level security, restricted views, or tenant-bound
+credentials underneath Runner where available.
+
+Export credentials in the launching shell. Do not put their values in project
+files or chat:
+
+```bash
+export DATABASE_URL='<staging read-only URL>'
+export SYNAPSOR_TENANT_ID='<staging tenant>'
+export SYNAPSOR_PRINCIPAL='<staging principal>'
+```
+
+Runner requires Node 22.13 or newer.
+
+## One Command To Workbench
+
+Run this from an empty project directory or your application root:
+
+```bash
+npx -y @synapsor/runner@latest start --from-env DATABASE_URL
+```
+
+The command automatically:
+
+1. checks the database and credential posture;
+2. inspects schema metadata without sampling source rows;
+3. statically reads supported Prisma, Drizzle, OpenAPI, and existing Synapsor
+   definitions when present;
+4. drafts disabled public DSL, canonical JSON, tests, and a generation lock;
+5. creates a valid zero-authority Runner config and local SQLite ledger;
+6. validates every generated artifact;
+7. opens one secured loopback Workbench URL.
+
+Before human activation, the agent has no generated authority and no source row
+has been read.
+
+Running the same command again resumes. Resume and Try do not rescan, rewrite
+files, or change a digest. Rescan and destructive Start over remain explicit
+human choices.
+
+## Five Minutes: First Safe Read
+
+Workbench starts with an overview, not a permission matrix. It shows:
+
+- database and framework evidence found;
+- resources inspected;
+- fields already kept out;
+- unresolved sensitive fields;
+- row identity;
+- tenant and principal scope;
+- database-role and RLS posture;
+- ready and blocked capabilities.
+
+Review only the exceptions. Routine conservative defaults are already applied.
+There is no global “approve everything” control.
+
+For each selected resource, confirm the exact primary/unique row identity,
+trusted scope, visible fields, kept-out fields, and any aggregate-only fields.
+Then sign the displayed digest. Changing a reviewed decision creates a new
+disabled digest.
+
+Choose **Try first safe read**. Runner calls the real local runtime and shows:
+
+```text
+Your first safe tool is working.
+
+Tool: <domain>.inspect_<resource>
+Agent can see: <reviewed fields>
+Agent cannot see: <kept-out fields>
+Tenant scope: trusted outside model arguments
+Principal scope: trusted outside model arguments
+Source database changed: no
+```
+
+CLI fallback:
+
+```bash
+npx -y @synapsor/runner@latest try call --list --format json
+npx -y @synapsor/runner@latest try call <returned-tool-name> --sample --json
+```
+
+The second command is for an activated named tool with valid generated sample
+input. It does not invent tenant or principal values.
+
+## Ten Minutes: Explore And Protect
+
+Scoped Explore is available only after its exact local authoring boundary is
+activated. It is absent from production, unknown-profile, remote, shared HTTP,
+and non-loopback `tools/list`.
+
+In Workbench, choose **Ask an aggregate question**. Select only reviewed
+resources, dimensions, measures, filters, and time buckets. No SQL or plan JSON
+is required.
+
+The first release supports bounded:
+
+- `count` and reviewed `count_distinct`;
+- `sum` and `avg` over reviewed numeric measures;
+- reviewed categorical dimensions;
+- day, week, and month buckets;
+- typed filters and bounded top-N;
+- at most one reviewed many-to-one relationship.
+
+Minimum cohorts, group limits, response limits, query limits, extraction
+budgets, and anti-differencing budgets are fixed by the activated boundary.
+Small groups are suppressed. Results describe changes or contributors; they do
+not prove causation.
+
+CLI fallback for the Workbench-suggested aggregate:
+
+```bash
+npx -y @synapsor/runner@latest try explore --suggested --json
+```
+
+Choose **Protect this analysis** directly on the successful result. Runner
+freezes its reviewed resources, measures, grouping, time bucket, ordering,
+scope, suppression, and limits into:
+
+```text
+synapsor/protected/drafts/<namespace>__<name>/capability.synapsor.sql
+synapsor/protected/drafts/<namespace>__<name>/synapsor.contract.json
+synapsor/protected/drafts/<namespace>__<name>/contract-tests.json
+```
+
+The capability remains disabled until a human activates its exact digest.
+Disabling Scoped Explore does not remove the protected named capability.
+
+CLI fallback, without copying an opaque query handle:
+
+```bash
+npx -y @synapsor/runner@latest try protect \
+  --name analytics.reviewed_weekly_summary \
+  --json
+```
+
+## Fifteen Minutes: First Proposal
+
+After the first read, choose **Add a safe action**. Schema metadata supplies
+structure, never business permission. The human specifies:
+
+1. the business action;
+2. target resource and exact row identity;
+3. fields that may change;
+4. allowed values, transitions, and numeric bounds;
+5. trusted tenant and principal scope;
+6. conflict/version guard;
+7. approval role;
+8. optional small bounded auto-approval;
+9. per-operation and daily limits;
+10. optional reviewed compensation.
+
+Runner generates public DSL, canonical JSON, tests, an exact-effect preview,
+and a disabled action. Unsupported or unsafe combinations fail closed. In
+particular, DELETE, bounded-set, quorum, auto-approval, and reversibility cannot
+be combined beyond what the canonical DSL supports.
+
+After exact-digest human activation, call the named proposal tool in Workbench
+or through the host-neutral Try path. The result must say:
+
+```text
+Proposal created.
+Source database changed: no.
+The model cannot approve or apply this proposal.
+```
+
+Inspect the latest lifecycle without copying a proposal ID:
+
+```bash
+npx -y @synapsor/runner@latest lifecycle --details
+```
+
+Approval and apply stay outside MCP:
+
+```bash
+npx -y @synapsor/runner@latest proposals approve latest --yes
+npx -y @synapsor/runner@latest apply latest
+npx -y @synapsor/runner@latest lifecycle show latest --details
+```
+
+Production should use a verified signed-key or OIDC operator identity rather
+than unverified development identity. See [Approval Roles And Verified
+Operator Identity](approval-roles-and-operator-identity.md).
+
+These commands show the default human-approval/manual-apply path. A production
+operator can separately opt an eligible action into exact-digest supervised
+execution. That does not give the model an apply tool: the model creates a
+bounded proposal, reviewed policy may approve it, and a separately trusted
+worker repeats all guards before any later source mutation. Existing
+`AUTO APPROVE` contracts remain manual-apply unless both opt-ins are present.
+See [Operator-Supervised Automatic
+Apply](supervised-automatic-apply.md).
+
+## Guarded Development Writeback Setup
+
+Preview is always the default:
+
+```bash
+npx -y @synapsor/runner@latest writeback setup \
+  --profile staging \
+  --json
+```
+
+The response contains one immutable plan digest and exact setup SQL, objects,
+grants, receipt mode, and next action.
+
+- `runner_ledger`: no Synapsor receipt table or receipt grant is added to the
+  source database.
+- `source_db` + `auto_migrate`: verifies the configured idempotent first-use
+  path using the trusted writer.
+- `source_db` + `precreated`: requires a separate setup/admin URL environment
+  name and exact steady-state writer role.
+- app-owned handlers receive no unnecessary source receipt setup.
+
+DDL apply is refused for missing, unknown, or production profiles. In
+development/staging, it requires the exact displayed confirmation:
+
+```bash
+npx -y @synapsor/runner@latest writeback setup \
+  --profile staging \
+  --writer-role '<steady-state-writer-role>' \
+  --setup-url-env SYNAPSOR_SETUP_DATABASE_URL \
+  --apply \
+  --confirm 'APPLY WRITEBACK SETUP sha256:<reviewed-plan-digest>'
+```
+
+Never reuse the model/read credential as the elevated setup connection.
+
+## Connect An MCP Client
+
+Workbench generates ready-to-copy Cursor, Claude, Codex, and generic stdio
+snippets for the same reviewed authority. Stdio opens no network listener and
+needs no HTTP bearer credential.
+
+Render the generic snippet:
+
+```bash
+npx -y @synapsor/runner@latest mcp config --absolute-paths
+```
+
+Preview a project-scoped Cursor change:
+
+```bash
+npx -y @synapsor/runner@latest mcp install cursor --project --dry-run
+```
+
+No client config contains database URLs, trusted scope values, approval,
+activation, apply, or revert authority.
+
+## Machine-Readable Output
+
+Commands that support machine output write exactly one JSON value to stdout.
+Operational logs and diagnostics use stderr:
+
+```bash
+npx -y @synapsor/runner@latest try explore --suggested --json | jq -e .
+```
+
+On a process-level failure, JSON output uses:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "COMMAND_REJECTED",
+    "message": "Safe redacted explanation"
+  },
+  "recovery": {
+    "state_preserved": "What remains intact",
+    "source_database_changed": null,
+    "next_action": "One exact next action"
+  }
+}
+```
+
+`null` means Runner cannot honestly infer the source mutation outcome from a
+generic command exception. Operation-specific receipts and reconciliation
+states remain authoritative.
+
+## Before And After
+
+The earlier manual path could require roughly thirteen disconnected steps:
+inspect, compile, create config, validate, doctor, initialize a store, start
+Workbench, generate MCP config, create receipt DDL/grants, run a smoke call,
+approve, and apply.
+
+The guided path through the first proposal uses:
+
+- one public shell command;
+- deliberate Workbench review and activation;
+- no manual file edits;
+- no external documentation search;
+- no Cursor requirement.
+
+The packed FitFlow gate records the exact command count, human decisions, and
+timings in `development/runner-1.6.3-fitflow-results.json`.
+
+## Visual Reference
+
+Repository screenshots cover desktop, mobile, light, dark, loading, blocked,
+stale, failure, empty Protect, and unavailable-action states:
+
+- [Desktop overview](https://github.com/Synapsor/Synapsor-Runner/blob/main/development/runner-1.6.3-visual/workbench-overview-desktop-light.png)
+- [Mobile overview](https://github.com/Synapsor/Synapsor-Runner/blob/main/development/runner-1.6.3-visual/workbench-overview-mobile-light.png)
+- [Blocked identity review](https://github.com/Synapsor/Synapsor-Runner/blob/main/development/runner-1.6.3-visual/workbench-blocked-identity.png)
+- [Stale/failure recovery](https://github.com/Synapsor/Synapsor-Runner/blob/main/development/runner-1.6.3-visual/workbench-keyboard-stale-failure.png)
+
+For common blocked states and one-action recovery commands, use
+[Troubleshooting First Run](troubleshooting-first-run.md).

package/docs/human-attention-notifications.md

@@ -0,0 +1,367 @@
+# Human Attention And Notifications
+
+Runner keeps the full lifecycle in its ledger and secured Workbench. External
+notifications are a quiet interruption channel for meaningful human attention,
+not a copy of every state transition.
+
+Notifications are additive, local-first, and disabled by default. Runner needs
+no webhook, network connection, Cloud account, or continuously running
+dispatcher for its existing proposal, approval, apply, receipt, and replay
+flows.
+
+## Architecture
+
+```text
+authoritative ledger transition
+  -> immutable attention event in the same store transaction
+  -> coalesced Human Attention item
+  -> separately operated dispatcher
+  -> configured JSONL or signed webhook sink
+  -> authenticated human opens Workbench
+  -> existing approval/recovery control handles the item
+```
+
+An event informs. It never authorizes. A webhook response, delivery receipt,
+inbox acknowledgement, or notification replay cannot activate a capability,
+approve a proposal, apply a write, cancel work, or resolve an unknown database
+outcome.
+
+SQLite and shared PostgreSQL runtime stores retain the same event identities,
+attention projection, acknowledgement, and delivery state.
+
+## Quiet Default
+
+Under the default route, successful activity remains visible in the ledger,
+Workbench timeline, CLI, metrics, and optional digest, but does not interrupt a
+human.
+
+No immediate external notification is sent by default for:
+
+- proposal creation, policy auto-approval, approval, or queueing;
+- a worker lease or individual retry;
+- successful manual or automatic apply;
+- an isolated conflict that Runner handled safely;
+- planned worker start, pause, resume, drain, or stop;
+- capability activation by the same operator.
+
+Immediate delivery defaults to states where timely attention matters:
+
+- human approval required;
+- UNKNOWN transaction outcome or reconciliation required;
+- dead-letter work;
+- sustained worker-health failure;
+- queue depth/age crossing an operator threshold;
+- schema drift or stale digest blocking authority;
+- invalidated writer credential posture;
+- critical policy/limit failure;
+- an approved proposal approaching expiry while action is still possible.
+
+Informational success events can be sent only through an explicit all-events
+route or periodic digest.
+
+## Events And Attention Items
+
+Events are immutable audit facts. Attention items are durable incident
+projections over related events.
+
+For example, ten proposals requiring the same role can produce ten immutable
+events but one item saying that ten proposals need review. Repeated worker
+failures, queue backlog, or the same schema-drift condition update one item and
+its occurrence count. Retry attempts stay internal until the configured
+attempt/duration threshold is crossed.
+
+Attention states are:
+
+- `open`;
+- `acknowledged`;
+- `resolved`;
+- `expired`.
+
+Acknowledgement means only that a verified operator saw the item. It is not
+approval or resolution.
+
+## Configure Sinks
+
+This operator-owned config enables one signed webhook and one optional
+development JSONL stream:
+
+```json
+{
+  "notifications": {
+    "enabled": true,
+    "workbench_url_env": "SYNAPSOR_WORKBENCH_URL",
+    "sinks": [
+      {
+        "id": "operations",
+        "type": "webhook",
+        "enabled": true,
+        "url_env": "SYNAPSOR_NOTIFY_WEBHOOK_URL",
+        "signing_secret_env": "SYNAPSOR_NOTIFY_SIGNING_SECRET",
+        "minimum_severity": "warning",
+        "events": [
+          "proposal.review_required",
+          "worker.dead_lettered",
+          "worker.unknown_outcome",
+          "worker.reconciliation_required",
+          "schema.drift_detected"
+        ],
+        "capabilities": ["billing.propose_small_credit"],
+        "environments": ["staging", "production"],
+        "delivery": "immediate",
+        "max_attempts": 5,
+        "timeout_ms": 3000,
+        "max_response_bytes": 1024,
+        "replay_window_seconds": 300,
+        "allow_private_destinations": false,
+        "recovery_notifications": false,
+        "budgets": {
+          "per_minute": 10,
+          "per_hour": 100,
+          "immediate_informational_per_hour": 0,
+          "aggregation_window_seconds": 300,
+          "cooldown_seconds": 600,
+          "max_unresolved_reminders": 3,
+          "digest_cadence_minutes": 1440,
+          "escalation_delay_seconds": 60,
+          "retry_attempt_threshold": 3,
+          "degraded_duration_seconds": 120,
+          "queue_depth_threshold": 100,
+          "queue_age_seconds": 300
+        },
+        "quiet_hours": {
+          "start_utc_hour": 22,
+          "end_utc_hour": 7
+        }
+      },
+      {
+        "id": "development",
+        "type": "jsonl",
+        "enabled": false,
+        "destination": "stdout",
+        "minimum_severity": "informational",
+        "delivery": "all"
+      }
+    ]
+  }
+}
+```
+
+Set values only in the operator environment:
+
+```bash
+export SYNAPSOR_WORKBENCH_URL=https://runner-ops.example.internal
+export SYNAPSOR_NOTIFY_WEBHOOK_URL=https://events.example.com/synapsor
+export SYNAPSOR_NOTIFY_SIGNING_SECRET='at-least-32-random-bytes'
+```
+
+The config stores environment-variable names, not URLs or secrets. Events never
+contain credentials, database URLs, SQL, source rows, aggregate group results,
+kept-out fields, trusted tenant/principal values, sensitive arguments, or
+authority tokens.
+
+## Route By Destination
+
+Every sink has its own event, severity, capability, environment, and delivery
+route. A practical split is:
+
+| Sink | Route |
+| --- | --- |
+| Workbench | Complete event and attention history |
+| Team chat webhook | Review-required and operational warnings |
+| Incident webhook | UNKNOWN, reconciliation, dead letter, sustained worker failure |
+| Email-provider webhook | Daily digest |
+| Audit webhook | Explicit all-events redacted stream |
+
+The ledger and Workbench remain the source of truth.
+
+## Operate Without Copying IDs
+
+Inspect the highest-priority item:
+
+```bash
+synapsor-runner attention list --config ./synapsor.runner.json
+synapsor-runner attention show --config ./synapsor.runner.json
+```
+
+Use `attention show <attention_id>` only when selecting a specific item. JSON
+automation is available with `--json`.
+
+Acknowledgement is explicit:
+
+```bash
+synapsor-runner attention acknowledge --actor alice \
+  --config ./synapsor.runner.json
+```
+
+Production acknowledgement follows configured verified operator identity and is
+cryptographically bound to the exact item digest and occurrence.
+
+Inspect and test delivery:
+
+```bash
+synapsor-runner notifications status --config ./synapsor.runner.json
+synapsor-runner notifications test --sink operations \
+  --config ./synapsor.runner.json
+synapsor-runner notifications dispatch --sink operations --limit 20 \
+  --config ./synapsor.runner.json
+```
+
+`notifications test` sends an unmistakable synthetic event containing no
+database or proposal data. Opening Workbench, installing Runner, and starting
+MCP never start outbound delivery.
+
+Requeue one dead-letter delivery:
+
+```bash
+synapsor-runner notifications replay latest --yes \
+  --reason "Webhook repaired and synthetic test passed" \
+  --config ./synapsor.runner.json
+```
+
+This replays only the immutable redacted notification. It does not replay an
+approval or database mutation. Replay is an operator recovery action and
+requires the configured `signed_key` or `jwt_oidc` identity. Runner binds the
+verified decision to the exact delivery revision and records a redacted
+immutable `notification.replayed` audit event.
+
+## Webhook Contract
+
+Runner sends a CloudEvents 1.0 structured JSON body with content type
+`application/cloudevents+json`. Important headers are:
+
+```text
+X-Synapsor-Event-Id
+X-Synapsor-Timestamp
+X-Synapsor-Signature-Version: v1
+X-Synapsor-Signature: sha256=<hex HMAC>
+```
+
+The HMAC-SHA-256 input is the UTF-8 string
+`v1.<timestamp>.<event-id>.<exact-body>`. Receivers must:
+
+1. Require signature version `v1`.
+2. Reject timestamps outside the configured replay window.
+3. Verify the HMAC with a timing-safe comparison.
+4. Deduplicate the stable event ID.
+5. Return only a bounded transport acknowledgement.
+
+Runner ignores response content. A receiver cannot return a command.
+
+A minimal Node receiver can verify the exact bytes before parsing JSON:
+
+```js
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+export function verifySynapsorWebhook(rawBody, headers, secret, now = Date.now()) {
+  const eventId = headers["x-synapsor-event-id"];
+  const timestamp = headers["x-synapsor-timestamp"];
+  const version = headers["x-synapsor-signature-version"];
+  const suppliedHeader = headers["x-synapsor-signature"];
+  if (!eventId || !timestamp || version !== "v1" || !suppliedHeader?.startsWith("sha256=")) {
+    return false;
+  }
+
+  const timestampSeconds = Number(timestamp);
+  const ageMs = Math.abs(now - timestampSeconds * 1000);
+  if (!Number.isSafeInteger(timestampSeconds) || ageMs > 300_000) return false;
+
+  const expected = Buffer.from(
+    createHmac("sha256", secret)
+      .update(`v1.${timestamp}.${eventId}.${rawBody}`, "utf8")
+      .digest("hex"),
+    "hex",
+  );
+  const supplied = Buffer.from(suppliedHeader.slice("sha256=".length), "hex");
+  return expected.length === supplied.length && timingSafeEqual(expected, supplied);
+}
+```
+
+Read the request as raw UTF-8 bytes for verification; reserializing parsed JSON
+changes the signed body. Store the event ID for at least the replay window and
+reject a duplicate before processing it.
+
+The structured body resembles:
+
+```json
+{
+  "specversion": "1.0",
+  "id": "aev_...",
+  "type": "ai.synapsor.worker.reconciliation_required",
+  "source": "urn:synapsor:runner:production",
+  "time": "2026-07-25T00:00:00.000Z",
+  "datacontenttype": "application/json",
+  "subject": "billing.propose_small_credit",
+  "data": {
+    "schema_version": "synapsor.notification.v1",
+    "severity": "critical",
+    "environment": "production",
+    "capability": "billing.propose_small_credit",
+    "contract_digest": "sha256:...",
+    "summary": "A guarded apply needs operator reconciliation.",
+    "workbench_url": "https://runner-ops.example.internal/attention/att_..."
+  }
+}
+```
+
+The Workbench URL identifies an item but carries no approval or recovery
+authority. The operator must authenticate normally.
+
+HTTPS is required by default. Redirects and unsafe loopback, link-local,
+metadata, multicast, unspecified, private, and rebinding destinations are
+refused. Intentional private destinations require both
+`allow_private_destinations: true` and an exact `private_host_allowlist`.
+
+## Delivery And Noise Guarantees
+
+Delivery is at least once. Sink-specific records use atomic leases, fencing,
+bounded retries, jittered backoff, timeout, maximum attempts, and dead-letter
+state. Repeated delivery cannot repeat proposal authority or source mutation.
+
+When a non-critical budget is exhausted, Runner preserves every event, updates
+the Workbench item, and suppresses or batches external messages. Critical events
+bypass ordinary quiet hours and budgets but still coalesce under a separate
+bounded emergency ceiling.
+
+Optional digests report redacted counts for proposals, auto-approval, apply,
+review-required work, conflicts, retries, dead letters, limits, queue age, and
+unresolved critical items. They link to authenticated Workbench detail.
+
+Recovery messages are off by default. When an incident resolves, Workbench is
+updated; an external recovery message is sent only when that sink explicitly
+enables `recovery_notifications` or the critical-route policy requires it.
+
+## Retry And Dead-Letter Runbook
+
+1. Run `notifications status --json` and inspect sink health, pending delivery,
+   and dead-letter counts.
+2. Open the corresponding Workbench attention item. Confirm the authoritative
+   proposal/worker state before changing delivery.
+3. Repair the operator-owned destination, DNS policy, TLS, or secret rotation.
+4. Send `notifications test --sink <id>`; it contains no database data.
+5. Run `notifications dispatch --sink <id> --limit 20` to drain eligible work.
+6. Replay a dead-letter delivery only with
+   `notifications replay <delivery_id> --yes --reason "<why replay is safe>"`.
+
+Replay preserves the original immutable event ID. It cannot re-run the database
+operation. The exact recovery decision must be verified through the configured
+operator identity. A still-failing sink remains observable and does not rewrite
+the underlying proposal outcome.
+
+## Supervised Worker Health Gate
+
+An exact supervised-worker capability may list:
+
+```json
+{
+  "required_attention_sinks": ["operations"]
+}
+```
+
+If every required sink is unhealthy or untested, an otherwise eligible
+policy-approved production write remains queued. Workbench explains that
+operator visibility is unavailable. A healthy sink does not approve anything;
+after recovery, the worker still repeats every ordinary digest, policy, scope,
+freshness, limit, credential, lease, and guarded-write check.
+
+See [Operator-Supervised Automatic
+Apply](supervised-automatic-apply.md) for the execution boundary.