@synapsor/runner 1.0.0 → 1.1.0

package/docs/running-a-runner-fleet.md

@@ -0,0 +1,349 @@
+# Running A Small Runner Fleet
+
+Synapsor Runner 1.1 supports a bounded small-fleet deployment. It does not
+turn the OSS package into Synapsor Cloud and it does not promise an unbounded,
+multi-region, or SLA-backed control plane.
+
+```text
+TLS load balancer
+  -> N stateless Streamable HTTP Runners
+       -> shared Postgres runtime ledger
+       -> bounded Postgres/MySQL source pools
+  -> supervised writeback workers
+       -> restricted source writer or app-owned executor
+```
+
+The model still receives only reviewed semantic tools. Approval, apply,
+operator credentials, database credentials, and shared-ledger authority remain
+outside MCP.
+
+## Audit Before Deployment
+
+Audit the model-facing surface before connecting a production-like database:
+
+```bash
+npx -y @synapsor/runner audit --example dangerous-db-mcp
+synapsor-runner audit ./tools-list.json
+synapsor-runner audit https://mcp.example.com --bearer-env MCP_AUDIT_TOKEN
+```
+
+Treat generic SQL/query tools, model-controlled tenant/principal inputs, and
+model-facing approval/apply tools as blockers. Audit is a static review, not a
+security proof; follow it with `tools preview`, `doctor`, and the live fleet
+verification.
+
+## What 1.1 Guarantees
+
+With `storage.shared_postgres.mode = "runtime_store"`:
+
+- each mutation holds one schema-scoped Postgres advisory lock;
+- concurrent schema migration is serialized under that lock;
+- two instances cannot create two active proposals for the same canonical
+  tenant/capability/object tuple;
+- distinct verified reviewers append decisions without losing one another;
+- one worker claim/effect completes, conflicts, retries, or enters dead letter;
+- direct SQL and app-owned handler retries use durable source-side receipts;
+- fixed-window rate limits are atomic across instances and keyed from verified
+  tenant context plus reviewed capability;
+- CLI and local UI review reads use the same shared queue as MCP serving.
+
+The current implementation restores the shared ledger into a transient SQLite
+store while holding the advisory lock, performs one bounded operation, then
+syncs the result. `max_entries` defaults to 10,000 and may be set from 100 to
+100,000. Runner fails closed with `POSTGRES_RUNTIME_STORE_CAPACITY_EXCEEDED`
+rather than copying an unbounded ledger. This serialized design is appropriate
+for a small self-hosted fleet, not high-throughput horizontal scale.
+
+## Verified Local Topology
+
+The repository includes a synthetic Compose fixture:
+
+```bash
+docker compose --profile fleet \
+  -f examples/runner-fleet/docker-compose.yml up --build -d --wait
+```
+
+The stronger verification command is:
+
+```bash
+corepack pnpm test:fleet
+```
+
+Prerequisites: Node 22, pnpm through Corepack, Docker Engine, and Docker
+Compose. It needs no AWS, Cloud account, external identity provider, or
+internet service after container images and dependencies are available.
+
+Latest verified result: **2026-07-12 (America/Los_Angeles), PASS**. Assertions:
+
+```text
+two claim-bound Runners share one bounded Postgres ledger
+cross-tenant reads are denied
+one active proposal survives concurrent creation
+rate limits hold across instances
+two verified reviewers satisfy a 2-person quorum
+apply is blocked at 1/2 and succeeds at 2/2
+simultaneous reviewer processes preserve both decisions
+two competing workers create exactly one source effect
+worker termination before write recovers without an effect
+worker termination during an open write transaction rolls back and recovers
+worker termination after commit recovers as already-applied
+source-down, read-only-ledger, and timeout readiness failures recover without restart
+shared dead letters requeue or discard with receipts and events preserved
+Postgres and MySQL pool queues fail fast at configured bounds
+backup digest and clean restore match
+retention archives before delete and preserves active proposals
+```
+
+All source rows, identities, keys, tokens, and credentials are synthetic. The
+test tears down its volumes.
+
+## Claim-Bound Sessions
+
+Use asymmetric verification for a networked fleet:
+
+```json
+{
+  "trusted_context": {
+    "provider": "http_claims",
+    "values": {
+      "tenant_id_key": "tenant_id",
+      "principal_key": "sub"
+    }
+  },
+  "session_auth": {
+    "provider": "jwt_asymmetric",
+    "algorithms": ["RS256"],
+    "jwks_url_env": "SYNAPSOR_SESSION_JWKS_URL",
+    "issuer": "https://identity.example",
+    "audience": "synapsor-runner",
+    "tenant_claim": "tenant_id",
+    "principal_claim": "sub",
+    "clock_skew_seconds": 30,
+    "jwks_cache_seconds": 600,
+    "jwks_cooldown_seconds": 30,
+    "fetch_timeout_ms": 3000,
+    "max_response_bytes": 1048576
+  }
+}
+```
+
+Every served capability context must bind tenant and principal from
+`HTTP_CLAIM`. Runner rejects an environment-bound contract mixed into this
+server with `TRUSTED_CONTEXT_PROVIDER_CONFLICT` before tools are served.
+
+Use an HTTPS JWKS URL from an allowlisted identity system. Runner rejects
+redirects, oversized responses, unknown algorithms, `none`, missing/unknown
+`kid`, bad issuer/audience, expired/not-yet-valid tokens, and private JWK
+material. Unknown `kid` triggers at most one controlled refresh. For offline
+deployments, configure one public PEM through `public_key_env` or
+`public_key_path`; never place a private key in Runner config.
+
+## Ledger And Source Pools
+
+```json
+{
+  "storage": {
+    "shared_postgres": {
+      "mode": "runtime_store",
+      "url_env": "SYNAPSOR_LEDGER_DATABASE_URL",
+      "schema": "synapsor_runner",
+      "lock_timeout_ms": 5000,
+      "max_entries": 10000
+    }
+  },
+  "sources": {
+    "app_postgres": {
+      "engine": "postgres",
+      "read_url_env": "APP_POSTGRES_READ_URL",
+      "write_url_env": "APP_POSTGRES_WRITE_URL",
+      "statement_timeout_ms": 3000,
+      "pool": {
+        "max_connections": 4,
+        "connection_timeout_ms": 2000,
+        "idle_timeout_ms": 30000,
+        "queue_timeout_ms": 1000,
+        "queue_limit": 16
+      }
+    }
+  }
+}
+```
+
+Budget database connections across every replica and worker:
+
+```text
+replicas * sum(source max_connections) + readiness/admin headroom
+```
+
+Keep that below database role and instance limits. Queue overflow fails with
+`SOURCE_POOL_QUEUE_FULL`; acquisition timeout fails with
+`SOURCE_POOL_TIMEOUT`. Neither waits indefinitely or creates a proposal.
+
+Use separate roles:
+
+- source reader: `CONNECT`, schema `USAGE`, and `SELECT` only on reviewed
+  tables/views;
+- direct writer: reviewed column-level `UPDATE` plus source receipt-table
+  `SELECT/INSERT/UPDATE`;
+- ledger role: only the configured ledger schema and migration rights;
+- migration administrator: run migrations separately when Runner should not
+  own DDL authority.
+
+## Fleet-Wide Rate Limits
+
+```json
+{
+  "rate_limits": {
+    "enabled": true,
+    "default": { "requests": 60, "window_seconds": 60 },
+    "capabilities": {
+      "billing.propose_refund": { "requests": 10, "window_seconds": 60 }
+    }
+  }
+}
+```
+
+Semantics are fixed-window, keyed by a hash of verified tenant ID and
+capability. There is no separate burst allowance: a tenant may consume the
+entire configured count immediately, then must wait for the aligned window to
+reset. In local SQLite mode limits are process-local. In `runtime_store` mode
+they use an atomic shared Postgres bucket. Rejection returns `RATE_LIMITED` and
+`retry_after_ms` to the reset boundary, increments a metric, and creates no
+proposal.
+
+## Probes And Metrics
+
+- `GET /healthz`: unauthenticated cheap process liveness; no dependency
+  checks or configuration inventory.
+- `GET /readyz`: 200 only when catalog, required sources, authoritative ledger,
+  and required writeback/executor dependencies are ready; otherwise 503.
+- `GET /metrics`: disabled unless configured. A non-loopback bind requires a
+  separate metrics bearer token.
+
+```json
+{
+  "metrics": {
+    "enabled": true,
+    "token_env": "SYNAPSOR_METRICS_TOKEN"
+  }
+}
+```
+
+Do not use the model-facing MCP token as the metrics token. Metrics include
+controlled tenant/capability/source/component labels, never object IDs,
+principals, database URLs, tokens, or raw errors.
+
+## Reviewers, Quorum, And Workers
+
+Use `signed_key` or `jwt_oidc` operator identity. `dev_env` is explicitly
+unverified and is only for local fixtures. A capability may require multiple
+distinct reviewers in the canonical contract:
+
+```sql
+APPROVAL REQUIRED ROLE billing_lead
+REQUIRE 2 APPROVALS
+```
+
+The same verified subject cannot fill two slots. Policy auto-approval does not
+satisfy a multi-human quorum. Apply and workers reject the proposal until
+progress reaches `N/N`. A rejection is terminal and auditable.
+
+Use the shared queue explicitly:
+
+```bash
+synapsor-runner proposals list --config ./synapsor.runner.json
+synapsor-runner proposals show latest --config ./synapsor.runner.json
+synapsor-runner ui --config ./synapsor.runner.json
+synapsor-runner worker run --yes --config ./synapsor.runner.json
+```
+
+Dead-letter operations require verified operator identity:
+
+```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 /secure/alice.pem
+synapsor-runner worker dead-letter discard wrp_... --reason "closed" --yes \
+  --config ./synapsor.runner.json --identity alice --identity-key /secure/alice.pem
+```
+
+Requeue preserves history and refuses if a durable applied/already-applied
+receipt already proves the effect. Discard closes the queue item without
+deleting proposals, receipts, or events.
+
+## Backup, Restore, And Retention
+
+```bash
+synapsor-runner store shared-postgres backup \
+  --url-env SYNAPSOR_LEDGER_DATABASE_URL --schema synapsor_runner \
+  --output ./ledger-backup.json
+synapsor-runner store shared-postgres verify-backup --input ./ledger-backup.json
+synapsor-runner store shared-postgres restore-backup \
+  --input ./ledger-backup.json --url-env SYNAPSOR_LEDGER_DATABASE_URL \
+  --schema synapsor_runner_restore --yes
+```
+
+Restore only accepts an empty target schema and verifies the post-restore
+manifest digest. Store archives as sensitive database extracts with owner-only
+permissions.
+
+Retention is archive-before-delete:
+
+```bash
+synapsor-runner store shared-postgres retention --older-than 30d \
+  --url-env SYNAPSOR_LEDGER_DATABASE_URL --schema synapsor_runner --dry-run
+synapsor-runner store shared-postgres retention --older-than 30d \
+  --url-env SYNAPSOR_LEDGER_DATABASE_URL --schema synapsor_runner \
+  --output ./ledger-archive.json --yes
+```
+
+The archive is written and digest-verified before deletion. Pending review,
+approved, pending-worker, retry, failed, and dead-letter records are retained.
+The operation appends an immutable retention event.
+
+Restore runbook:
+
+1. Stop ingress and workers.
+2. Verify the backup digest.
+3. Restore into a clean schema.
+4. Run `store shared-postgres status` and `/readyz` against the restore.
+5. Inspect at least one proposal, receipt, and replay through CLI.
+6. Point one canary Runner at the restored schema.
+7. Resume ingress, then workers, and watch readiness/dead-letter metrics.
+
+## Shutdown, Rotation, And Upgrades
+
+Terminate with `SIGTERM`; Runner stops accepting work, closes HTTP sessions and
+source pools, and releases ledger locks. Give workers enough grace for the
+configured handler timeout. A hard kill is recoverable through leases and
+source-side idempotency receipts, but should remain an incident signal.
+
+Rotate JWKS keys by publishing the new `kid`, waiting at least the configured
+cache lifetime, switching issuers, then retiring the old key. Rotate metrics,
+handler, database, and ledger credentials independently through their named
+environment variables.
+
+Only homogeneous Runner 1.1 instances are verified by `test:fleet`. Mixed
+1.0/1.1 operation is not claimed. For rolling upgrades:
+
+1. back up and verify the ledger;
+2. run schema/config validation with the target version;
+3. drain one worker and remove one Runner from the load balancer;
+4. upgrade one canary, verify `/readyz`, MCP tools, proposal inspection, and
+   metrics;
+5. continue one instance at a time;
+6. upgrade workers after HTTP Runners.
+
+Rollback the binary only while contracts/config remain accepted by the prior
+minor. If the prior version does not understand a new canonical field or
+ledger entry, restore the verified pre-upgrade backup into a clean schema and
+roll back the full fleet. Never mix versions merely because both are `1.x`.
+
+## TLS Boundary
+
+Terminate public TLS or mTLS at a trusted load balancer, or configure Runner's
+tested TLS/mTLS options directly. Keep Runner-to-database TLS verification on,
+use private networking where possible, restrict `/metrics`, and never forward
+untrusted identity headers as claims. The bearer JWT itself, not a proxy-added
+tenant header, is the session authority.

