Initial import of zapier-docs-master from zapier monorepo

2026-09-11 18:02:21 -04:00 · 2026-09-11 18:02:21 -04:00 · 244f473421
commit 244f473421
61 changed files with 635 additions and 0 deletions
--- a/MESSAGE-FLOWS.md
+++ b/MESSAGE-FLOWS.md
@ -0,0 +1,44 @@
+# Message flows
+
+## 1. Create timestamp (async)
+
+1. Zapier → `POST https://zappier-edge/v1/timestamp` (`x-api-key`)
+2. zappier-edge meters → `POST middleware/zapier/v1/timestamp`
+3. splitter: chain sha256; optional `verae.archive.put`
+4. middleware → chain create or existing lookup
+5. middleware publishes `verae.zapier.jobs.watch` `{ jobId, tenantId, … }`
+6. HTTP 202 `{ jobId }` back to Zapier
+7. job-poller consumes watch, GET chain status
+8. On terminal: `verae.zapier.jobs.events`
+9. webhook-deliver POSTs Zapier REST Hook if subscribed
+
+## 2. Wait
+
+Same as (1) but HTTP holds until `jobs.events` or `WAIT_TIMEOUT_MS` → `{ status: pending, jobId }`.
+
+## 3. Hash already registered
+
+Step 4 returns original jobId + original seal. No second chain write. `receipts[0].kind = seal`. Later archive attaches become `receipts[1…]` if `includeAttached`.
+
+## 4. includeAttached
+
+After seal is known, aggregator publishes `verae.archive.query`. Each WORM: bloom miss = no packet; hit = `verae.archive.reply.<correlationId>`. Aggregator merges into wait JSON.
+
+## 5. Multipart attachments
+
+Splitter emits one `archive.put` per file (`kind: file`, `contentSha256`). Chain never stores bytes.
+
+## 6. Batch Merkle (bulk summary)
+
+1. Zapier → `POST /v1/timestamp/batch` (one item per line)
+2. Middleware hashes each item (leaves), builds Merkle tree
+3. Chain seals **only the root**
+4. Each leaf proof → `verae.archive.put` `kind: tree` on a sharded tree node
+5. Central `GET /hashes/{leaf}` → miss (`itemizedOnMainChain: false`)
+6. `GET /hashes/{leaf}?includeTree=true` → aggregator broadcasts `verae.archive.query` `kinds=["tree"]`
+7. Tree node bloom hit → `archive.reply.<id>` with proof; others silent
+8. Response: root seal + `tree-leaf` receipt
+
+## 7. Simulator
+
+`packages/verae-zapier-simulator` replays flows 1–6 in-process with a trace console, fault injection, and modification suggestions. It does not connect to live NATS.
--- a/README.md
+++ b/README.md
@ -0,0 +1,60 @@
+# zapier-docs-master
+
+Summaries, NATS contracts, and message flows for every Verae Time × Zapier module.
+
+**Live catalog:** https://zapier.georgelambert.org/  
+**Overview (start here):** https://git.georgelambert.org/marchon/overview  
+**Operator console:** http://127.0.0.1:3850/ (Fleet · Trace · Docs)  
+**Monorepo:** https://git.georgelambert.org/marchon/master-zapier-plan-draft (`main` and `master`)
+
+## Git repos (Forgejo on NS1)
+
+| Repo | URL |
+|------|-----|
+| master-zapier-plan-draft | https://git.georgelambert.org/marchon/master-zapier-plan-draft |
+| zappier-edge | https://git.georgelambert.org/marchon/zappier-edge |
+| verae-middleware | https://git.georgelambert.org/marchon/verae-middleware |
+| verae-zapier-app | https://git.georgelambert.org/marchon/verae-zapier-app |
+| verae-activate | https://git.georgelambert.org/marchon/verae-activate |
+| verae-request-splitter | https://git.georgelambert.org/marchon/verae-request-splitter |
+| verae-archive-worm | https://git.georgelambert.org/marchon/verae-archive-worm |
+| verae-archive-aggregator | https://git.georgelambert.org/marchon/verae-archive-aggregator |
+| verae-tree-node | https://git.georgelambert.org/marchon/verae-tree-node |
+| verae-zapier-simulator | https://git.georgelambert.org/marchon/verae-zapier-simulator |
+| zapier-user-docs | https://git.georgelambert.org/marchon/zapier-user-docs |
+| verae-fleet | https://git.georgelambert.org/marchon/verae-fleet |
+| **overview** | https://git.georgelambert.org/marchon/overview |
+| verae-nats-process | https://git.georgelambert.org/marchon/verae-nats-process |
+| **zapier-docs-master** (this repo) | https://git.georgelambert.org/marchon/zapier-docs-master |
+| **verae-ops** | https://git.georgelambert.org/marchon/verae-ops |
+
+Clone (SSH port 2223):
+
+`git clone ssh://git@git.georgelambert.org:2223/marchon/<name>.git`
+
+## Modules
+
+| Module | Summary | NATS in | NATS out |
+|--------|---------|---------|----------|
+| zappier-edge | Metered HTTPS for Zapier | — | — (HTTPS to middleware) |
+| verae-middleware | Job id + wait HTTP | jobs.events | jobs.watch |
+| verae-activate | Pushable Zapier app | — | — |
+| verae-zapier-app | Full Zapier nouns | — | — |
+| request-splitter | Hash vs files | — | archive.put |
+| archive-worm | Bloom WORM node | archive.query, archive.put | archive.reply.* (hit only) |
+| archive-aggregator | Merge archive replies | archive.reply.* | archive.query |
+| tree-node | Merkle leaf proofs | archive.query, archive.put | archive.reply.* (hit only) |
+| zapier-simulator | Trace console (in-process) | — | — |
+| zapier-user-docs | Signup → lookup guide | — | — |
+| verae-fleet | Replica floors + monitor | — | — |
+| overview | System map | — | — |
+| nats-process | Template worker | example.process.in | example.process.out / reply.* |
+| ops | Install / Docker / Proxmox / metal | — | — |
+
+## Documents in this repo
+
+- [MESSAGE-FLOWS.md](MESSAGE-FLOWS.md) — numbered request paths
+- [modules-and-nats.md](modules-and-nats.md) — address table
+- [archive-nats.md](archive-nats.md) — bloom / multi-receipt design
+- [composition.md](composition.md) — HTTPS hops
+- `modules/<name>/SUMMARY.md` and `NATS.md`
--- a/archive-nats.md
+++ b/archive-nats.md
@ -0,0 +1,91 @@
+# Archive NATS: jobs, multipart split, hash receipts, WORM bloom fan-out
+
+Zapier never speaks NATS. HTTPS stops at zappier → middleware. Middleware owns jobs, splitting, chain lookup, and archive aggregation.
+
+## End-to-end
+
+```text
+Zapier  --HTTPS-->  zappier (meter, x-api-key)
+                 --HTTPS-->  middleware /zapier/v1/timestamp[/wait]
+                              1. split multipart
+                                 chain: SHA256 only (+ optional public-meta digest)
+                                 archives: public JSON, encrypted private JSON, files
+                              2. publish jobs.watch → return jobId (202)
+                              3. waiters subscribe jobs.events
+                              4. lookup SHA256 on chain (mock or Verae)
+                                 already sealed → original receipt, no new seal
+                                 later attach records → extra receipts
+                              5. if includeAttached:
+                                 publish verae.archive.query
+                                 WORM nodes: bloom miss = silence
+                                 bloom hit = reply
+                                 aggregate until WAIT_ARCHIVE_MS
+                              6. jobs.events completed JSON → waiter / REST Hook
+```
+
+Blockchain stores **hash + time + block + certificate**. Public metadata, encrypted metadata, and file bytes live on **WORM archives**.
+
+## Splitter
+
+`splitRequest(body | multipart)`:
+
+| Field | Destination |
+|-------|-------------|
+| `data` / `sha256` | Chain register or lookup |
+| `publicMetadata` | Archive put (clear) |
+| `privateMetadata` | Archive put (ciphertext) |
+| `files[]` | Archive put; chain gets content hashes + ids |
+| `includeAttached` | Whether wait path queries archives |
+
+## Hash already registered
+
+Return original `jobId` and original seal. Do not write a second chain timestamp.
+
+If later attach jobs exist for that hash, `receipts` is an array: seal first, then attachment receipts in time order.
+
+## Subjects
+
+| Subject | Publisher | Subscriber |
+|---------|-----------|------------|
+| `verae.zapier.jobs.watch` | HTTP edge | job poller |
+| `verae.zapier.jobs.events` | poller | waiter, webhook router |
+| `verae.archive.put` | splitter | archive that owns the shard |
+| `verae.archive.query` | aggregator | **every** archive (not a shared queue group) |
+| `verae.archive.reply.<correlationId>` | archive on bloom hit | aggregator |
+
+Query payload: `{ correlationId, sha256, tenantId, kinds[] }`.  
+`kinds` may include `tree` for Merkle leaf proofs (hashes sealed only as a bulk summary root).  
+Reply payload: `{ archiveId, sha256, records[] }`.
+
+Bloom miss → no reply. Aggregator timeout → complete with whatever arrived.
+
+## WORM archives
+
+Each process holds append-only records + a bloom of SHA256 keys it stores. False positives OK; false negatives must be rare. Bloom is not an ACL — on hit, still check tenant/share.
+
+Harness: three mock archives with overlapping hashes.
+
+## Completed job JSON (wait / hook)
+
+```json
+{
+  "jobId": "…",
+  "status": "completed",
+  "sha256": "…",
+  "receipts": [
+    { "kind": "seal", "timestamp": "…", "certificate": "…", "blockIndex": 42 },
+    { "kind": "metadata-attach", "attachedAt": "…", "publicMetadata": {} }
+  ],
+  "files": [{ "id": "…", "sha256": "…", "archiveId": "archive-b" }],
+  "archivesQueried": true,
+  "archiveReplies": 2
+}
+```
+
+Flag off or all blooms miss → `files` empty, extra receipts omitted.
+
+## Security
+
+- Zapier never connects to NATS or archives.
+- Private metadata only on authenticated archive replies.
+- NS1 NATS stays loopback; use `scripts/nats-tunnel.sh`.
--- a/composition.md
+++ b/composition.md
@ -0,0 +1,33 @@
+# Composition: zappier commercial edge + Verae adapter
+
+```text
+Users → Zapier UI
+Zapier cloud runs packages/verae-zapier
+  --HTTPS, x-api-key--> packages/zappier /v1/*
+                          (meter, quote, 401/403, usage)
+                          --internal HTTPS--> packages/verae-zapier-middleware /zapier/v1/*
+                                --sync--> api.veraetime.net  or MOCK_VERAE
+                                --NATS--> workers --> Verae + Zapier REST Hooks
+
+Humans → zappier /portal   signup, API key, usage, reloads, invoices
+Ops    → zappier /admin    rate card, tiers, customers, PO invoices
+```
+
+## Ownership
+
+| Concern | Package |
+|---------|---------|
+| API keys, custom pricing, Stripe, invoices, portal | `packages/zappier` |
+| Timestamp/verify/status, NATS, REST Hooks, mock Verae | `packages/verae-zapier-middleware` |
+| Zapier Platform nouns (creates/searches/triggers) | `packages/verae-zapier` |
+| Official SDK reference | `vendor/zapier-platform` |
+
+Zapier never talks to NATS or `api.veraetime.net`.
+
+Do not reimplement Stripe, invoices, or the rate-card UI inside the Verae middleware.
+
+Public keys are zappier `x-api-key` (issued at portal signup). Middleware `zmw_` / `PLAN_LIMITS` stay internal until composition PR 4 removes them from the public path.
+
+Demo zappier routes `/v1/transform` and `/v1/storage` are a metering sandbox, not Verae timestamping or encrypted LTS.
+
+Payment invoices (zappier) are not certified timestamp receipts (Verae feature i).
--- a/modules-and-nats.md
+++ b/modules-and-nats.md
@ -0,0 +1,82 @@
+# Modules and NATS message contracts
+
+Master map of every service in the Zapier ↔ middleware ↔ chain ↔ WORM-archive path.
+
+Zapier cloud **never** connects to NATS. Internal services do: middleware workers, archives, account-balance, zappier-edge billing, CS, sales, and accounting.
+
+## Who talks to whom (HTTPS vs NATS)
+
+```text
+[Zapier Platform app]  HTTPS  [zappier-edge]  HTTPS  [middleware-http]
+        |                     | NATS verae.billing.*          |
+        |                     v                               |
+[customer portal]      [account-balance]                 NATS JetStream
+[CS :3011]             queue account-balance             (NS1 loopback :4222)
+[sales :3012]                 ^                               |
+[accounting :3013]            | request-reply                 |
+                              +-------------------------------+
+          +------------------+------------------+-------------+
+          |                  |                  |
+   [job-poller]      [webhook-deliver]   [archive-aggregator]
+          |                                     |
+          | HTTPS                               | NATS query/reply
+   [verae-chain-client]                         |
+                                          [archive-worm × N]
+                                          bloom miss = silence
+```
+
+## Module catalog
+
+| Module | Repo (Forgejo) | Runtime | Listens | Sends |
+|--------|----------------|---------|---------|-------|
+| zapier-platform-app | `verae-zapier-app` | Zapier cloud | User Zap steps | HTTPS to zappier-edge |
+| zappier-edge | `zappier-edge` | Public HTTPS :3000 | Zapier, portal, admin | HTTPS to middleware; NATS billing after authz |
+| access-authz | `verae-access-authz` | :3020 + NATS | `verae.access.authz.check` | allow/deny |
+| access-web | `verae-access-web` | :3021 | customer browser | billing statement/reload |
+| access-api | `verae-access-api` | :3022 | x-api-key | statement; HTTPS to middleware |
+| access-leaf | `verae-access-leaf` | :3023 | S2S leaf | archive/jobs only |
+| access-zapier | `verae-access-zapier` | :3024 | Zapier HTTPS | jobs.watch after authz |
+| account-balance | `zappier-account-balance` | :3010 + NATS | `verae.billing.*` | statement/adjust replies |
+| customer-service | `zappier-customer-service` | :3011 | CS staff HTTP | NATS balance.adjust / statement.get |
+| sales-pricing | `zappier-sales-pricing` | :3012 | Sales HTTP | NATS statement.get; HTTPS to edge for multipliers |
+| accounting-export | `zappier-accounting-export` | :3013 | Accounting HTTP | reads invoices; NATS statement |
+| middleware-http | `verae-middleware` | Public HTTPS :3100 | zappier-edge | NATS jobs.watch; HTTP to chain; wait on jobs.events |
+| job-poller | `verae-job-poller` | Worker | `verae.zapier.jobs.watch` | `verae.zapier.jobs.events`; HTTP GET chain status |
+| webhook-deliver | `verae-webhook-deliver` | Worker | `verae.zapier.webhooks.deliver` + events | HTTPS POST Zapier REST Hook |
+| request-splitter | `verae-request-splitter` | In middleware | HTTP body / multipart | chain hash; `verae.archive.put` |
+| archive-aggregator | `verae-archive-aggregator` | Worker / in wait | `includeAttached` on wait | `verae.archive.query`; reads `verae.archive.reply.<id>` |
+| archive-worm | `verae-archive-worm` | N copies | `verae.archive.query`, `verae.archive.put` | `verae.archive.reply.<id>` if bloom hits |
+| tree-node | `verae-tree-node` | N copies (WORM role) | `verae.archive.query`, `verae.archive.put` kind `tree` | `verae.archive.reply.<id>` if bloom hits |
+| zapier-simulator | `verae-zapier-simulator` | Local HTTP :3847 | operator browser | in-process replay of all addresses |
+| zapier-user-docs | `zapier-user-docs` | Static | — | catalog `/user-docs/` |
+| verae-chain-client | `verae-chain-client` | Library | — | HTTPS `api.veraetime.net` or MOCK |
+| fleet | `verae-fleet` | Local HTTP :3850 | operator | keepFloor + SSH hosts |
+| overview | `overview` | Static | — | high-level map |
+| nats-process | `verae-nats-process` | Template worker | `verae.example.process.in` | `.out` / `.reply.*` |
+| docs-master | `zapier-docs-master` | Static | — | published on zapier.georgelambert.org |
+
+## Addresses (subjects)
+
+| Address | Kind | Payload (required fields) |
+|---------|------|---------------------------|
+| `verae.zapier.jobs.watch` | JetStream work queue | `tenantId`, `veraeUserId`, `jobId`, `tokenRef`, `enqueuedAt`, `attempt`, `maxAttempts`, `intervalMs`, `traceId` |
+| `verae.zapier.jobs.events` | JetStream events | `event` (`timestamp.completed\|failed\|timeout`), `tenantId`, `jobId`, `status`, `traceId`, `emittedAt` |
+| `verae.zapier.webhooks.deliver` | JetStream work queue | `hookId`, `tenantId`, `targetUrl`, `event`, `payload`, `attempt`, `traceId` |
+| `verae.zapier.usage` | optional | `tenantId`, `action`, `amount`, `at` |
+| `verae.billing.statement.get` | request-reply | `customerId` → prepaid, credits, usage, payments |
+| `verae.billing.balance.adjust` | request-reply | `customerId`, `cents`, `reason`, `agent` |
+| `verae.billing.usage.recorded` | pub | meter events from zappier-edge |
+| `verae.billing.payment.recorded` | pub | portal reload / invoice paid |
+| `verae.billing.credit.applied` | pub | CS goodwill |
+| `verae.access.authz.check` | request-reply | `{ plane, subject, principal }` → `{ allow, reason }` |
+| `verae.access.web.billing.statement.get` | ingress | web plane only; mapped after authz |
+| `verae.access.api.*` | ingress | customer API plane |
+| `verae.access.zapier.*` | ingress | Zapier plane |
+| `verae.access.leaf.in` | ingress | S2S leaf; never billing |
+| `verae.archive.put` | JetStream | `sha256`, `tenantId`, `kind` (`publicMeta\|privateMeta\|file\|tree`), `record`, `traceId` |
+| `verae.archive.query` | pub to **all** archives | `correlationId`, `sha256`, `tenantId`, `kinds[]`, `traceId` |
+| `verae.archive.reply.<correlationId>` | replies | `archiveId`, `sha256`, `records[]`, `traceId` |
+
+## Completed job JSON (back to Zapier)
+
+See `docs/02-architecture/archive-nats.md`. Seal receipts from chain; extra receipts and `files[]` from archive aggregation when `includeAttached` is true.
--- a/modules/overview/NATS.md
+++ b/modules/overview/NATS.md
@ -0,0 +1,3 @@
+# NATS — overview
+
+Documentation only. Describes the central 3-server cluster. Zapier never connects.
--- a/modules/overview/SUMMARY.md
+++ b/modules/overview/SUMMARY.md
@ -0,0 +1,3 @@
+# overview
+
+High-level system map, 3-node NATS cluster, uptime, network failure, address routing. Repo: `overview`.
--- a/modules/verae-access-api/NATS.md
+++ b/modules/verae-access-api/NATS.md
@ -0,0 +1,3 @@
+# NATS — verae-access-api
+
+Plane `api`. Statement and jobs.watch after authz. No credits, no archive.
--- a/modules/verae-access-api/SUMMARY.md
+++ b/modules/verae-access-api/SUMMARY.md
@ -0,0 +1,3 @@
+# verae-access-api
+
+Direct customer API (`x-api-key`). Separate from Zapier Platform.
--- a/modules/verae-access-authz/NATS.md
+++ b/modules/verae-access-authz/NATS.md
@ -0,0 +1,3 @@
+# NATS — verae-access-authz
+
+`verae.access.authz.check` request-reply. Queue `access-authz`. Fail closed.
--- a/modules/verae-access-authz/SUMMARY.md
+++ b/modules/verae-access-authz/SUMMARY.md
@ -0,0 +1,3 @@
+# verae-access-authz
+
+Default-deny authorization step on the NATS address path. Planes: zapier, web, api, leaf, staff.
--- a/modules/verae-access-leaf/NATS.md
+++ b/modules/verae-access-leaf/NATS.md
@ -0,0 +1,3 @@
+# NATS — verae-access-leaf
+
+`verae.access.leaf.in` → authz.check → `verae.archive.*` / jobs.*. Denied: billing.
--- a/modules/verae-access-leaf/SUMMARY.md
+++ b/modules/verae-access-leaf/SUMMARY.md
@ -0,0 +1,3 @@
+# verae-access-leaf
+
+Server-to-server NATS leaf ingress. Archive and jobs only. Never billing.
--- a/modules/verae-access-staff/NATS.md
+++ b/modules/verae-access-staff/NATS.md
@ -0,0 +1,3 @@
+# NATS — verae-access-staff
+
+Plane `staff`. Authz then billing statement/adjust.
--- a/modules/verae-access-staff/SUMMARY.md
+++ b/modules/verae-access-staff/SUMMARY.md
@ -0,0 +1,3 @@
+# verae-access-staff
+
+Staff plane for credits and statement review.
--- a/modules/verae-access-web/NATS.md
+++ b/modules/verae-access-web/NATS.md
@ -0,0 +1,3 @@
+# NATS — verae-access-web
+
+Plane `web`. Authz then `verae.billing.statement.get` / `balance.adjust` kind=reload.
--- a/modules/verae-access-web/SUMMARY.md
+++ b/modules/verae-access-web/SUMMARY.md
@ -0,0 +1,3 @@
+# verae-access-web
+
+Direct customer web plane. Not Zapier. Statement + reload only after authz.
--- a/modules/verae-access-zapier/NATS.md
+++ b/modules/verae-access-zapier/NATS.md
@ -0,0 +1,3 @@
+# NATS — verae-access-zapier
+
+Plane `zapier`. Authz then jobs.watch / usage.recorded. Zapier cloud never connects to NATS.
--- a/modules/verae-access-zapier/SUMMARY.md
+++ b/modules/verae-access-zapier/SUMMARY.md
@ -0,0 +1,3 @@
+# verae-access-zapier
+
+Zapier Platform HTTPS plane only. No portal, no admin, no leaf.
--- a/modules/verae-activate/NATS.md
+++ b/modules/verae-activate/NATS.md
@ -0,0 +1,10 @@
+# NATS — verae-activate
+
+This Zapier Platform app **does not use NATS**.
+
+| Direction | Address | Peer | Body |
+|-----------|---------|------|------|
+| IN | Zapier UI / runtime | user Zap | `number1`, `number2`, `text`, `data` / `sha256` |
+| OUT HTTPS (optional) | zappier-edge `/v1/add` or `/v1/timestamp` | only if `api_base` + `api_key` set | JSON |
+
+Blank connection fields → local compute only.
--- a/modules/verae-activate/SUMMARY.md
+++ b/modules/verae-activate/SUMMARY.md
@ -0,0 +1,11 @@
+# verae-activate (Zapier Platform app)
+
+**Job:** Private Zapier integration you push first. Actions run in Zapier cloud.
+
+**Expects:** User connection (API key optional).
+
+**Sends:** nothing if fields blank (Add Numbers / Echo / SHA256 / Create Timestamp local mock). If `api_base` + `api_key`, HTTPS to zappier-edge.
+
+**Does not** speak NATS.
+
+**Test:** `npm test`; `zapier-platform validate`.
--- a/modules/verae-archive-aggregator/NATS.md
+++ b/modules/verae-archive-aggregator/NATS.md
@ -0,0 +1,8 @@
+# NATS — verae-archive-aggregator
+
+| Direction | Address | Peer | Body |
+|-----------|---------|------|------|
+| OUT | `verae.archive.query` | all WORM | `{ correlationId, sha256, tenantId, kinds[], traceId }` |
+| IN | `verae.archive.reply.<correlationId>` | WORM hits | `{ archiveId, sha256, records[] }` |
+
+Stop collecting at `WAIT_ARCHIVE_MS`. Silent archives are listed in `silent[]`, not errors.
--- a/modules/verae-archive-aggregator/SUMMARY.md
+++ b/modules/verae-archive-aggregator/SUMMARY.md
@ -0,0 +1,11 @@
+# verae-archive-aggregator
+
+**Job:** If `includeAttached`, fan out archive query and merge replies into the job JSON.
+
+**Expects:** wait-path flag from middleware-http; replies on `verae.archive.reply.<correlationId>`.
+
+**Sends:** `verae.archive.query` to all WORM nodes.
+
+**Timeout:** missing archives omit slices; chain receipt still succeeds.
+
+**Test:** `npm test` — one silent bloom miss + one hit; merge seal + metadata-attach.
--- a/modules/verae-archive-worm/NATS.md
+++ b/modules/verae-archive-worm/NATS.md
@ -0,0 +1,9 @@
+# NATS — verae-archive-worm
+
+| Direction | Address | From / to | Body |
+|-----------|---------|-----------|------|
+| IN | `verae.archive.put` | splitter | `{ sha256, tenantId, kind, record, traceId }` |
+| IN | `verae.archive.query` | aggregator (broadcast) | `{ correlationId, sha256, tenantId, kinds[], traceId }` |
+| OUT | `verae.archive.reply.<correlationId>` | aggregator | `{ archiveId, sha256, records[], traceId }` **only if bloom.mightHave(sha256)** |
+
+Subscribe to query **without** a shared queue group so every archive sees every query.
--- a/modules/verae-archive-worm/SUMMARY.md
+++ b/modules/verae-archive-worm/SUMMARY.md
@ -0,0 +1,14 @@
+# verae-archive-worm
+
+**Job:** Append-only WORM store of metadata and files. Bloom filter: miss → stay silent on NATS.
+
+**Expects:**
+- `verae.archive.put` — append record, add sha256 to bloom
+- `verae.archive.query` — `{ correlationId, sha256, tenantId, kinds[] }` (every node sees this; **not** a shared queue group)
+
+**Sends:**
+- `verae.archive.reply.<correlationId>` **only on bloom hit** — `{ archiveId, sha256, records[] }`
+
+**Does not** write to the blockchain.
+
+**Test:** `npm test` — miss is `null`; put then query returns records.
--- a/modules/verae-fleet/NATS.md
+++ b/modules/verae-fleet/NATS.md
@ -0,0 +1,3 @@
+# NATS — verae-fleet
+
+Does not subscribe. Records which workers should. NATS remains loopback.
--- a/modules/verae-fleet/SUMMARY.md
+++ b/modules/verae-fleet/SUMMARY.md
@ -0,0 +1,5 @@
+# verae-fleet
+
+**Job:** Service catalog, per-service configs, monitor, restart, pause/on/off, keep tree-node replica floor.
+
+**Config:** `fleet.json` (min/max) + `machines.json` (hosts) + `services/<id>.json`. Operator console at `:3850` (Fleet · Trace · Docs).
--- a/modules/verae-jobs-events/NATS.md
+++ b/modules/verae-jobs-events/NATS.md
@ -0,0 +1,3 @@
+# NATS — verae-jobs-events
+
+IN `verae.zapier.jobs.events` queue `jobs-events`.
--- a/modules/verae-jobs-events/SUMMARY.md
+++ b/modules/verae-jobs-events/SUMMARY.md
@ -0,0 +1,3 @@
+# verae-jobs-events
+
+Mailbox for `verae.zapier.jobs.events` (passthrough + count).
--- a/modules/verae-nats-accounts/NATS.md
+++ b/modules/verae-nats-accounts/NATS.md
@ -0,0 +1,3 @@
+# NATS — verae-nats-accounts
+
+Policy only. See `policy.json`.
--- a/modules/verae-nats-accounts/SUMMARY.md
+++ b/modules/verae-nats-accounts/SUMMARY.md
@ -0,0 +1,3 @@
+# verae-nats-accounts
+
+INTERNAL vs LEAF. Leaf deny `verae.billing.>`.
--- a/modules/verae-nats-process/NATS.md
+++ b/modules/verae-nats-process/NATS.md
@ -0,0 +1,3 @@
+# NATS — verae-nats-process
+
+IN `verae.example.process.in` (queue `example-process`). OUT `.out` and `.reply.<id>`.
--- a/modules/verae-nats-process/SUMMARY.md
+++ b/modules/verae-nats-process/SUMMARY.md
@ -0,0 +1,3 @@
+# verae-nats-process
+
+Template for a new `verae.<area>.<resource>.*` worker. Copy this repo to expand.
--- a/modules/verae-ops/NATS.md
+++ b/modules/verae-ops/NATS.md
@ -0,0 +1,3 @@
+# verae-ops NATS
+
+Documentation only. Runtime NATS bind stays private. See https://zapier.georgelambert.org/packages/verae-ops/06-linking-services.pdf
--- a/modules/verae-ops/SUMMARY.md
+++ b/modules/verae-ops/SUMMARY.md
@ -0,0 +1,3 @@
+# verae-ops
+
+Install and maintenance documentation: Docker, Proxmox, VMs, dedicated hardware, linking services.
--- a/modules/verae-request-splitter/NATS.md
+++ b/modules/verae-request-splitter/NATS.md
@ -0,0 +1,8 @@
+# NATS — verae-request-splitter
+
+| Direction | Address | To | Body |
+|-----------|---------|-----|------|
+| OUT | `verae.archive.put` | each WORM | one message per publicMeta / privateMeta / file |
+| OUT | (in-process) chain | middleware | `{ sha256, hashAlg, data? }` |
+
+No inbound NATS in the in-process embedding.
--- a/modules/verae-request-splitter/SUMMARY.md
+++ b/modules/verae-request-splitter/SUMMARY.md
@ -0,0 +1,13 @@
+# verae-request-splitter
+
+**Job:** Peel a request into (1) chain hash and (2) off-chain archive puts.
+
+**Expects messages from:** middleware-http (in-process call today; later NATS `verae.splitter.in` if split out).
+
+**Sends messages to:**
+- Chain path: `{ sha256, hashAlg, data? }`
+- `verae.archive.put` for each `publicMeta` / `privateMeta` / `file`
+
+**Does not talk to Zapier or NATS job poller.**
+
+**Test:** `npm test` — hash-only has zero puts; two files + public meta → 3 puts.
--- a/modules/verae-tree-node/NATS.md
+++ b/modules/verae-tree-node/NATS.md
@ -0,0 +1,7 @@
+# NATS — verae-tree-node
+
+| Direction | Address | From / to | Body |
+|-----------|---------|-----------|------|
+| IN | `verae.archive.put` | merkle builder | `{ sha256, kind: "tree", record: { merkleRoot, proof, leafIndex, chainSealJobId } }` |
+| IN | `verae.archive.query` | aggregator (broadcast) | `{ correlationId, sha256, kinds: ["tree", …] }` |
+| OUT | `verae.archive.reply.<correlationId>` | aggregator | only if bloom.mightHave(sha256) |
--- a/modules/verae-tree-node/SUMMARY.md
+++ b/modules/verae-tree-node/SUMMARY.md
@ -0,0 +1,9 @@
+# verae-tree-node
+
+**Job:** Hold inclusion proofs for SHA-256 leaves that were registered only as part of a bulk Merkle summary. The main Verae chain itemizes the **root**, not each leaf.
+
+**Expects messages from:** middleware batch path (`verae.archive.put` kind `tree`); aggregator (`verae.archive.query`).
+
+**Sends messages to:** `verae.archive.reply.<correlationId>` on bloom hit.
+
+**Does not talk to Zapier.** Same bloom-silence rule as `verae-archive-worm`.
--- a/modules/verae-zapier-middleware/NATS.md
+++ b/modules/verae-zapier-middleware/NATS.md
@ -0,0 +1,9 @@
+# NATS — verae-middleware
+
+| Direction | Address | Peer | Body |
+|-----------|---------|------|------|
+| OUT | `verae.zapier.jobs.watch` | job-poller | job watch payload |
+| IN | `verae.zapier.jobs.events` | waiter | terminal status |
+| OUT | (via aggregator) `verae.archive.query` | WORM | attached lookup |
+
+HTTP remains the only Zapier-facing surface.
--- a/modules/verae-zapier-middleware/SUMMARY.md
+++ b/modules/verae-zapier-middleware/SUMMARY.md
@ -0,0 +1,15 @@
+# verae-middleware (HTTP edge)
+
+**Job:** Public `/zapier/v1/*`. Auth, entitlements, timestamp/wait, hash lookup, objects, receipts. Publishes NATS jobs; waits on events.
+
+**Expects HTTPS from:** zappier-edge (or Zapier if pointed here).
+
+**Sends:**
+- HTTPS to verae-chain-client (`/api/timestamp`, `/api/status`, `/api/verify`)
+- `verae.zapier.jobs.watch` after create
+- waits `verae.zapier.jobs.events`
+- splitter + aggregator when attachments / `includeAttached`
+
+**Returns to requestor:** 202 `{ jobId }` or wait JSON (completed / pending+jobId).
+
+**NATS:** never exposed to Zapier.
--- a/modules/verae-zapier-simulator/NATS.md
+++ b/modules/verae-zapier-simulator/NATS.md
@ -0,0 +1,3 @@
+# NATS — verae-zapier-simulator
+
+In-process replay of `jobs.watch`, `jobs.events`, `archive.put`, `archive.query`, `archive.reply.*`. No live subscribe.
--- a/modules/verae-zapier-simulator/SUMMARY.md
+++ b/modules/verae-zapier-simulator/SUMMARY.md
@ -0,0 +1,7 @@
+# verae-zapier-simulator
+
+**Job:** Zapier-like UI + hop-by-hop trace console to validate messaging, assumptions, delays, failures, recoveries, and suggested modifications before `zapier-platform push`.
+
+**Expects:** HTTP `:3847` or `Simulator.run` in tests.
+
+**Sends:** nothing to live NATS / Zapier / Verae.
--- a/modules/verae-zapier/NATS.md
+++ b/modules/verae-zapier/NATS.md
@ -0,0 +1,10 @@
+# NATS — verae-zapier-app
+
+This Zapier Platform app **does not use NATS**.
+
+| Direction | Address | Peer | Body |
+|-----------|---------|------|------|
+| IN | Zapier runtime | user Zap | create/search/trigger fields |
+| OUT HTTPS | middleware `/zapier/v1/timestamp`, `/wait`, `/verify`, `/status/{id}`, `/hashes/{sha256}`, REST Hook subscribe | verae-middleware | Bearer `zmw_` |
+
+Job completion is a REST Hook HTTP POST from webhook-deliver, not a NATS client in Zapier.
--- a/modules/verae-zapier/SUMMARY.md
+++ b/modules/verae-zapier/SUMMARY.md
@ -0,0 +1,9 @@
+# verae-zapier-app
+
+**Job:** Full Zapier CLI app: timestamp, wait, verify, batch, job status, hash lookup, REST Hook.
+
+**Expects:** `zmw_` middleware key (today) or zappier key after composition.
+
+**Sends:** HTTPS to middleware `/zapier/v1/*`.
+
+**Does not** speak NATS.
--- a/modules/zapier-decisions/NATS.md
+++ b/modules/zapier-decisions/NATS.md
@ -0,0 +1,3 @@
+# NATS — zapier-decisions
+
+None.
--- a/modules/zapier-decisions/SUMMARY.md
+++ b/modules/zapier-decisions/SUMMARY.md
@ -0,0 +1,3 @@
+# zapier-decisions
+
+Architecture decisions and action log for the lab cleanup (prepaid SoT, identity, access planes, leaf policy, fleet).
--- a/modules/zapier-user-docs/NATS.md
+++ b/modules/zapier-user-docs/NATS.md
@ -0,0 +1,3 @@
+# NATS — zapier-user-docs
+
+Static docs. Users never configure NATS in Zapier.
--- a/modules/zapier-user-docs/SUMMARY.md
+++ b/modules/zapier-user-docs/SUMMARY.md
@ -0,0 +1,3 @@
+# zapier-user-docs
+
+**Job:** Customer guide from signup through register, central-chain lookup, and tree-node lookup of bulk-summary leaves.
--- a/modules/zappier-account-balance/NATS.md
+++ b/modules/zappier-account-balance/NATS.md
@ -0,0 +1,12 @@
+# NATS — zappier-account-balance
+
+Queue group `account-balance`. This process is the source of truth for prepaid cents.
+
+| Direction | Address | Kind | Body |
+|-----------|---------|------|------|
+| IN | `verae.billing.statement.get` | request-reply | `{ customerId }` → statement |
+| IN | `verae.billing.balance.get` | request-reply | `{ customerId }` → statement |
+| IN | `verae.billing.balance.adjust` | request-reply | `{ customerId, cents, reason, agent, kind }` |
+| IN | `verae.billing.usage.recorded` | pub | `{ customerId, endpointId, cents, at }` (debits prepaid) |
+
+`payment.recorded` and `credit.applied` are fan-out events from publishers; prepaid mutations go through `balance.adjust`.
--- a/modules/zappier-account-balance/SUMMARY.md
+++ b/modules/zappier-account-balance/SUMMARY.md
@ -0,0 +1,3 @@
+# zappier-account-balance
+
+NATS source of truth for prepaid balances, credits, usage events, and payments.
--- a/modules/zappier-accounting-export/NATS.md
+++ b/modules/zappier-accounting-export/NATS.md
@ -0,0 +1,7 @@
+# NATS — zappier-accounting-export
+
+| Direction | Address | Kind |
+|-----------|---------|------|
+| OUT | `verae.billing.statement.get` | request-reply (review) |
+
+IIF/CSV export remains HTTPS to zappier-edge admin.
--- a/modules/zappier-accounting-export/SUMMARY.md
+++ b/modules/zappier-accounting-export/SUMMARY.md
@ -0,0 +1,5 @@
+# zappier-accounting-export
+
+Accounting export of invoices to QuickBooks IIF and CSV, plus **review** of customer credits, balances, usage, and payments over NATS.
+
+Forgejo: https://git.georgelambert.org/marchon/zappier-accounting-export
--- a/modules/zappier-customer-service/NATS.md
+++ b/modules/zappier-customer-service/NATS.md
@ -0,0 +1,8 @@
+# NATS — zappier-customer-service
+
+| Direction | Address | Kind |
+|-----------|---------|------|
+| OUT | `verae.billing.statement.get` | request-reply (review) |
+| OUT | `verae.billing.balance.adjust` | request-reply (credits) |
+
+HTTP fallback: `ACCOUNT_BALANCE_URL` then zappier-edge admin. Zapier cloud never connects here.
--- a/modules/zappier-customer-service/SUMMARY.md
+++ b/modules/zappier-customer-service/SUMMARY.md
@ -0,0 +1,7 @@
+# zappier-customer-service
+
+CS department API and UI for prepaid credit additions and **review** of credits, balances, usage, and payments.
+
+Internal path: NATS `verae.billing.statement.get` / `verae.billing.balance.adjust` → account-balance. HTTP fallback to `:3010` then zappier-edge admin.
+
+Forgejo: https://git.georgelambert.org/marchon/zappier-customer-service
--- a/modules/zappier-identity/NATS.md
+++ b/modules/zappier-identity/NATS.md
@ -0,0 +1,3 @@
+# NATS — zappier-identity
+
+`verae.identity.bind` / `verae.identity.lookup` queue `identity`.
--- a/modules/zappier-identity/SUMMARY.md
+++ b/modules/zappier-identity/SUMMARY.md
@ -0,0 +1,3 @@
+# zappier-identity
+
+Bind and lookup `veraeUserId`. JWTs never stored.
--- a/modules/zappier-sales-pricing/NATS.md
+++ b/modules/zappier-sales-pricing/NATS.md
@ -0,0 +1,7 @@
+# NATS — zappier-sales-pricing
+
+| Direction | Address | Kind |
+|-----------|---------|------|
+| OUT | `verae.billing.statement.get` | request-reply (review) |
+
+Pricing writes remain HTTPS to zappier-edge admin.
--- a/modules/zappier-sales-pricing/SUMMARY.md
+++ b/modules/zappier-sales-pricing/SUMMARY.md
@ -0,0 +1,5 @@
+# zappier-sales-pricing
+
+Sales department API and UI for per-customer tier/multiplier and **review** of the same NATS statement as CS and the customer portal.
+
+Forgejo: https://git.georgelambert.org/marchon/zappier-sales-pricing
--- a/modules/zappier/NATS.md
+++ b/modules/zappier/NATS.md
@ -0,0 +1,15 @@
+# NATS — zappier-edge
+
+Zapier cloud still never connects to NATS. The edge process **does** publish and request on the private billing bus.
+
+| Direction | Address | Peer | Body |
+|-----------|---------|------|------|
+| IN HTTPS | `/v1/*` | Zapier Platform app | JSON + `x-api-key` |
+| OUT HTTPS | middleware `/zapier/v1/*` | verae-middleware | same tenant request |
+| OUT NATS | `verae.billing.usage.recorded` | account-balance | meter event (`customerId`, `veraeUserId`) |
+| OUT NATS | `verae.billing.payment.recorded` | account-balance / others | portal reload |
+| OUT NATS | `verae.billing.credit.applied` | account-balance / others | admin/CS credit |
+| OUT NATS | `verae.billing.statement.get` | account-balance | portal/admin review |
+| OUT NATS | `verae.billing.balance.adjust` | account-balance | prepaid mutation |
+
+Jobs, archive, and webhooks stay on middleware workers.
--- a/modules/zappier/SUMMARY.md
+++ b/modules/zappier/SUMMARY.md
@ -0,0 +1,11 @@
+# zappier-edge
+
+**Job:** Metered commercial API, portal, admin, Stripe. Zapier’s only public HTTPS hop.
+
+**Expects:** Zapier Platform app with `x-api-key`.
+
+**Sends:** HTTPS to middleware `/zapier/v1/*` (or local mock `/v1/timestamp`, `/v1/add`, `/v1/hashes`, `/v1/receipts`).
+
+**Does not** speak NATS or `api.veraetime.net`.
+
+**Test:** `npm test` (Jest, 177+).