@synapsor/runner 0.1.0-alpha.4 → 0.1.0-alpha.6

package/docs/schema-inspection.md

@@ -1,88 +0,0 @@
-# Schema Inspection
-
-`synapsor inspect` reads database metadata so you can choose a
-narrow reviewed capability without writing an entire runner config by hand.
-
-Use the public `synapsor ...` runner CLI. From a source checkout, use
-`./bin/synapsor ...` if the global binary is not linked yet.
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor inspect \
-  --engine auto \
-  --from-env SYNAPSOR_DATABASE_READ_URL \
-  --schema public
-```
-
-JSON output:
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor inspect \
-  --engine mysql \
-  --from-env SYNAPSOR_DATABASE_READ_URL \
-  --schema app \
-  --json
-```
-
-## What It Reads
-
-The inspector collects metadata only:
-
-- engine and server version;
-- current database user;
-- schemas/databases visible to the credential;
-- tables and views;
-- columns, types, nullability, defaults, and generated status;
-- primary keys;
-- unique constraints;
-- foreign keys;
-- index summaries;
-- best-effort table writability from object type;
-- suggested tenant columns;
-- suggested conflict/version columns;
-- suggested sensitive or large/binary fields.
-
-It does not sample normal business rows by default.
-
-## Suggestions Are Not Authority
-
-Tenant, conflict, sensitive-field, and default-visible-column suggestions are
-heuristics. You must review them before generating or serving a capability.
-
-Suggested tenant column names include:
-
-```text
-tenant_id, account_id, organization_id, org_id, workspace_id, customer_id
-```
-
-Suggested conflict/version columns include:
-
-```text
-updated_at, modified_at, row_version, version, lock_version, etag
-```
-
-Likely sensitive fields include names containing:
-
-```text
-password, secret, token, api_key, private_key, session, cookie, ssn,
-credit_card, card_number, cvv, refresh_token, oauth
-```
-
-Binary/blob/vector columns are excluded from generated default visible columns.
-
-## Safety Behavior
-
-- Use a read-only database credential.
-- Pass the connection through an environment variable name, not a command-line
-  URL.
-- Inspection opens read-only transactions where supported.
-- Inspection applies statement timeouts.
-- Inspection does not issue DDL or DML.
-- Errors are sanitized to avoid printing connection strings.
-
-## Next Step
-
-Use the inspection result to create `onboarding-selection.json`, then run:
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor init --spec onboarding-selection.json --non-interactive
-```

package/docs/shadow-mode.md

@@ -1,67 +0,0 @@
-# Shadow Mode
-
-Shadow mode lets you evaluate autonomy before allowing writes.
-
-The model can create proposals and evidence, but the source database is never
-mutated. A human continues doing the real work in the application. You can then
-record what the human actually did and compare it to the agent proposal.
-
-Run a shadow config:
-
-```json
-{
-  "mode": "shadow"
-}
-```
-
-List shadow proposals:
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor shadow list --store ./.synapsor/local.db
-```
-
-Record the human action:
-
-```bash
-cat > human-action.json <<'JSON'
-{
-  "late_fee_cents": 0,
-  "waiver_reason": "customer requested review"
-}
-JSON
-
-npx -y -p @synapsor/runner@alpha synapsor shadow record-human-action wrp_123 \
-  --store ./.synapsor/local.db \
-  --patch human-action.json \
-  --actor human_operator \
-  --notes "matched support lead decision"
-```
-
-Compare:
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor shadow compare wrp_123 --store ./.synapsor/local.db
-```
-
-Report:
-
-```bash
-npx -y -p @synapsor/runner@alpha synapsor shadow report --store ./.synapsor/local.db
-```
-
-The report counts:
-
-- total shadow proposals;
-- proposals with human actions;
-- exact matches;
-- partial matches;
-- mismatches;
-- proposals with no human action yet.
-
-Use this path to move gradually:
-
-```text
-read-only -> shadow proposals -> human-reviewed commits -> policy-approved commits later
-```
-
-This goal does not add policy auto-approval.

package/docs/telemetry.md

@@ -1,28 +0,0 @@
-# Telemetry
-
-Local mode does not send telemetry to Synapsor Cloud.
-
-By default, Synapsor Runner local commands do not upload:
-
-- schema metadata;
-- table names;
-- database rows;
-- prompts;
-- proposal contents;
-- credentials or database URLs;
-- usage data.
-
-Cloud communication occurs only after an explicit Cloud action, such as
-`synapsor cloud connect`, or when a config uses `mode: "cloud"`.
-
-The local MCP server keeps database credentials in the local environment. MCP
-client snippets reference the local command and store path; they must not
-include database URLs or passwords.
-
-Cloud mode may exchange documented control-plane metadata for runner
-registration, heartbeats, tool catalogs, proposal/job leases, result reporting,
-and replay/audit workflows. Cloud mode must remain testable and must not upload
-database credentials.
-
-If a future feature adds opt-in telemetry, it must be documented, disabled by
-default for local mode, and must not include secrets or row payloads.

package/docs/threat-model.md

@@ -1,25 +0,0 @@
-# Threat Model
-
-## Boundary
-
-Synapsor Runner is the local trusted writeback boundary. The write credential stays in the customer environment. Synapsor Cloud sends approved structured jobs, not database URLs, passwords, raw SQL, prompts, or model confidence.
-
-## Threats covered
-
-- Compromised or prompt-injected model: runner ignores prompts and accepts only structured approved jobs.
-- Malicious model arguments: target, tenant, allowed columns, conflict guard, and idempotency key come from Synapsor proposal state.
-- Over-broad proposal target: runner requires primary key and tenant guard.
-- Compromised runner token: token is scoped to one source and limited to configured runner permissions such as adapter read/invoke, runner heartbeat, job claim, and result reporting; it does not grant approval or arbitrary SQL authority.
-- Replayed job: receipt table makes applied retries idempotent.
-- Concurrent runners: receipt row and target row are locked inside a transaction.
-- Stale row/version conflict: version-column mismatch returns `conflict`.
-- Tenant mismatch: missing target row under tenant guard returns conflict and does not write.
-- Multi-row impact: affected rows must equal one.
-- Database outage mid-transaction: transaction rolls back and reports failed.
-- Control-plane outage after commit: receipt table allows safe idempotent result retry.
-- Log leakage: default logs redact tokens and database URLs.
-- Dependency compromise: CI, lockfile review, and dependency audit are release gates.
-
-## Limitations
-
-The current alpha does not support arbitrary SQL, inserts, deletes, DDL, stored procedures, multi-row updates, cross-database transactions, automatic schema changes, or a self-hosted Synapsor control plane.

package/docs/trusted-context.md

@@ -1,70 +0,0 @@
-# Trusted Context
-
-Trusted context is the data Synapsor Runner uses as authority but does not allow
-the model to choose freely.
-
-Examples:
-
-- tenant ID;
-- principal/user ID;
-- role;
-- environment or workspace scope.
-
-In local mode, the supported provider is environment binding:
-
-```json
-{
-  "trusted_context": {
-    "provider": "environment",
-    "values": {
-      "tenant_id_env": "SYNAPSOR_TENANT_ID",
-      "principal_env": "SYNAPSOR_PRINCIPAL"
-    }
-  }
-}
-```
-
-For larger configs, use named contexts so each capability says which trusted
-binding it uses:
-
-```json
-{
-  "contexts": {
-    "local_support_operator": {
-      "provider": "environment",
-      "values": {
-        "tenant_id_env": "SYNAPSOR_TENANT_ID",
-        "principal_env": "SYNAPSOR_PRINCIPAL"
-      }
-    }
-  },
-  "capabilities": [
-    {
-      "name": "support.inspect_ticket",
-      "context": "local_support_operator"
-    }
-  ]
-}
-```
-
-Backward compatibility: `trusted_context` still works as the global fallback.
-If a capability names `context`, that named context is used for that capability.
-If a capability does not name `context`, the global `trusted_context` is used.
-Config validation fails when a capability references a missing named context.
-
-At runtime:
-
-```bash
-export SYNAPSOR_TENANT_ID="acme"
-export SYNAPSOR_PRINCIPAL="local_operator"
-```
-
-The model may pass business identifiers such as `invoice_id` or `ticket_id`.
-Those identifiers are validated inside the trusted tenant scope.
-
-The model must not pass `tenant_id`, principal, role, or authorization scope as
-ordinary authority arguments. If a tool schema appears to require those fields
-from the model, treat it as a bug.
-
-Cloud mode may bind trusted context from Cloud runner/session context, but
-database credentials still stay local.