package/examples/runner-fleet/Dockerfile

@@ -0,0 +1,11 @@
+FROM node:22-bookworm-slim
+
+RUN corepack enable && corepack prepare pnpm@10.14.0 --activate
+
+WORKDIR /app
+COPY . .
+RUN corepack pnpm install --frozen-lockfile \
+  && corepack pnpm build:runner-package
+
+ENTRYPOINT ["node", "apps/runner/dist/cli.js"]
+CMD ["mcp", "serve", "--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8766", "--config", "/config/synapsor.runner.json"]

package/examples/runner-fleet/README.md

@@ -0,0 +1,52 @@
+# Two-Runner Fleet Fixture
+
+This synthetic fixture starts Postgres, MySQL, and two stateless Streamable
+HTTP Runner services. Both Runners share one bounded Postgres runtime ledger.
+The committed passwords and HS256 key are disposable local-demo values. Never
+reuse them outside this fixture.
+
+From the repository root:
+
+```bash
+corepack pnpm install
+docker compose --profile fleet -f examples/runner-fleet/docker-compose.yml up --build -d --wait
+docker compose --profile fleet -f examples/runner-fleet/docker-compose.yml ps
+```
+
+Check both instances:
+
+```bash
+curl --fail http://127.0.0.1:8871/healthz
+curl --fail http://127.0.0.1:8871/readyz
+curl --fail http://127.0.0.1:8872/readyz
+```
+
+The MCP endpoint requires a claim-bearing development JWT. Generate one for
+the fixture only:
+
+```bash
+node examples/runner-fleet/mint-dev-token.mjs acme local-agent
+```
+
+The production path should use `jwt_asymmetric` with an explicit RS256/ES256
+allowlist and a trusted JWKS URL or public PEM. See
+[Running A Runner Fleet](../../docs/running-a-runner-fleet.md).
+
+Run the stronger automated verification instead of treating a green Compose
+status as proof:
+
+```bash
+corepack pnpm test:fleet
+```
+
+That test launches two source-tree Runners, uses asymmetric claim-bound
+sessions and concurrent signed reviewers, starts competing workers, kills
+workers before, during, and after writeback, and verifies readiness,
+dead-letter recovery, idempotency, pool pressure, backup/restore, and
+archive-before-retention. It deletes all fixture volumes when complete.
+
+Clean up the visual Compose fixture with:
+
+```bash
+docker compose --profile fleet -f examples/runner-fleet/docker-compose.yml down -v --remove-orphans
+```

