Overview
Synapsor Runner is the trusted-writeback layer for existing Postgres/MySQL databases. It claims approved structured jobs from Synapsor, validates the target, allowed columns, tenant scope, idempotency key, and conflict guard, then performs a parameterized single-row update and reports applied, conflict, or failed.
The runner runs in the customer environment. The write credential is not sent to the model and is not included in the Synapsor writeback job. Synapsor Cloud stores proposal state, evidence, approval, job lease metadata, result status, and replay records.
The first supported operation is guarded single-row UPDATE for Postgres and MySQL. The runner does not execute arbitrary SQL, model-generated SQL, INSERT, DELETE, DDL, stored procedures, or multi-row writes.
Until the public repository is configured, install from the local source checkout rather than a package registry or guessed GitHub URL.
What runs in Synapsor Cloud
Synapsor Cloud owns the write proposal, evidence bundle, query audit, review decision, job lease, writeback status, and replay record.
Cloud does not send database passwords, database URLs, arbitrary SQL, model prose, or model confidence as write authorization.
What runs in the customer environment
The runner owns the write credential, database transaction, target-row validation, conflict check, idempotency receipt, and safe result callback.
Run one runner per source or deploy multiple runners with the same source-scoped token when your operational policy allows it. Lease and idempotency checks prevent duplicate application.
Security invariants
The job must be approved for writeback before it can be claimed. Cloud returns a compatibility job for existing workers plus a public synapsor.writeback-job.v1 object for new runners.
The runner validates primary key, tenant guard, allowed columns, conflict guard, proposal hash/version, and idempotency key before building parameterized SQL.
The runner rejects jobs that try to update protected columns, omit tenant scope on multi-tenant sources, affect zero rows due to stale versions, or affect more than one row.
Run doctor
The doctor command validates local configuration, runner-token authentication, source-scoped writeback permissions, database reachability, engine/version, receipt-table readiness, and non-committing receipt write permission.
Doctor may create or verify the runner receipt table. It does not mutate business tables.
Connect Synapsor Cloud
Start with the local Docker demo. When you need team approvals, RBAC, hosted evidence/replay search, managed policy, and runner visibility, create a source-scoped runner token in Cloud and run cloud connect from the runner checkout.
Cloud connect verifies the token, registers runner id/version/source/engine/capability metadata, and posts an initial heartbeat. It does not upload database URLs, database passwords, write credentials, prompts, or table data.
Inspect results
Applied means the guarded single-row transaction committed. Conflict means the row was missing or the expected version no longer matched. Failed means the runner could not complete the guarded operation for an operational reason.
New runners may report synapsor.execution-receipt.v1 receipts with rows_affected, previous_version, new_version, receipt_hash, and executed_at. Synapsor attaches the terminal result to the proposal and replay record so a reviewer can inspect what was read, proposed, approved, attempted, and applied later.
Threat model and limitations
Treat the model as untrusted. Treat model arguments as untrusted. Treat a runner token as sensitive. The runner is intentionally narrow so a compromised model cannot turn an approved capability into arbitrary SQL.
The v0.1 runner is not a general self-hosted Synapsor control plane, not an automation platform, and not a generic database migration tool.
Developer notes
- Run doctor before enabling polling.
- Use a source-scoped runner token, not a normal user session.
- Store runner token and database URL outside git.
- Use receipt-table idempotency for production-like testing.
- Start in dry-run mode.
- Verify applied/conflict/failed results in the Synapsor proposal and replay record.
- Do not give the model raw SQL or write credentials.