@synapsor/runner 1.4.12 → 1.4.122

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## 1.4.122 (prepared, not published)
+
+### Trusted principal row scope and Cloud-linked governance
+
+- Adds a canonical reviewer-fixed principal row scope that is always
+  AND-composed with tenant scope and resolved only from a required trusted
+  context binding. Missing or invalid principal authority fails closed.
+- Enforces the bound principal predicate in PostgreSQL and MySQL reads,
+  proposals, aggregates, guarded CRUD, bounded sets, executor envelopes,
+  receipts, replay, and reviewed compensation. Same-tenant cross-principal
+  access uses the same generic miss as cross-tenant or absent rows.
+- Preserves the scope through DSL parse/format/compile, Spec validation and
+  digesting, config normalization, protocol jobs, C++/Cloud round trips,
+  contract explanation/testing, and scoped evidence/proposal/resource handles.
+- Adds explicit `local_only` and `cloud_linked` authority behavior. Cloud-linked
+  proposals use a durable idempotent outbox, metadata-only evidence residency,
+  Cloud-governed approval/leasing, terminal-state reconciliation, and no local
+  approval/apply fallback while Cloud is unavailable.
+- Separates contract-registry human/service credentials from Runner machine
+  tokens. Cloud push no longer accepts secrets through command arguments or a
+  Runner-token fallback.
+- Introduces the separately packable `@synapsor/cli@0.1.0-beta.1` Cloud client;
+  `synapsor-runner` remains the local MCP/database enforcement boundary.
+- Stages `@synapsor/spec@1.4.2`, `@synapsor/dsl@1.4.3`, and
+  `@synapsor/runner@1.4.122`. Nothing is published by this change.
+
+## 1.4.121 (prepared, not published)
+
+### Contract trust surface and bounded-set parser correctness
+
+- Fixes BUG-018: `SELECT WHERE risk_level = 'high' AND case_status =
+  'active'` now compiles into two ordered canonical equality terms instead of
+  silently folding the second term into the first string value.
+- Uses a quote-aware, full-clause parser. `AND` inside a quoted literal remains
+  literal content, while malformed terms, trailing tokens, `OR`, parentheses,
+  and non-equality operators fail during DSL compilation with location-aware
+  errors.
+- Preserves existing single-term contracts and literal types. The canonical
+  Spec bump in this release is limited to the additive enum and aggregate-read
+  fields described below.
+- Adds standalone DSL and bundled Runner parity coverage plus PostgreSQL/MySQL
+  live proof under source-database and Runner-ledger receipt authority. The
+  proof excludes first-term-only, second-term-only, and wrong-tenant rows and
+  verifies exact receipt/replay membership.
+- Adds a real stdio contract language server plus canonical `contract explain`
+  and deterministic text/JSON/SARIF lint for review before serving.
+- Adds adopter-owned static/live contract tests with a public manifest schema,
+  generic operator-boundary checks, and disposable PostgreSQL/MySQL coverage.
+- Adds tenant-scoped object/principal ledger reports in JSON, Markdown, and PDF
+  with redaction, canonical digests, optional operator signatures, and tamper
+  verification.
+- Adds typed DSL enums and canonical fixed aggregate reads for COUNT/SUM/AVG.
+  Aggregate tools use trusted tenant scope, fixed equality selection, mandatory
+  minimum-group suppression, one scalar result, and evidence/query audit with
+  no member rows or IDs.
+- Adds disabled-by-default graduated-trust recommendations. Evaluation uses
+  scoped human-reviewed outcomes, excludes auto-approval as independent
+  evidence, requires verified operator review, and exports a separate
+  digest-bound contract artifact without activating it.
+- Proves additive Spec/DSL/Runner/C++ aggregate and enum parity, shared Postgres
+  recommendation durability, and transient PostgreSQL/MySQL timeout
+  classification.
+- Stages `@synapsor/spec@1.4.1`, `@synapsor/dsl@1.4.2`, and
+  `@synapsor/runner@1.4.121`. Nothing is published by this change.
+
 ## 1.4.12 (prepared, not published)
 
 ### Runtime-store smoke-call consistency