package/examples/runner-fleet/docker-compose.yml

@@ -0,0 +1,76 @@
+services:
+  postgres:
+    image: postgres:16
+    environment:
+      POSTGRES_DB: synapsor_fleet
+      POSTGRES_USER: synapsor_admin
+      POSTGRES_PASSWORD: synapsor_admin_password
+    ports:
+      - "55439:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "test \"$(psql -U synapsor_admin -d synapsor_fleet -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: 30
+    volumes:
+      - ./seed/postgres.sql:/docker-entrypoint-initdb.d/001-schema.sql:ro
+
+  mysql:
+    image: mysql:8
+    environment:
+      MYSQL_DATABASE: synapsor_fleet
+      MYSQL_ROOT_PASSWORD: root_password
+    ports:
+      - "53309:3306"
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-proot_password"]
+      interval: 2s
+      timeout: 5s
+      retries: 40
+    volumes:
+      - ./seed/mysql.sql:/docker-entrypoint-initdb.d/001-schema.sql:ro
+
+  runner-a:
+    profiles: ["fleet"]
+    build:
+      context: ../..
+      dockerfile: examples/runner-fleet/Dockerfile
+    command: ["mcp", "serve", "--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8766", "--config", "/config/synapsor.runner.json"]
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment: &runner_environment
+      FLEET_POSTGRES_READ_URL: postgresql://synapsor_reader:synapsor_reader_password@postgres:5432/synapsor_fleet
+      FLEET_POSTGRES_WRITE_URL: postgresql://synapsor_writer:synapsor_writer_password@postgres:5432/synapsor_fleet
+      SYNAPSOR_LEDGER_DATABASE_URL: postgresql://synapsor_admin:synapsor_admin_password@postgres:5432/synapsor_fleet
+      SYNAPSOR_SESSION_JWT_SECRET: synthetic-fleet-session-secret-change-before-use-0001
+      SYNAPSOR_METRICS_TOKEN: synthetic-fleet-metrics-token-change-before-use
+    ports:
+      - "8871:8766"
+    volumes:
+      - ./synapsor.runner.json:/config/synapsor.runner.json:ro
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:8766/readyz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      interval: 2s
+      timeout: 5s
+      retries: 30
+
+  runner-b:
+    profiles: ["fleet"]
+    build:
+      context: ../..
+      dockerfile: examples/runner-fleet/Dockerfile
+    command: ["mcp", "serve", "--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8766", "--config", "/config/synapsor.runner.json"]
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment: *runner_environment
+    ports:
+      - "8872:8766"
+    volumes:
+      - ./synapsor.runner.json:/config/synapsor.runner.json:ro
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:8766/readyz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      interval: 2s
+      timeout: 5s
+      retries: 30

