Expand dev-overview: transport ports, sources, billing publishers, finish list

Document designed vs running NATS subjects and cluster TCP/leaf/public
endpoints, per-address I/O, Zapier→Verae job path, and unwired modules.
This commit is contained in:
George Lambert 2026-09-14 13:32:51 -04:00
commit 1c728c5513

View file

@ -30,14 +30,15 @@ Zapier never has `NATS_URL`. Verae never has `NATS_URL`.
## 1. Submit (async create)
1. Zap action **Create Timestamp** (or curl) `POST https://zap.zapier.georgelambert.org/zapier/v1/timestamp` with portal API key `zmw_…` (not a Verae JWT).
2. access-zapier / edge meters (designed: `verae.billing.usage.recorded`) and forwards to middleware.
3. Middleware `checkEntitlement` (local plan limits today).
4. `veraeClient.createTimestamp`:
2. access-zapier / edge: authz, then `meter()` records cents; if `NATS_URL` is set, `natsPublish(verae.billing.usage.recorded)`.
3. Forwards to middleware `POST /zapier/v1/timestamp`.
4. Middleware `checkEntitlement` (local plan limits today).
5. `veraeClient.createTimestamp`:
- **Mock:** in-process job, fake `jobId`.
- **Live:** `POST https://api.veraetime.net/api/timestamp` with JWT → **202** `{ jobId }`.
5. Splitter (in-process): hash vs attachments; optional `verae.archive.put` (bytes never go to chain).
6. `enqueueWatch` → JetStream **`verae.zapier.jobs.watch`**.
7. HTTP **202** `{ jobId, sha256, existing }` back to Zapier immediately.
6. Splitter (in-process): hash vs attachments; optional `verae.archive.put` (bytes never go to chain).
7. `enqueueWatch` → JetStream **`verae.zapier.jobs.watch`**.
8. HTTP **202** `{ jobId, sha256, existing }` back to Zapier immediately.
Same SHA-256 is idempotent (`existing: true`).
@ -47,7 +48,7 @@ The poller is **in the middleware Node process** when `NATS_ENABLED=true` (`star
1. Durable consumer `job-poller` on `ZAPIER_JOBS` / `verae.zapier.jobs.watch`.
2. Resolve `tokenRef` → tenant Verae password → `POST` login → JWT (stays in middleware).
3. `GET /api/status/{jobId}` (mock or live).
3. `GET /api/status/{jobId}` (mock or live timestamp server).
4. `pending` → `nak` after `intervalMs` (retry).
5. `completed` → publish `jobs.events` `{ event: timestamp.completed, status, jobId, tenantId, traceId }`.
6. `failed` → `timestamp.failed`. Too many attempts → `timestamp.timeout`.
@ -76,6 +77,20 @@ Live OpenAPI: poll until `completed` / `failed`. Hash lookup is **501** on live
`POST /zapier/v1/verify` → middleware → Verae `POST /api/verify`. No job watch.
## 6. Batch Merkle (designed; same bus)
From `MESSAGE-FLOWS.md`:
1. `POST /v1/timestamp/batch` — one item per line.
2. Middleware hashes leaves, builds Merkle tree.
3. Chain seals **only the root** (`POST /api/timestamp` on the root).
4. Each leaf proof → `verae.archive.put` `kind: tree`.
5. Central hash lookup of a leaf misses unless `includeTree=true`.
6. Aggregator broadcasts `verae.archive.query` `kinds=["tree"]`.
7. Tree node bloom hit → `archive.reply.<id>` with proof.
Live wait path does not yet call the aggregator, so tree-leaf receipts are not merged on NS1.
## Connect live `api.veraetime.net`
Still blocked on operator bind credentials. When ready:
@ -93,5 +108,18 @@ Then: working Verae login, one live seal, confirm 202/status/verify, map receipt
## Billing on this path
Designed: edge meters `usage.recorded` → account-balance; 402 if prepaid empty.
Running: middleware local usage files; account-balance NATS is up for portal/CS. **Wire edge meter → `verae.billing.usage.recorded` and 402 from books** is still a finish item.
| Hop | Designed | Running |
|-----|----------|---------|
| Edge meter | `verae.billing.usage.recorded` | **coded**; fires when edge has `NATS_URL` |
| Account-balance | subscribe + debit prepaid; 402 if empty | **subscriber running**; 402 from books not proven on every Zap |
| Middleware quota | local files via `recordUsage` | **running**; not NATS |
| `verae.zapier.usage` | optional JS meter | stream only |
## Connect a new internal process
```bash
export NATS_URL=nats://10.10.10.21:4222,nats://10.10.10.22:4222,nats://10.10.10.23:4222
# clone verae-nats-process, rename subjects, register in verae-fleet
```
Jobs stay: HTTP in from Zapier → HTTPS to Verae → NATS watch/events → HTTP back to Zapier.