package/README.md

@@ -14,9 +14,8 @@ surface.
 
 ## Prove It In 60 Seconds
 
-The path is: **audit** your existing MCP risk, then **demo** the safety
-boundary, then **connect** a staging database. The first two commands finish in
-seconds and touch nothing but a local fixture file.
+Path: **audit** MCP risk, **demo** the boundary, then **connect** staging. The
+first two commands touch only a local fixture.
 
 First, inspect the risk in a typical raw-SQL database MCP server. This works
 even if you never adopt Runner:
@@ -25,18 +24,16 @@ even if you never adopt Runner:
 npx -y @synapsor/runner audit --example dangerous-db-mcp
 ```
 
-Then point the same static review at your own exported tool manifest, remote
-`tools/list` endpoint, or stdio MCP server:
+Audit your own tool manifest, remote `tools/list`, or stdio server:
 
 ```bash
 npx -y @synapsor/runner audit ./tools-list.json
 ```
 
-The audit flags raw SQL, arbitrary table/column inputs, model-controlled tenant
-or principal authority, model-facing approval/writeback tools, and missing
-conflict or idempotency signals. It does not call business tools, and it is a
-risk review rather than proof that a server is secure. See [MCP Database Risk
-Review](docs/mcp-audit.md) for remote, stdio, JSON, and Markdown workflows.
+It flags raw SQL, arbitrary identifiers, model-controlled authority,
+model-facing approval/writeback, and missing conflict or idempotency signals.
+It does not call business tools. See [MCP Database Risk
+Review](docs/mcp-audit.md) for supported workflows and limits.
 
 Then see the proposal, approval boundary, evidence, and replay loop. It needs no
 database, Docker, config file, MCP client, or Synapsor account:
@@ -78,36 +75,25 @@ approval, apply, or revert tools. A human or trusted operator approves outside
 MCP, then Runner performs a guarded write or routes the proposal to an
 app-owned executor.
 
-The distinction is the complete boundary, not a read-only toggle or a generic
-approve/reject prompt:
-
-- reviewed contracts constrain tools, tenant context, visible and writable
-  columns, numeric bounds, transitions, and approval requirements;
-- proposals separate model intent from commit authority, including aggregate
-  auto-approval ceilings where configured;
-- evidence, query audit, idempotency receipts, and replay preserve what was
-  inspected, requested, approved, and applied.
-
-Runner supports bounded deployments when its documented database, identity,
-ledger, backup, and operational controls are satisfied. It does not make raw
-SQL tools, host infrastructure, or prompt-injection-prone clients safe.
+Contracts constrain tools, trusted context, visible and writable columns,
+bounds, transitions, and approvals. Proposals separate model intent from commit
+authority; evidence, query audit, receipts, and replay preserve the reviewed
+lifecycle. Runner does not make raw SQL tools, hosts, or
+prompt-injection-prone clients safe.
 
 ## Why Not Just Use A Prompt And App Code?
 
-Prompt instructions can guide behavior, but prompt-only enforcement is not an
-authorization boundary. First ask who produces the SQL:
+Prompts are not an authorization boundary. First ask who produces the SQL:
 
-- **The model produces SQL:** your validator must safely understand arbitrary
-  queries, scope, and side effects. That is `execute_sql` with an extra parser.
+- **The model produces SQL:** validation must understand arbitrary queries,
+  scope, and side effects. That is `execute_sql` behind a parser.
 - **Trusted app code produces fixed, parameterized SQL:** good. You have built
   a semantic tool, and that may be enough for a small read-only application.
 
-Runner becomes useful when those tools also need one reviewed contract for
-trusted tenant scope, field controls, evidence, approval outside MCP, guarded
-and idempotent writeback, receipts, replay, and reviewed compensation. Use your
-own code when you do not need that lifecycle. Read the [full build-vs-adopt
-guide](docs/why-synapsor-vs-app-guardrails.md) for the decision table, public
-incident evidence, and regulated-data boundaries.
+Runner adds one reviewed contract for trusted scope, field controls, evidence,
+approval outside MCP, guarded writeback, receipts, replay, and compensation.
+Use your own code when you do not need that lifecycle. See the [build-vs-adopt
+guide](docs/why-synapsor-vs-app-guardrails.md).
 
 ## Connect A Staging Database
 
@@ -177,6 +163,23 @@ bounded inverse; `synapsor-runner revert <proposal_id>` creates a separately
 approved proposal. This is not rollback, time travel, or app-owned
 compensation.
 
+## Review And Prove Your Contract
+
+Before serving a contract, use `contract explain` for a reviewer-readable
+boundary, `contract lint --strict` for deterministic CI checks, and `contract
+test` for adopter-owned allow/deny/redaction cases. The built-in language
+server supplies diagnostics, completion, hover, and formatting for
+`.synapsor.sql` and legacy `.synapsor` files. See [Contract
+Review](docs/contract-review.md) and [Contract
+Testing](docs/contract-testing.md).
+
+Runner also supports reviewed [aggregate reads](docs/aggregate-reads.md),
+tenant-scoped tamper-evident [ledger reports](docs/compliance-reports.md), and
+opt-in [graduated-trust recommendations](docs/graduated-trust.md). Aggregate
+tools return one scalar and no source rows. Graduated trust is disabled by
+default, remains operator-only, and can export a reviewable artifact but never
+activate it.
+
 ## Trust And Verification
 
 Start with the **[Threat Model](THREAT_MODEL.md)**. It defines protected assets,
@@ -185,9 +188,16 @@ trust boundaries, covered threats, non-goals, and required operator controls.
 - [Conformance fixtures](docs/conformance.md) prove trusted context, scoped
   reads, kept-out fields, proposal boundaries, approval, receipts, and replay
   behavior rather than only validating JSON shape.
+- `contract test` lets adopters encode the same boundary checks for their own
+  synthetic fixtures; it never invokes an LLM and refuses remote live targets
+  by default.
 - MCP proposal, evidence, and replay handles are references rather than bearer
   authority: resource reads re-check the owning tenant and principal against
   the current trusted session.
+- Same-tenant owner/assignee isolation uses a reviewed
+  [`PRINCIPAL SCOPE KEY`](docs/capability-authoring.md#same-tenant-principal-row-scope)
+  composed with mandatory tenant scope; `test:principal-scope` proves generic
+  cross-principal denial and evidence-handle isolation on Postgres and MySQL.
 - `test:live-apply`, `test:guarded-crud`, `test:bounded-set`, and
   `test:reversible` run disposable PostgreSQL/MySQL scenarios. They prove no
   pre-approval mutation, guarded single-row CRUD, idempotent retry,
@@ -204,30 +214,14 @@ See [Security Boundary](docs/security-boundary.md) and
 
 ## Operate The Approval Loop
 
-Reviewed policies combine per-proposal and daily ceilings; exceeding one routes
-the proposal to human review. Operators use `apply --all-approved --yes`,
-Prometheus metrics, structured logs, and optional signed reviewer/apply roles.
-Shared Postgres ledger mirror mode is available for bounded operator handoffs,
-and `storage.shared_postgres.mode = "runtime_store"` lets MCP serving use
-Postgres as the primary proposal/evidence/replay store with bounded CLI
-approval/apply/worker commands bridged through the same ledger. Local SQLite
-remains the default. See
-[Production](docs/production.md) and the
-[Runner Config Reference](docs/runner-config-reference.md).
-
-`smoke call` honors `runtime_store`: artifacts go to shared Postgres; failures
-never fall back to SQLite. `--store` is compatibility plumbing. Requires
-`1.4.12`+.
-
-For a small multi-tenant fleet, bind every capability context to verified HTTP
-claims, use `jwt_asymmetric` session auth, and share a bounded Postgres
-`runtime_store`. Never assume a global `http_claims` setting overrides an
-environment-bound contract context; Runner rejects that contradiction before
-serving tools. Load balancers should use dependency-free `/healthz` for
-liveness and `/readyz` for source/ledger/writeback readiness. The tested
-two-Runner topology, pool/rate-limit budgets, metrics, backup/restore,
-dead-letter, and rolling-upgrade rules are in
-[Running A Small Runner Fleet](docs/running-a-runner-fleet.md).
+Policies combine per-proposal and daily ceilings; exceeding one routes to human
+review. Operators get batch apply, metrics, structured logs, and optional
+signed roles. Local SQLite is the default; bounded fleets can use verified HTTP
+claims, asymmetric JWT sessions, and a shared Postgres `runtime_store`.
+`smoke call` follows that store and never falls back to SQLite. Use `/healthz`
+for liveness and `/readyz` for dependency readiness. See
+[Production](docs/production.md), [Runner Config](docs/runner-config-reference.md),
+and [Small Runner Fleets](docs/running-a-runner-fleet.md).
 
 ## Packages
 
@@ -236,6 +230,7 @@ dead-letter, and rolling-upgrade rules are in
 | `@synapsor/runner` | CLI, MCP runtime, local ledger, proposals, approval, guarded writeback, replay, and MCP audit. |
 | `@synapsor/spec` | Canonical portable contracts for contexts, capabilities, workflows, evidence, proposals, receipts, and replay. |
 | `@synapsor/dsl` | SQL-like authoring that compiles contexts, capabilities, and workflow declarations into canonical contract JSON. |
+| `@synapsor/cli` | Synapsor Cloud administration, contract governance, human review, Runner connections, and shared audit records. |
 
 Runner executes locally. The spec is shared by Runner and Cloud/C++; the DSL
 is its reviewable source format. Start with [Capability
@@ -255,12 +250,20 @@ deployments: your database remains the source of truth and Runner stores review
 artifacts in the default local SQLite ledger or an opt-in shared Postgres
 runtime store.
 Synapsor Cloud adds a shared contract registry, immutable versions,
-downloadable Runner bundles, and team activity, evidence, and approval
-surfaces. See [OSS Runner vs Synapsor Cloud](docs/oss-vs-cloud.md) for the
-detailed boundary.
+source-scoped Runner connections, downloadable bundles, a human approval
+inbox, durable leased writeback jobs, and a redacted shared activity/receipt
+chronology. Database credentials and guarded execution remain local. See [Cloud
+Mode](docs/cloud-mode.md) for the design-partner path and [OSS Runner vs
+Synapsor Cloud](docs/oss-vs-cloud.md) for the detailed boundary.
+
+`synapsor-runner` owns the local MCP/database boundary. `synapsor` from
+`@synapsor/cli` manages Cloud review and audit. Both Cloud push commands use
+the same contract digest and scoped service-key API. See the [Cloud CLI
+guide](https://github.com/Synapsor/Synapsor-Runner/blob/main/docs/cloud-cli.md).
 
 ## Next Steps
 
+- Follow the [step-by-step Synapsor Tutorial](https://github.com/sandeshtiwari/Synapsor-Tutorial).
 - Run the [`support-plan-credit` flagship example](examples/support-plan-credit).
 - Connect [Claude, Cursor, OpenAI Agents SDK, or another MCP client](docs/mcp-clients.md).
 - Author and [push a validated contract to Cloud](docs/cloud-push.md).

package/THREAT_MODEL.md

@@ -50,6 +50,12 @@ idempotency boundary for effects.
 - Model asks for arbitrary SQL: no generic SQL tool is exposed in the Synapsor path.
 - Model supplies `tenant_id`, `principal`, source id, allowed columns, row version, or approval identity: runner rejects trusted-binding overrides.
 - Prompt injection in database content asks the model to bypass policy: the runner ignores text as authority and only accepts structured capability/job state.
+- Aggregate inference through a one-record group: reviewed aggregate tools
+  require minimum-group suppression and never return member rows or IDs. This
+  reduces, but does not eliminate, statistical inference risk.
+- Policy self-expansion from favorable automated outcomes: graduated trust is
+  off by default, excludes auto-approvals from human evidence, requires a
+  verified operator decision, and exports without activation.
 - Wrong tenant or object: reads and writes include trusted primary-key and tenant predicates.
 - Disallowed field update: patch columns must be allowlisted.
 - Stale row: conflict guard mismatch returns `conflict` instead of silently writing.

package/dist/cli.d.ts

@@ -14,6 +14,9 @@ export declare function runInitWizard(args: string[], options?: {
     stdout?: Pick<NodeJS.WriteStream, "write">;
 }): Promise<number>;
 export declare function resolveSqlWriteDatabaseUrl(job: WritebackJob, configPath: string, env: NodeJS.ProcessEnv): Promise<string>;
+export declare function verifyLocalWritebackAuthority(job: WritebackJob, configPath: string, storePath?: string, options?: {
+    cloudApproved?: boolean;
+}): Promise<void>;
 export declare function reconciliationSupportedOutcome(observation: ReconciliationObservation): "applied" | "conflict" | "failed";
 export declare function reconciliationReceipt(intent: StoredWritebackIntent, observation: ReconciliationObservation, outcome: "applied" | "conflict" | "failed", runnerId: string, reason: string): ExecutionReceiptV2 | ExecutionReceiptV3 | ExecutionReceiptV4;
 export {};

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAYA,OAAO,EAAoP,KAAK,WAAW,EAA0H,MAAM,6BAA6B,CAAC;AAIza,OAAO,EAgBL,KAAK,qBAAqB,EAK3B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAgI,KAAK,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,KAAK,kBAAkB,EAAuD,KAAK,YAAY,EAAwB,MAAM,2BAA2B,CAAC;AAElV,OAAO,EAQL,KAAK,gBAAgB,EAEtB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAUL,KAAK,yBAAyB,EAE/B,MAAM,8BAA8B,CAAC;AAyUtC,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA6D1D;AA0FD,KAAK,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACvC,GACL,OAAO,CAAC,MAAM,CAAC,CA2YjB;AAqmGD,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAS/H;AAs4CD,wBAAgB,8BAA8B,CAAC,WAAW,EAAE,yBAAyB,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAKxH;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,qBAAqB,EAC7B,WAAW,EAAE,yBAAyB,EACtC,OAAO,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,EAC1C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,kBAAkB,GAAG,kBAAkB,GAAG,kBAAkB,CAgH9D"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAYA,OAAO,EAAkU,KAAK,WAAW,EAA0H,MAAM,6BAA6B,CAAC;AAIvf,OAAO,EAkBL,KAAK,qBAAqB,EAK3B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAgI,KAAK,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,KAAK,kBAAkB,EAAqG,KAAK,YAAY,EAAwB,MAAM,2BAA2B,CAAC;AAEhY,OAAO,EAQL,KAAK,gBAAgB,EAEtB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAWL,KAAK,yBAAyB,EAG/B,MAAM,8BAA8B,CAAC;AA8UtC,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAgE1D;AA0FD,KAAK,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACvC,GACL,OAAO,CAAC,MAAM,CAAC,CA2YjB;AA4mHD,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAS/H;AAojBD,wBAAsB,6BAA6B,CACjD,GAAG,EAAE,YAAY,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GACxC,OAAO,CAAC,IAAI,CAAC,CAgGf;AA0lCD,wBAAgB,8BAA8B,CAAC,WAAW,EAAE,yBAAyB,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAKxH;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,qBAAqB,EAC7B,WAAW,EAAE,yBAAyB,EACtC,OAAO,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,EAC1C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,kBAAkB,GAAG,kBAAkB,GAAG,kBAAkB,CAgH9D"}