Add dev-overview: designed vs running NATS routes and Zapier-Verae path.
Some checks failed
offline / test (push) Has been cancelled

Independent Forgejo repo maps every verae.* address, endpoint I/O, job
monitor loop, and remaining billing/archive wiring.
This commit is contained in:
George Lambert 2026-09-14 13:25:04 -04:00
commit 86b421db05

View file

@ -0,0 +1,68 @@
# Gaps and finish list
Modules and addresses that are designed but **not fully connected, not running as fleet workers, or not on the live Verae/Zapier path**.
## Blocked on the operator (not a NATS bug)
| Item | State | To finish |
|------|--------|-----------|
| Zapier Platform `push` | no login | `zapier login` → register → `MIDDLEWARE_BASE_URL=https://zap.zapier.georgelambert.org` → push private app |
| Live Verae | `MOCK_VERAE=true` | credentials; `MOCK_VERAE=false`; prove one seal |
| nkeys / mTLS | cluster `$G` only | `verae-nats-accounts` sketch; flip only after every `NATS_URL` has creds |
| Hash lookup on live OpenAPI | 501 | Verae API gap or our store |
## Running on HTTP/NATS but incomplete routing
| Module | Running? | NATS | Gap |
|--------|----------|------|-----|
| middleware HTTP + in-process job-poller + webhook-deliver | **yes** | watch/events/deliver | live Verae + Zapier push |
| account-balance | **yes** | billing RR | edge may not publish `usage.recorded` on every Zap |
| access-* + authz | **yes** | authz + ingress | — |
| identity | **yes** (fleet) | bind/lookup | confirm portal always binds `veraeUserId` |
| jobs-events mailbox `:3030` | **yes** (fleet) | events counter | exclusive consumer off unless `JOBS_EVENTS_EXCLUSIVE=1` |
| CS / sales / accounting | **yes** | statement/adjust | staff UX |
| zappier-edge | **yes** | billing after authz | meter → NATS; Stripe live |
| archive-worm + tree-node | **yes on LXC 510** (keep) | `archive.put/query/reply` | only **1+1** copies; fleet overlay `enabled: false` for extra replicas |
| archive-aggregator | **no** as fleet worker | query/reply | enable overlay **or** finish in-process hook (`includeAttached` TBD in middleware) |
| request-splitter | library in middleware | `archive.put` | `verae.splitter.in` not used |
| `ZAPIER_USAGE` / `USAGE_WRITER` | stream yes | `verae.zapier.usage` | no consumer; middleware usage is local files |
| fleet job-poller / webhook-deliver **extra** copies | overlay **false** | same subjects | only enable if you want SSH-spread replicas **instead of** in-process (do not double-consume without queue groups — in-process already uses queue names) |
## Designed, not a live worker
| Module | Address | What to do |
|--------|---------|------------|
| `verae-nats-process` | `verae.example.process.*` | template only; clone to add a function |
| `verae-activate` | none (HTTPS Zapier) | optional tiny app; needs Zapier login |
| `verae-zapier` (full app) | HTTPS | push after login |
| simulator | in-process fake NATS | local `:3847`; not production |
## Billing triggers and event logging (aux)
| Signal | Designed | Finish |
|--------|----------|--------|
| Timestamp/verify meter | `verae.billing.usage.recorded` + optional `verae.zapier.usage` | Publish from edge/middleware `recordUsage`; consume into account-balance; 402 from books not only local quota |
| Portal reload | `payment.recorded` + `balance.adjust` | confirm both fire on Stripe/test reload |
| CS credit | `balance.adjust` + `credit.applied` | running for adjust; confirm applied pub |
| Authz deny audit | `verae.access.authz.deny` | running on deny; no SIEM sink |
| Job lifecycle log | `jobs.events` | running; mailbox counts only — add structured log/export if needed |
| Archive put/query | `VERAE_ARCHIVE` | 510 worm/tree; aggregator not in wait path |
| Keep/fleet | no NATS | HTTP health only — fine |
| Uptime | HTTPS GET | no NATS |
| Backup | disk/JS snapshot | no live event subject |
| Public NATS edge | leaf, token | **do not** use from Zapier; rotate token; consider nkeys |
## Ordered finish for message routing
1. **Do not double-start** job-poller: either in-process **or** fleet copies, same queue `job-poller`.
2. Wire **usage**: `recordUsage` → `verae.billing.usage.recorded` (and/or `verae.zapier.usage` + `USAGE_WRITER`).
3. Enable **archive-aggregator** (or in-process equivalent) so `includeAttached` and tree proofs work on wait/status.
4. Raise worm/tree **replica floors** on 510/more CTs if archive HA is required (fleet overlay min 3).
5. Operator: Zapier `push` + `MOCK_VERAE=false`.
6. Prove: Zap create → `jobs.watch` → live `GET /api/status` → `jobs.events` → wait body + REST Hook.
7. nkeys/mTLS after every client has creds; then lock down the public edge to accounts (LEAF vs INTERNAL).
8. Optional: exclusive `jobs-events` mailbox; SIEM on `authz.deny` and `jobs.events`; `verae.splitter.in` if splitter is split out.
## What is already enough for a mock Zap
HTTPS zap/mw → mock create → `jobs.watch` → in-process poller → mock status completed → `jobs.events` → wait returns mock certificate. Archive extras and live chain are the missing middle.