package/examples/runner-fleet/mint-dev-token.mjs

@@ -0,0 +1,19 @@
+import crypto from "node:crypto";
+
+const tenant = process.argv[2] ?? "acme";
+const subject = process.argv[3] ?? "fleet-demo-agent";
+const secret = "synthetic-fleet-session-secret-change-before-use-0001";
+const now = Math.floor(Date.now() / 1000);
+const header = { alg: "HS256", typ: "JWT" };
+const payload = {
+  sub: subject,
+  tenant_id: tenant,
+  iss: "https://fleet.example.invalid",
+  aud: "synapsor-runner-fleet",
+  iat: now,
+  exp: now + 600,
+};
+const encode = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");
+const unsigned = `${encode(header)}.${encode(payload)}`;
+const signature = crypto.createHmac("sha256", secret).update(unsigned).digest("base64url");
+process.stdout.write(`${unsigned}.${signature}\n`);

package/examples/runner-fleet/seed/mysql.sql

@@ -0,0 +1,20 @@
+CREATE TABLE invoices (
+  id varchar(128) PRIMARY KEY,
+  tenant_id varchar(128) NOT NULL,
+  status varchar(64) NOT NULL,
+  late_fee_cents integer NOT NULL,
+  waiver_reason varchar(500),
+  updated_at datetime(6) NOT NULL
+);
+
+INSERT INTO invoices (id, tenant_id, status, late_fee_cents, waiver_reason, updated_at) VALUES
+  ('MYSQL-ACME', 'acme', 'overdue', 700, NULL, '2026-07-12 12:00:00.000000');
+
+CREATE VIEW slow_invoices AS
+SELECT invoices.*, SLEEP(0.35) AS synthetic_delay
+FROM invoices;
+
+CREATE USER IF NOT EXISTS 'synapsor_reader'@'%' IDENTIFIED BY 'synapsor_reader_password';
+GRANT SELECT ON synapsor_fleet.invoices TO 'synapsor_reader'@'%';
+GRANT SELECT ON synapsor_fleet.slow_invoices TO 'synapsor_reader'@'%';
+FLUSH PRIVILEGES;

package/examples/runner-fleet/seed/postgres.sql

@@ -0,0 +1,73 @@
+CREATE TABLE public.invoices (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL,
+  status text NOT NULL,
+  late_fee_cents integer NOT NULL,
+  waiver_reason text,
+  updated_at timestamptz NOT NULL
+);
+
+CREATE TABLE public.synapsor_writeback_receipts (
+  idempotency_key text PRIMARY KEY,
+  job_id text UNIQUE NOT NULL,
+  proposal_id text NOT NULL,
+  status text NOT NULL,
+  result_hash text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  completed_at timestamptz
+);
+
+CREATE TABLE public.synthetic_handler_receipts (
+  idempotency_key text PRIMARY KEY,
+  proposal_id text NOT NULL,
+  object_id text NOT NULL,
+  status text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+INSERT INTO public.invoices (id, tenant_id, status, late_fee_cents, waiver_reason, updated_at) VALUES
+  ('INV-ACME', 'acme', 'overdue', 2500, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-GLOBEX', 'globex', 'overdue', 3100, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-RATECO', 'rateco', 'overdue', 900, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-QUORUM-RACE', 'acme', 'overdue', 1400, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-WORKER-RACE', 'acme', 'overdue', 1600, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-DEAD-REQUEUE', 'acme', 'overdue', 1700, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-DEAD-DISCARD', 'acme', 'overdue', 1750, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-KILL-BEFORE', 'acme', 'overdue', 1200, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-KILL-DURING', 'acme', 'overdue', 1500, NULL, '2026-07-12T12:00:00Z'),
+  ('INV-KILL-AFTER', 'acme', 'overdue', 1800, NULL, '2026-07-12T12:00:00Z');
+
+CREATE FUNCTION public.synthetic_pool_delay() RETURNS integer
+LANGUAGE plpgsql VOLATILE AS $$
+BEGIN
+  PERFORM pg_sleep(0.15);
+  RETURN 0;
+END
+$$;
+
+CREATE VIEW public.slow_invoices AS
+SELECT invoices.*, public.synthetic_pool_delay() AS synthetic_delay
+FROM public.invoices;
+
+DO $$
+BEGIN
+  CREATE ROLE synapsor_reader LOGIN PASSWORD 'synapsor_reader_password';
+  CREATE ROLE synapsor_writer LOGIN PASSWORD 'synapsor_writer_password';
+EXCEPTION WHEN duplicate_object THEN NULL;
+END
+$$;
+
+GRANT CONNECT ON DATABASE synapsor_fleet TO synapsor_reader, synapsor_writer;
+GRANT USAGE ON SCHEMA public TO synapsor_reader, synapsor_writer;
+GRANT SELECT ON public.invoices TO synapsor_reader, synapsor_writer;
+GRANT SELECT ON public.slow_invoices TO synapsor_reader;
+GRANT UPDATE (late_fee_cents, waiver_reason, updated_at) ON public.invoices TO synapsor_writer;
+GRANT SELECT, INSERT, UPDATE ON public.synapsor_writeback_receipts TO synapsor_writer;
+
+-- Docker's Postgres entrypoint briefly starts a temporary postmaster while it
+-- runs init scripts. The Compose health check compares this timestamp with the
+-- current postmaster start time so dependents wait for the final server.
+CREATE TABLE public.synapsor_fixture_ready (
+  initialized_at timestamptz NOT NULL
+);
+INSERT INTO public.synapsor_fixture_ready (initialized_at) VALUES (clock_timestamp());