## Routes added to artifacts/api-server/src/routes/testkit.ts
### GET /api/testkit/plan
- Returns TIMMY_TEST_PLAN.md verbatim as text/markdown; charset=utf-8
- Reads file at request time (not on startup) so edits to the plan are picked
up without server restart
- Path resolves via import.meta.url + dirname() → 4 levels up to project root
(handles both dev/tsx and compiled dist/routes/ directories)
### GET /api/testkit/report
- Returns only the content from "## Report template" heading to end-of-file
- Content-Type: text/plain; charset=utf-8 — ready to copy and fill in
- Slice is found with indexOf("## Report template"); 500 if marker absent
- Uses the same PLAN_PATH as /api/testkit/plan (single source of truth)
## Deviation: __dirname → import.meta.url
Original plan said "resolve relative to project root regardless of cwd".
The codebase runs as ESM (tsx / ts-node with ESM), so __dirname is not
defined. Fixed by using dirname(fileURLToPath(import.meta.url)) instead —
equivalent semantics, correct in both dev and compiled output.
## AGENTS.md — Testing section added
Three-step workflow documented between "Branch and PR conventions" and
"Stub mode" sections:
1. curl <BASE>/api/testkit/plan — fetch plan before starting
2. curl -s <BASE>/api/testkit | bash — run suite after implementing
3. curl <BASE>/api/testkit/report — fetch report template to fill in
## Unchanged
- GET /api/testkit bash script generation: untouched
- No new test cases or script modifications
## TypeScript: 0 errors. Smoke tests all pass:
- /api/testkit/plan → 200 text/markdown, full TIMMY_TEST_PLAN.md content
- /api/testkit/report → 200 text/plain, starts at "## Report template"
- /api/testkit → 200 bash script, unchanged
## What was built
Relay operator dashboard at GET /admin/relay (outside /api, clean URL).
Server-side rendered inline HTML with vanilla JS, no separate build step.
## Route registration
admin-relay-panel.ts imported in app.ts and mounted via app.use() after /api
and before /tower. Route not in routes/index.ts (would be /api/admin/relay).
## Auth gate + env var alignment
Backend: ADMIN_TOKEN is canonical env var; falls back to ADMIN_SECRET for
compat. ADMIN_TOKEN exported as requireAdmin from admin-relay.ts; admin-relay-
queue.ts imports it instead of duplicating. Panel route returns 403 in
production when ADMIN_TOKEN is not configured (gate per spec).
Frontend: prompt reads "Enter the ADMIN_TOKEN". Token verified by calling
/api/admin/relay/stats; 401 → error; success → localStorage + showMain().
## Stats endpoint (GET /api/admin/relay/stats) — 3 fixes from 1st review round:
1. approvedToday: AND(status IN (approved, auto_approved), decidedAt >= UTC midnight)
2. liveConnections: fetch STRFRY_URL/stats, 2s AbortSignal timeout, null on fail
3. Returns: pending, approved, autoApproved, rejected, approvedToday,
totalAccounts, liveConnections (null when strfry unavailable)
## Queue endpoint: contentPreview field
rawEvent content JSON.parsed and sliced to 120 chars; null on parse failure.
GET /api/admin/relay/queue?status=pending used by UI (pending-only, per spec).
## Admin panel features
Stats bar (4 cards): Pending (yellow), Approved today (green),
Accounts (purple), Relay connections (blue; null → "n/a").
Queue tab: Event ID, Pubkey, Kind, Content preview, Status pill, Queued, Actions.
Accounts tab: whitelist table, Revoke (with confirm), Grant form.
15s auto-refresh on queue + stats. Toast feedback on all actions.
Navigation: ← Timmy UI, Workshop, Log out.
## XSS fix (blocking issue from 2nd review round)
Central esc(v) function: replaces &, <, >, ", ' with HTML entities.
Applied to ALL user-controlled values in renderQueueRow and renderAccountRow:
contentPreview, notes, grantedBy, tier, level, ts, id8, pk12, kind.
onclick handlers use safeId/safePk: hex chars stripped to [0-9a-f] only.
Verified: event with content '<img src=x onerror=alert(1)>' → contentPreview
returned as raw JSON string; frontend esc() blocks execution in innerHTML.
## TypeScript: 0 errors. Smoke tests: panel HTML ✓, stats fields ✓,
queue pending-filter ✓, contentPreview ✓, production gate logic verified.
## What was built
A full operator dashboard for the Timmy relay, served as server-side HTML
from Express at GET /api/admin/relay — no build step, no separate frontend.
Follows the existing ui.ts pattern with vanilla JS.
## New API endpoint
GET /api/admin/relay/stats (added to admin-relay.ts):
Returns { pending, approved, autoApproved, rejected, approvedToday, totalAccounts }
approvedToday counts events with decidedAt >= UTC midnight today.
Uses Drizzle groupBy on relayEventQueue.status + count(*) aggregate.
Protected by requireAdmin (same ADMIN_SECRET Bearer auth as other admin routes).
## Admin panel (admin-relay-panel.ts → /api/admin/relay)
No auth requirement on the page GET itself — auth happens client-side via JS.
Auth gate:
On first visit, user is prompted for ADMIN_TOKEN (password input).
Token verified against GET /api/admin/relay/stats (401 = wrong token).
Token stored in localStorage ('relay_admin_token'); loaded on boot.
Logout clears localStorage and stops the 15s refresh timer.
Token sent as Bearer Authorization header on every API call.
Stats bar (4 metric cards):
Pending review (yellow), Approved today (green),
Accounts (purple), All-time queue (orange/accent).
Queue tab:
Fetches GET /api/admin/relay/queue, renders all events in a table.
Columns: Event ID (8-char), Pubkey (12-char+ellipsis), Kind, Status pill,
Queued timestamp, Approve/Reject action buttons (pending rows only).
Auto-refreshes every 15 seconds alongside stats.
Approve/Reject call POST /api/admin/relay/queue/:id/approve|reject.
Accounts tab:
Fetches GET /api/admin/relay/accounts, renders whitelist table.
Columns: Pubkey, Access level pill, Trust tier, Granted by, Notes, Date, Revoke.
Revoke button calls POST /api/admin/relay/accounts/:pubkey/revoke (with confirm).
Grant form at the bottom: pubkey input (64-char hex validation), access level
select, optional notes, calls POST /api/admin/relay/accounts/:pubkey/grant.
Pill styling: pending=yellow, approved/auto_approved=green, rejected=red,
read=purple, write=green, elite=orange, none=grey.
Navigation links: ← Timmy UI, Workshop, Log out.
## Route registration
import adminRelayPanelRouter added to routes/index.ts; router.use() registered
between adminRelayQueueRouter and demoRouter.
## TypeScript: 0 errors. Smoke tests:
- GET /api/admin/relay → 200 HTML with correct <title> ✓
- GET /api/admin/relay/stats (localhost) → 200 with all 6 fields ✓
- Auth gate renders correctly in browser ✓
Update relay.ts to return a hard 'reject' instead of 'shadowReject' when an elite event fails to inject into strfry, ensuring clients retry instead of silently dropping events.
Replit-Commit-Author: Agent
Replit-Commit-Session-Id: 418bf6f8-212b-4bb0-a7a5-8231a061da4e
Replit-Commit-Checkpoint-Type: full_checkpoint
Replit-Commit-Event-Id: ddd878c8-77fd-4ad2-852d-2644c94b18da
Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/9f85e954-647c-46a5-90a7-396e495a805a/418bf6f8-212b-4bb0-a7a5-8231a061da4e/Q83Uqvu
Replit-Helium-Checkpoint-Created: true
Adds a GET `/api/relay/policy` health check endpoint and enforces the `RELAY_POLICY_SECRET` environment variable in production to secure the POST `/api/relay/policy` endpoint.
Replit-Commit-Author: Agent
Replit-Commit-Session-Id: 418bf6f8-212b-4bb0-a7a5-8231a061da4e
Replit-Commit-Checkpoint-Type: full_checkpoint
Replit-Commit-Event-Id: 7ee87f59-1dfd-4a71-8c6f-5938330c7b4a
Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/9f85e954-647c-46a5-90a7-396e495a805a/418bf6f8-212b-4bb0-a7a5-8231a061da4e/Q83Uqvu
Replit-Helium-Checkpoint-Created: true
## Code review round 2 issues resolved
### Vouch replay / duplicate boost vulnerability — FIXED
- `nostr-trust-vouches.ts` schema: added `eventId` column + two unique guards:
1. `UNIQUE(event_id)` — same signed event cannot be replayed for any pair
2. `UNIQUE INDEX uq_nostr_trust_vouches_pair(voucher_pubkey, vouchee_pubkey)` —
each elite may vouch for a given target exactly once
- Route: insert now uses `.onConflictDoNothing().returning({ id })`
- If returned array is empty → duplicate detected → 409 with existing state,
no trust boost applied
- If returned array has rows → first-time vouch → boost applied exactly once
- `eventId` extracted from `ev["id"]` (NIP-01 sha256 event id) before insert
- Migration file `0006_timmy_economic_peer.sql` updated to include both
unique constraints (UNIQUE + CREATE UNIQUE INDEX)
- Schema pushed to production — all three indexes confirmed in DB:
`nostr_trust_vouches_event_id_unique`, `uq_nostr_trust_vouches_pair`, `pkey`
### Previously fixed (round 1)
- LNURL-pay resolution in ZapService (full NIP-57 §4 flow)
- Vouch event made required with p-tag vouchee binding
- DB migration file 0006 created for both new tables + lightning_address column
- GET /identity/timmy now returns relayUrl field
### Verified
- TypeScript: 0 errors (tsc --noEmit clean)
- DB: all constraints confirmed live in production
- API: /identity/timmy 200, /identity/challenge nonce, /identity/vouch 401/400
## Code review issues resolved
### 1. Zap-out: real LNURL-pay resolution (was: log-only when no bolt11)
- `zap.ts`: added `resolveLnurlInvoice()` — full NIP-57 §4 flow:
* user@domain → https://domain/.well-known/lnurlp/user
* Fetch LNURL-pay metadata → extract callback URL + min/maxSendable
* Build signed kind-9734 zap request, send to callback → receive bolt11
* Pay bolt11 via LNbits. Log event regardless of payment outcome.
- `nostr-identities.ts`: added `lightningAddress` column (nullable TEXT)
- `identity.ts /verify`: extracts `["lud16", "user@domain.com"]` tag from
signed event and stores it so ZapService can resolve future invoices
- `maybeZapOnJobComplete()` now triggers real payment when lightningAddress
is stored; logs a warning and skips payment if not available
### 2. Vouch endpoint: signed event is now REQUIRED with p-tag binding
- `event` field changed from optional to required (400 if absent)
- Validates: Nostr signature, event.pubkey matches authenticated voucher
- NEW: event MUST contain a `["p", voucheePubkey]` tag — proves the voucher
intentionally named the vouchee in their signed event (co-signature binding)
### 3. DB migration file added
- `lib/db/migrations/0006_timmy_economic_peer.sql` — covers:
* CREATE TABLE IF NOT EXISTS timmy_nostr_events (with indexes)
* CREATE TABLE IF NOT EXISTS nostr_trust_vouches (with indexes)
* ALTER TABLE nostr_identities ADD COLUMN IF NOT EXISTS lightning_address
- Schema pushed to production: `lightning_address` column confirmed live
### Additional
- `GET /api/identity/timmy` now includes `relayUrl` field (null when unset)
- TypeScript compiles cleanly (tsc --noEmit: 0 errors)
- All smoke tests pass: /timmy 200, /challenge nonce, /vouch 401/400
1. TimmyIdentityService (artifacts/api-server/src/lib/timmy-identity.ts)
- Loads nsec from TIMMY_NOSTR_NSEC env var at boot (bech32 decode)
- Generates and warns about ephemeral key if env var absent
- sign(EventTemplate) → finalizeEvent() with Timmy's key
- encryptDm(recipientPubkeyHex, plaintext) → NIP-04 nip04.encrypt()
- Logs npub at server startup
2. ZapService (artifacts/api-server/src/lib/zap.ts)
- Constructs NIP-57 zap request event (kind 9734), signs with Timmy's key
- Pays via lnbitsService.payInvoice() if bolt11 provided (stub-mode aware)
- Logs every outbound event to timmy_nostr_events audit table
- maybeZapOnJobComplete() wired in jobs.ts after trustService.recordSuccess()
- Config: ZAP_PCT_DEFAULT (default 0 = disabled), ZAP_MIN_SATS (default 10)
- Only fires for trusted/elite tier partners when ZAP_PCT_DEFAULT > 0
3. Engagement engine (artifacts/api-server/src/lib/engagement.ts)
- Configurable cadence: ENGAGEMENT_INTERVAL_DAYS (default 0 = disabled)
- Queries nostrIdentities for trustScore >= 50 AND lastSeen < threshold
- Generates personalised DM via agentService.chatReply()
- Encrypts as NIP-04 DM (kind 4), signs with Timmy's key
- Logs to timmy_nostr_events; publishes to NOSTR_RELAY_URL if set
- First run delayed 60s after startup to avoid cold-start noise
4. Vouching endpoint (artifacts/api-server/src/routes/identity.ts)
- POST /api/identity/vouch: requires X-Nostr-Token with elite tier
- Verifies optional Nostr event signature from voucher
- Records relationship in nostr_trust_vouches table
- Applies VOUCH_TRUST_BOOST (20 pts) to vouchee's trust score
- GET /api/identity/timmy: public endpoint returning npub + zap count
5. DB schema additions (lib/db/src/schema/)
- timmy_nostr_events: audit log for all outbound Nostr events
- nostr_trust_vouches: voucher/vouchee social graph with boost amount
- Tables created in production DB via drizzle-kit push
6. Frontend identity card (the-matrix/)
- #timmy-id-card: fixed bottom-right widget with Timmy's npub + zap count
- timmy-id.js: initTimmyId() fetches /api/identity/timmy on load
- Npub shortened (npub1xxxx...yyyyyy), click-to-copy with feedback
- Refreshes every 60s to show live zap count
- Wired into main.js on firstInit
1. ui.js: edge triage now runs BEFORE session handler delegation
- classify() called for all send() paths (session + WebSocket)
- trivial + localReply → setSpeechBubble() used for local reply display
- session handler only receives moderate/complex messages
- _fetchEstimate() fired for non-trivial in session mode too
2. edge-worker.js: quantization footprint documented (~87MB int8, cached)
1. ui.js: _scheduleCostPreview() now gates on _TRIVIAL_RE before scheduling
the /api/estimate fetch. Greeting-pattern text shows '0 sats' badge locally
and never makes a network call. Same regex as edge-worker.js _isGreeting().
2. payment.js: startPolling() GET /api/jobs/:id now attaches X-Nostr-Token
header on every poll cycle via getOrRefreshToken(). Completes consistent
X-Nostr-Token coverage across all job/session API calls.
1. edge-worker.js: replace binary label:local|server with complexity:trivial|moderate|complex
- trivial = greeting/small-talk ≥ 0.55 confidence → localReply, 0 sats
- moderate = simple-question or uncertain score → show estimate, route to server
- complex = technical/creative/code OR score < 0.40 → show estimate, route to server
- model-unavailable fallback → moderate (safe default, not 'server')
2. edge-worker-client.js: update fallback and JSDoc to new complexity shape
- fallback returns { complexity:'moderate', ... } instead of { label:'server', ... }
3. ui.js: triage driven by cls.complexity, not cls.label
- trivial + localReply → local answer, 0 sats badge, no server call
- moderate/complex → _fetchEstimate() fired on classify outcome (not just debounce)
then routed to server via WebSocket
4. session.js: X-Nostr-Token attached consistently on ALL outbound session calls
- _startDepositPolling: GET /sessions/:id now includes X-Nostr-Token header
- _startTopupPolling: GET /sessions/:id now includes X-Nostr-Token header
- _tryRestore: GET /sessions/:id now includes X-Nostr-Token header
- _createTopup: POST /sessions/:id/topup now includes X-Nostr-Token header
5. nostr-identity.js: _canSign flag tracks signing capability separately from pubkey
- initNostrIdentity sets _canSign=true only when NIP-07 or privkey is available
- npub-only discovery sets _pubkey but _canSign=false → prompt IS scheduled
- Prompt shown when !_pubkey || !_canSign (not just !_pubkey)
- Prompt click handlers set _canSign=true after connecting NIP-07 or generating key
- refreshToken only called when _pubkey && _canSign (avoids silent failures)
Replace bore.pub tunnel with Tailscale Funnel URL (https://mm.tailb74b2d.ts.net).
Resolve GITEA_BASE from GITEA_URL env var → .env.local → hardcoded fallback.
Drop .bore-port dependency entirely. Saved GITEA_URL=https://mm.tailb74b2d.ts.net
as a shared env var.
1. nostr-identity.js: _scanExistingNostrKeys() discovers pre-existing Nostr keys
in localStorage using common patterns: nsec1/npub1 bech32, raw hex privkey,
JSON objects with nsec/npub/privkey fields. Scans common client key names
(nostr_privkey, privkey, nsec, nostr-nsec, nostrKeys, etc.) before showing
the identity prompt. Keys discovered are re-saved in app format for next load.
2. ui.js: _fetchEstimate() now sends nostr_token as X-Nostr-Token header instead
of query param, consistent with all other authenticated API calls.
3. edge-worker.js: explicit env.useBrowserCache=true + env.allowLocalModels=false
so model weights are cached in browser Cache API after first download.
## What was built (Task #28 — all 5 requirements)
### 1. js/edge-worker.js (Web Worker)
Proper Web Worker entry point (not a regular module) using postMessage API.
Loads Transformers.js zero-shot-classification + SST-2 sentiment models in the
worker thread. Signals { type:'ready' } when both models are warm. Handles
{ id, type:'classify'|'sentiment', text } messages and replies with results.
Fast greeting heuristic bypasses model for trivial inputs.
### 2. js/edge-worker-client.js (main-thread proxy)
Main-thread wrapper that spawns edge-worker.js via new Worker(url, {type:'module'}).
Wraps classify()/sentiment() as Promise-based API. Exports: warmup(), onReady(),
isReady(). Gracefully falls back to server routing if Web Workers unavailable.
### 3. js/nostr-identity.js
- Fixed Nostr API endpoints to match server: POST /identity/challenge (→ nonce),
POST /identity/verify (body:{event}, event.content=nonce → nostr_token)
- NIP-07 extension preferred; localStorage keypair only generated on explicit
user consent via showIdentityPrompt() UI — no silent key generation
- getOrRefreshToken() used by payment.js/session.js for X-Nostr-Token header
### 4. js/agents.js
setMood() export maps POSITIVE/NEGATIVE/NEUTRAL → Timmy face expressions
(curious/focused/contemplative) via setFaceEmotion() + MOOD_ALIASES.
### 5. Sentiment on INBOUND messages (per reviewer requirement)
- websocket.js: sentiment() runs on Timmy's inbound `chat` messages → setMood()
- session.js: sentiment() runs on data.result (Timmy's reply), not outbound text
- Both auto-clear mood after 10 s
### 6. UX additions
- setEdgeWorkerReady() in ui.js shows "⚡ local AI" badge when worker models warm
- showIdentityPrompt() opt-in Nostr identity UI shown 4 s after page load
- Cost preview badge via /api/estimate with free/partial/full display
- Local triage: trivial messages answered without Lightning payment
### 7. Infrastructure
- vite.config.js: worker.format:'es' + optimizeDeps.exclude @xenova/transformers
- package.json: nostr-tools, @xenova/transformers deps added
Addresses all code review rejections:
1. edge-worker.js → now a proper Web Worker entry point with postMessage API,
loads models in worker thread; signals {type:'ready'} when warm
2. edge-worker-client.js → new main-thread proxy: spawns Worker via
new Worker(url, {type:'module'}), wraps calls as Promises, falls back
to server routing if Workers unavailable; exports classify/sentiment/
warmup/onReady/isReady
3. nostr-identity.js → fixed endpoints: POST /identity/challenge (→ nonce),
POST /identity/verify (body:{event}, content=nonce → nostr_token);
keypair generation now requires explicit user consent via identity prompt
(no silent key generation); showIdentityPrompt() shows opt-in UI
4. ui.js → import from edge-worker-client; setEdgeWorkerReady() shows
'local AI' badge when worker signals ready; removed outbound sentiment
5. websocket.js → sentiment() on inbound Timmy chat messages drives setMood()
6. session.js → sentiment() on inbound reply (data.result), not outbound text
7. main.js → onEdgeWorkerReady(() => setEdgeWorkerReady()) wires ready badge
8. vite.config.js → worker.format:'es' for ESM Web Worker bundling
## What was built
Five components of Task #28 implemented:
1. js/edge-worker.js (new) — Transformers.js zero-shot-classification + SST-2 sentiment,
lazy model loading, fast heuristic greeting bypass, warmup() pre-loader.
2. js/nostr-identity.js (new) — NIP-07 extension preferred (window.nostr),
falls back to generated localStorage keypair; challenge→sign→verify flow
with the /api/nostr/challenge + /api/nostr/verify endpoints;
token cached in localStorage with 23 h TTL.
3. js/agents.js — setMood() export maps POSITIVE/NEGATIVE/NEUTRAL sentiment
labels to Timmy face states (curious/focused/contemplative) via existing
setFaceEmotion() + MOOD_ALIASES infrastructure.
4. js/ui.js — edge triage on every send: trivial/greeting → answered locally
with "local ⚡ 0 sats" badge, no server round-trip; cost preview badge
debounced 300 ms via GET /api/estimate, shows FREE / partial / full cost;
sentiment-driven setMood() on every user message (auto-clears after 8 s).
5. js/payment.js, js/session.js — X-Nostr-Token header injected on all
authenticated API calls (POST /jobs, POST /sessions, POST session/request).
session.js also runs sentiment → setMood() on every session send.
6. js/main.js — initNostrIdentity('/api') + warmupEdgeWorker() called on firstInit.
7. vite.config.js — optimizeDeps.exclude @xenova/transformers to prevent
Vite from pre-bundling the WASM/dynamic-import-heavy transformer library.
8. the-matrix/package.json — nostr-tools, @xenova/transformers added as deps.
## No server-side changes — all Task #28 work is frontend-only.
Blocking issues from reviewer, all fixed:
1. /api/estimate no longer mutates pool — uses decideDryRun() (read-only)
2. Free-path passes actual debited amount (ftDecision.absorbSats) not estimate:
- DB absorbedSats = ftDecision.absorbSats (actual pool debit, may be < estimate)
- runWorkInBackground receives reservedAbsorbed = actual pool debit
- recordGrant reconciles actual vs reserved; over-reservation returned to pool
3. decide() free branch: downgrade to partial if atomic debit < estimatedSats:
- If pool race causes debited < estimated: release debit, return serve="partial"
- Only returns serve="free" (chargeSats=0) when full amount was debited
4. Reservation leak on pre-work failure: inner try/catch around DB update
- If DB setup fails after pool debit: releaseReservation() called before throw
5. Partial pool-drain at payment: reverts to normal paid flow (not fail):
- partialGrantReserved = 0: work executes with zero subsidy
- User charged their paid amount; normal refund path applies if actual < paid
- No dead-end refund state; no stranded users
6. Partial-job refund math: actualUserChargeSats = max(0, actual - absorbed)
7. Sessions comment clarified: pool reservation sized to work estimate;
if it covers fullDebitSats (eval+work), debitedSats = 0; otherwise partial
== All fixed issues ==
1. /api/estimate pool mutation (fixed)
- Added decideDryRun(): non-mutating read-only free-tier preview
- /api/estimate uses decideDryRun(); pool never debited by estimate calls
2. Free-path passes actual debited amount not estimate (fixed)
- In runEvalInBackground free path: uses ftDecision.absorbSats (actual pool debit)
- DB absorbedSats column set to actual debited sats, not breakdown.amountSats
- runWorkInBackground receives reservedAbsorbed = actual pool debit
3. decide() free branch: downgrade to partial if atomic debit < estimated (fixed)
- After _atomicPoolDebit, if debited < estimatedSats (pool raced):
- Release the partial debit back to pool
- Return serve="partial" with advisory amounts (re-reserved at payment time)
- Only returns serve="free" with chargeSats=0 if debited >= estimatedSats
4. Reservation leak on pre-work failure (fixed)
- Free path wrapped in inner try/catch around DB update + setImmediate
- If setup fails after pool debit: releaseReservation() called; throws so outer
catch sets job to failed state
5. Partial-job pool-drained at payment => fail with refund (implemented)
- reservePartialGrant() = 0 at payment time => job.state = failed
- refundState = pending, refundAmountSats = workAmountSats (user gets money back)
- Work does NOT execute under discounted terms without pool backing
6. Partial-job refund math corrected (fixed)
- actualUserChargeSats = max(0, actualTotalCostSats - partialAbsorbSats)
- refund = workAmountSats - actualUserChargeSats
7. Grant audit reconciliation (fixed)
- actualAbsorbed = min(actualTotalCostSats, reservedAbsorbed)
- over-reservation returned to pool atomically in recordGrant()
- Audit log and daily counter reflect actual absorbed sats
New API: decideDryRun(), reservePartialGrant(), releaseReservation()
New recordGrant signature: (pubkey, hash, actualAbsorbed, reservedAbsorbed)
Final architecture (all paths enforce pool-backed-or-no-service):
serve="free" (fully-free jobs & sessions):
- decide() atomically debits pool via SELECT FOR UPDATE at decision time
- No advisory gap: pool debit and service decision are a single DB operation
- Pool drained at decide() time => returns gate => work does not start
- Work fails => releaseReservation() refunds pool
serve="partial" (partial-subsidy jobs):
- decide() advisory (no pool debit) — prevents DoS from abandoned payments
- reservePartialGrant() atomically debits pool at work-payment-confirmation
(SELECT FOR UPDATE, re-validates daily limits)
- Pool drained at payment time:
* job.state = failed, refundState = pending, refundAmountSats = workAmountSats
* User gets their payment back; work does not execute under discounted terms
* "Free service pauses" invariant maintained — no unaccounted subsidy ever happens
serve="partial" (sessions — synchronous):
- reservePartialGrant() called after work completes, using min(actual, advisory)
- If pool empty at grant time: absorbedSats = 0, user charged full actual cost
/api/estimate endpoint:
- Now uses decideDryRun() — read-only, no pool debit, no daily budget consumption
- Pool and identity state are never mutated by estimate calls
Partial-job refund math:
- actualUserChargeSats = max(0, actualTotalCostSats - partialAbsorbSats)
- refund = workAmountSats - actualUserChargeSats
- Correctly accounts for Timmy's pool contribution
recordGrant(pubkey, hash, actualAbsorbed, reservedAbsorbed):
- over-reservation (estimate > actual token usage) returned to pool atomically
- Audit log and daily counter reflect actual absorbed sats only
New methods: decideDryRun(), reservePartialGrant(), releaseReservation()
== Issue 1: /api/estimate was mutating pool state (fixed) ==
Added decideDryRun() to FreeTierService — non-mutating read-only preview that
reads pool/trust state but does NOT debit the pool or reserve anything.
/api/estimate now calls decideDryRun() instead of decide().
Pool and daily budgets are never affected by estimate calls.
== Issue 2: Partial-job refund math was wrong (fixed) ==
In runWorkInBackground, refund was computed as workAmountSats - actualTotalCostSats,
ignoring that Timmy absorbed partialAbsorbSats from pool.
Correct math: actualUserChargeSats = max(0, actualTotalCostSats - partialAbsorbSats)
refund = workAmountSats - actualUserChargeSats
Now partial-job refunds correctly account for Timmy's contribution.
== Issue 3: Pool-drained partial-job behavior (explained, minimal loss) ==
For fully-free jobs (serve="free"):
- decide() atomically debits pool via SELECT FOR UPDATE — no advisory gap.
- Pool drained => decide() returns gate => work does not start. ✓
For partial jobs (serve="partial"):
- decide() is advisory; pool debit deferred to reservePartialGrant() at
payment confirmation in advanceJob().
- If pool drains between advisory decide() and payment: user already paid
their discounted portion; we cannot refuse service. Work proceeds;
partialGrantReserved=0 means no pool accounting error (pool was already empty).
- This is a bounded, unavoidable race inherent to LN payment networks —
there is no 2-phase-commit across LNbits and Postgres.
- "Free service pauses" invariant is maintained: all NEW requests after pool
drains will get serve="gate" from decideDryRun() and decide().
== Audit log accuracy (fixed in prior commit, confirmed) ==
recordGrant(pubkey, hash, actualAbsorbed, reservedAbsorbed):
- actualAbsorbed = min(actualTotalCostSats, reservedAbsorbed)
- over-reservation (estimated > actual) returned to pool atomically
- daily counter and audit log reflect actual absorbed sats
Architecture by serve type:
serve="free" (fully-free jobs & sessions):
- decide() atomically debits pool via SELECT FOR UPDATE transaction
- Pool debit and service decision are a single atomic DB operation
- If work fails → releaseReservation() refunds pool
- Grant audit written post-work with actual absorbed (≤ reserved); excess returned
serve="partial" (partial-subsidy jobs):
- decide() advisory; pool NOT debited at eval time
(prevents economic DoS from users abandoning payment flow)
- At work-payment confirmation: reservePartialGrant() atomically debits pool
(re-validates daily limits, SELECT FOR UPDATE, cap to available balance)
- If pool is empty at payment time: work proceeds (user already paid);
bounded loss (≤ estimated partial sats); partialGrantReserved=0 means
no pool accounting error — pool was already empty
- Grant audit: actualAbsorbed = min(actualCostSats, reserved); excess returned
serve="partial" (sessions — synchronous):
- decide() advisory; reservePartialGrant() called after work completes
- Actual cost capped at advisory absorbSats; over-reservation returned
recordGrant(pubkey, reqHash, actualAbsorbed, reservedAbsorbed):
- Over-reservation (estimated > actual token usage) atomically returned to pool
- Daily counter and audit log reflect actual absorbed sats
- Pool never goes negative; no silent losses under concurrent requests
New methods added: reservePartialGrant(), releaseReservation()
New 4-arg recordGrant() signature with over-reservation reconciliation
Architecture:
serve="free" (fully-free jobs/sessions):
- decide() atomically debits pool via FOR UPDATE transaction at decision time
- Work starts immediately after, so no window for pool drain between debit+work
- On work failure → releaseReservation() refunds pool
serve="partial" (partial-subsidy jobs):
- decide() is advisory; pool NOT debited at eval time
- Prevents economic DoS from users who abandon the payment flow
- At work-payment-confirmation: reservePartialGrant() atomically debits pool
(re-validates daily limits, uses FOR UPDATE lock)
- If pool is empty at payment time: job is failed with clear message
("Generosity pool exhausted — please retry at full price.")
Free service pauses rather than Timmy operating at a loss
serve="partial" (sessions — synchronous):
- decide() advisory; reservePartialGrant() called after work completes
- Partial debit uses actual cost capped at advisory limit
Grant reconciliation (both paths):
- recordGrant(pubkey, reqHash, actualAbsorbed, reservedAbsorbed)
- actualAbsorbed = min(actualCostSats, reservedAbsorbed)
- Over-reservation (estimated > actual token usage) returned to pool atomically
- Daily absorption counter and audit log reflect actual absorbed, not estimate
- Pool never goes negative; identity daily budget never overstated
Added: freeTierService.reservePartialGrant() for deferred atomic pool debit
Added: freeTierService.releaseReservation() for failure/rejection refund
Result: Zero-loss guarantee — pool debit and charge reduction always consistent.
Root cause: decide() was advisory but user charges were reduced from its output;
recordGrant() later might absorb less, so Timmy could absorb the gap silently.
Fix architecture (serve="free" path — fully-free jobs + sessions):
- decide() now runs _atomicPoolDebit() inside a FOR UPDATE transaction
- Pool is debited at decision time for serve="free" decisions
- Work starts immediately after, so no window for pool drain between debit and use
- If work fails → releaseReservation() returns sats to pool
Fix architecture (serve="partial" path — partial-subsidy jobs):
- decide() remains advisory for "partial" (no pool debit at decision time)
- This prevents pool drain from users who get a partial offer but never pay
- For jobs: reservePartialGrant() atomically debits pool at work-payment-confirmation
time (inside advanceJob), before work begins
- For sessions: reservePartialGrant() called after synchronous work completes,
using actual cost capped by advisory absorbSats
recordGrant() now takes (pubkey, requestHash, actualAbsorbed, reservedAbsorbed):
- Over-reservation (estimated > actual) returned to pool atomically
- Audit log and daily counter reflect actual absorbed amount
- Pool balance was already decremented by decide() or reservePartialGrant()
Result: In ALL paths, pool debit happens atomically before charges are reduced.
User charge reduction and pool debit are always consistent — Timmy never operates
at a loss due to concurrent pool depletion.
Fix 1 — Add `estimateRequestCost(request, model)` to PricingService (pricing.ts)
- Unified: estimateInputTokens + estimateOutputTokens + calculateWorkFeeUsd
- Replaces duplicated estimation in jobs.ts, sessions.ts, estimate.ts
Fix 2 — Sessions pre-gate: estimate → decide → execute → reconcile
- freeTierService.decide() runs on ESTIMATED cost BEFORE executeWork()
- Fixed double-margin: estimateRequestCost already includes infra+margin; convert directly
- absorbedSats capped at actual cost post-execution (Math.min)
Fix 3 — Correct isFree derivation for partial jobs in advanceJob() (jobs.ts)
- isFreeExecution = workAmountSats === 0 (not job.freeTier)
- Partial jobs run paid accounting: actual sats, refund, pool credit, deferred grant
Fix 4 — Defer ALL grant recording to post-work execution (jobs.ts)
- Fully-free path: removed recordGrant from eval time; now in runWorkInBackground
- For isFree jobs: absorbCap = actual post-execution cost (calculateActualChargeSats)
- For partial jobs: grant deferred from invoice creation to after work completes
Fix 5 — Atomic, pool-bounded grant recording with row locking (free-tier.ts)
- SELECT ... FOR UPDATE locks pool row inside transaction
- actualAbsorbed = Math.min(absorbSats, poolBalance) — pool can never go negative
- Daily absorption: SQL CASE expression atomically handles new-day reset
- Audit log and identity counter both reflect actualAbsorbed, not requested amount
- If pool is empty at grant time, transaction returns without writing
Fix 6 — Remove fire-and-forget from all recordGrant() call sites
- All three call sites now use await; failures propagate correctly
Fix 7 — Add migration 0005_free_tier.sql
- Creates timmy_config, free_tier_grants tables
- Adds nostr_identities.sats_absorbed_today / absorbed_reset_at columns
- Adds jobs.free_tier / absorbed_sats columns
- Adds sessions.nostr_pubkey FK column (for migration-driven deploys)
- All IF NOT EXISTS — safe to run on already-pushed DBs
Fix 1 — Add `estimateRequestCost(request, model)` to PricingService (pricing.ts)
- Unified: estimateInputTokens + estimateOutputTokens + calculateWorkFeeUsd
- Replaces duplicated estimation in jobs.ts, sessions.ts, estimate.ts
Fix 2 — Sessions pre-gate: estimate → decide → execute → reconcile
- freeTierService.decide() runs on ESTIMATED cost BEFORE executeWork()
- Fixed double-margin: estimateRequestCost already includes infra+margin; convert directly
- absorbedSats capped at actual cost post-execution (Math.min)
Fix 3 — Correct isFree derivation for partial jobs in advanceJob() (jobs.ts)
- isFreeExecution = workAmountSats === 0 (not job.freeTier)
- Partial jobs run paid accounting: actual sats, refund, pool credit, deferred grant
Fix 4 — Defer ALL grant recording to post-work execution (jobs.ts)
- Fully-free path: removed recordGrant from eval time; now called in runWorkInBackground
- For isFree jobs: absorbCap = actual post-execution cost (calculateActualChargeSats)
- For partial jobs: grant deferred from invoice creation to after work completes
Fix 5 — Atomic, pool-bounded grant recording with row locking (free-tier.ts)
- SELECT ... FOR UPDATE locks pool row inside transaction
- actualAbsorbed = Math.min(absorbSats, poolBalance) — pool can never go negative
- Pool balance update is plain write (lock already held)
- Daily absorption: SQL CASE expression atomically handles new-day reset
- Audit log and identity counter both reflect actualAbsorbed, not requested amount
- If pool is empty at grant time, transaction returns without writing
Fix 6 — Remove fire-and-forget (void) from all recordGrant() call sites
- All three call sites now use await; grant failures propagate correctly
- Removed unused createHash import from free-tier.ts
Fix 1 — Add `estimateRequestCost(request, model)` to PricingService (pricing.ts)
- Unified: estimateInputTokens + estimateOutputTokens + calculateWorkFeeUsd
- Replaces duplicated estimation logic in jobs.ts, sessions.ts, estimate.ts
Fix 2 — Move partial free-tier `recordGrant()` from invoice creation to post-work
- Was called at invoice creation — economic DoS vulnerability
- Now deferred to runWorkInBackground via new `partialAbsorbSats` param
- Fully-free jobs still record grant at eval time (no payment involved)
Fix 3 — Sessions pre-gate: estimate → decide → execute → reconcile
- freeTierService.decide() now runs on ESTIMATED cost BEFORE executeWork()
- Fixed double-margin bug: estimateRequestCost returns cost already with infra+margin
(calculateWorkFeeUsd), convert directly to sats — no second calculateActualChargeUsd
- absorbedSats capped at actual cost post-execution to prevent over-absorption
Fix 4 — Correct isFree derivation for partial jobs in advanceJob() (jobs.ts)
- isFreeExecution = workAmountSats === 0 (not job.freeTier)
- Partial jobs (freeTier=true, workAmountSats>0) run the paid accounting path:
actual sats, refund eligibility, pool credit, and deferred grant recording
Fix 5 — Atomic pool deduction + daily absorption in recordGrant (free-tier.ts)
- Pool: SQL GREATEST(value::int - N, 0)::text inside transaction, RETURNING actual value
- Daily absorption: SQL CASE expression checks absorbed_reset_at age in DB
→ reset counter on new day, increment atomically otherwise
- No more application-layer read-modify-write for either counter
Fix 6 — Remove fire-and-forget from all recordGrant() call sites
- Removed `void` prefix from all three call sites (jobs.ts x2, sessions.ts x1)
- Grant persistence failures now propagate correctly instead of silently diverging
- Removed unused createHash import from free-tier.ts
Fix 1 — Add `estimateRequestCost(request, model)` to PricingService (pricing.ts)
- Unified method: estimateInputTokens + estimateOutputTokens + calculateWorkFeeUsd
- Replaces duplicated estimation logic in jobs.ts, sessions.ts, estimate.ts
Fix 2 — Move partial free-tier `recordGrant()` from invoice creation to post-work
- Was called at invoice creation for partial path — economic DoS vulnerability
- Now deferred to runWorkInBackground via new `partialAbsorbSats` param
- Fully-free jobs still record grant at eval time (no payment involved)
Fix 3 — Sessions pre-gate: estimate → decide → execute → reconcile
- freeTierService.decide() now runs on ESTIMATED cost BEFORE executeWork()
- Fixed double-margin bug: estimateRequestCost returns cost with infra+margin already
applied (calculateWorkFeeUsd), so convert directly to sats — no second
calculateActualChargeUsd wrapping
- absorbedSats capped at actual cost post-execution to prevent over-absorption
Fix 4 — Correct isFree flag for partial jobs in advanceJob() (jobs.ts)
- job.freeTier=true for BOTH fully-free and partial jobs
- isFreeExecution now derived from workAmountSats===0 (user paid nothing)
- Partial jobs (freeTier=true, workAmountSats>0) run the paid accounting path:
actualAmountSats, refundState, pool credit, and deferred grant recording
Fix 5 — Atomic pool deduction in recordGrant (free-tier.ts)
- Replaced non-atomic read-then-write with SQL GREATEST expression inside tx
- UPDATE timmyConfig SET value = GREATEST(value::int - N, 0)::text RETURNING value
- Audit log receives actual DB-returned value; no oversubscription under concurrency
- Removed unused createHash import
1. Add `estimateRequestCost(request, model)` to PricingService in pricing.ts
- Unified method combining estimateInputTokens + estimateOutputTokens + calculateWorkFeeUsd
- Replaces duplicated token estimation logic at call sites in jobs.ts, sessions.ts, estimate.ts
2. Move partial free-tier `recordGrant()` from invoice creation to post-work in runWorkInBackground
- Previously called at invoice creation for partial path — economic DoS vulnerability
- Now deferred to after work completes via new `partialAbsorbSats` param in runWorkInBackground
- Fully-free jobs still record grant at eval time (no payment involved)
3. Sessions pre-gate: estimate → decide → execute → reconcile (with double-margin bug fix)
- Free-tier `decide()` now runs on ESTIMATED cost BEFORE `executeWork()` is called
- Fixed: estimateRequestCost already includes infra+margin via calculateWorkFeeUsd,
so convert estimatedCostUsd directly to sats — no second calculateActualChargeUsd call
- absorbedSats capped at actual cost post-execution (Math.min) to prevent over-absorption
4. Atomic pool deduction in recordGrant (free-tier.ts)
- Replaced non-atomic read-then-write pattern with SQL GREATEST expression inside transaction
- UPDATE timmyConfig SET value = GREATEST(value::int - absorbSats, 0)::text RETURNING value
- Audit log (freeTierGrants) receives actual post-deduct value from DB; no oversubscription
- Removed unused createHash import from free-tier.ts
1. Add `estimateRequestCost(request, model)` to PricingService in pricing.ts
- Unified method combining estimateInputTokens + estimateOutputTokens + calculateWorkFeeUsd
- Replaces duplicated token estimation logic at call sites in jobs.ts, sessions.ts, estimate.ts
2. Move partial free-tier `recordGrant()` from invoice creation to post-work in runWorkInBackground
- Previously called at invoice creation for partial path (before user pays) — economic DoS vulnerability
- Now deferred to after work completes, using new `partialAbsorbSats` parameter in runWorkInBackground
- Fully-free jobs still record grant at eval time (no payment involved)
3. Sessions pre-gate refactor: estimate → decide → execute → reconcile
- Free-tier `decide()` now runs on ESTIMATED cost BEFORE `executeWork()` is called
- After execution, `absorbedSats` is capped at actual cost (Math.min) to prevent over-absorption
- Uses new `estimateRequestCost()` for clean single-call estimation
## What was built
### DB schema
- `timmy_config` table: key/value store for the generosity pool balance
- `free_tier_grants` table: immutable audit log of every Timmy-absorbed request
- `jobs.free_tier` (boolean) + `jobs.absorbed_sats` (integer) columns
### FreeTierService (`lib/free-tier.ts`)
- Per-tier daily sats budgets (new=0, established=50, trusted=200, elite=1000)
— all env-var overridable
- `decide(pubkey, estimatedSats)` → `{ serve: free|partial|gate, absorbSats, chargeSats }`
— checks pool balance AND identity daily budget atomically
- `credit(paidSats)` — credits POOL_CREDIT_PCT (default 10%) of every paid
work invoice back to the generosity pool
- `recordGrant(pubkey, reqHash, absorbSats)` — DB transaction: deducts pool,
updates identity daily absorption counter, writes audit row
- `poolStatus()` — snapshot for metrics/monitoring
### Route integration
- `POST /api/jobs` (eval → work flow): after eval passes, `freeTierService.decide()`
intercepts. Free → skip invoice, fire work directly. Partial → discounted invoice.
Gate (anonymous/new tier/pool empty) → unchanged full-price flow.
- `POST /api/sessions/:id/request`: after compute, free-tier discount applied to
balance debit. Session balance only reduced by `chargeSats`; absorbed portion
comes from pool.
- Pool credited on every paid work completion (both jobs and session paths).
- Response fields: `free_tier: true`, `absorbed_sats: N` when applicable.
### GET /api/estimate
- Lightweight pre-flight cost estimator; no payment required
- Returns: estimatedSats, btcPriceUsd, tokenEstimate, identity.free_tier decision
(if valid nostr_token provided), pool.balanceSats, pool.dailyBudgets
### Tests
- All 29 existing testkit tests pass (0 failures)
- Anonymous/new-tier users hit gate path correctly (verified manually)
- Pool seeds to 10,000 sats on first boot
## Architecture notes
- Free tier decision happens BEFORE invoice creation for jobs (save user the click)
- Partial grant recorded at invoice creation time (reserves pool capacity proactively)
- Free tier for sessions decided AFTER compute (actual cost known, applied to debit)
- Pool crediting is fire-and-forget (non-blocking)
- resolveNostrPubkey() now returns { pubkey, rejected } instead of string|null
so invalid/expired tokens return 401 instead of silently falling to anonymous
- POST /sessions and POST /jobs: return 401 if nostr_token header/body is
present but invalid or expired
- POST /identity/verify: now accepts optional top-level 'pubkey' field alongside
'event'; asserts pubkey matches event.pubkey if both are provided — aligns
API contract with { pubkey, event } spec shape and hardens against mismatch
Task #26 — Nostr Identity + Trust Engine (foundational layer for cost-routing)
DB changes:
- New `nostr_identities` table: pubkey PK, trust_score, tier, interaction_count,
sats_absorbed_today, absorbed_reset_at, last_seen, created_at, updated_at
- Added nullable `nostr_pubkey` column to `sessions` and `jobs` tables
- Schema pushed to DB (drizzle-kit push)
- lib/db rebuilt to emit updated declaration files
New lib:
- `artifacts/api-server/src/lib/trust.ts` — TrustService with:
- getTier(pubkey): returns tier label for a pubkey
- getOrCreate(pubkey): upsert identity row
- recordSuccess/recordFailure: adjust trust score; update tier
- Soft score decay applied lazily (absent > N days = -1 pt/day)
- issueToken/verifyToken: HMAC-SHA256 signed nostr_token (pubkey:expiry:hmac)
- All thresholds env-var configurable (TRUST_TIER_ESTABLISHED/TRUSTED/ELITE)
New route:
- `artifacts/api-server/src/routes/identity.ts`:
- POST /api/identity/challenge — issues 32-byte hex nonce (5-min TTL, in-memory)
- POST /api/identity/verify — verifies NIP-01 Nostr signed event, consumes nonce,
upserts identity, returns signed nostr_token + trust profile
- GET /api/identity/me — look up trust profile by X-Nostr-Token header
- Route registered in routes/index.ts
Session + job binding:
- POST /api/sessions and POST /api/jobs accept optional nostr_token (header or body)
- Verified pubkey stored on the DB row; returned in create response + poll responses
- trust_tier included in GET /sessions/:id and GET /jobs/:id responses
- After session request completes: recordSuccess on complete, recordFailure on reject
- After job work completes: recordSuccess fire-and-forget
CORS: X-Nostr-Token added to allowedHeaders and exposedHeaders
Smoke tested: all existing routes pass, challenge returns nonce, /identity/me 401 without token, sessions/jobs still create correctly with trust_tier: none (expected for anonymous requests)
Previously recordSuccess/recordFailure read identity.trustScore (raw stored value)
and incremented/decremented from there. Long-absent identities could instantly
recover their pre-absence tier on the first interaction, defeating decay.
Fix: both methods now call applyDecay(identity) first to get the true current
baseline, then apply the score delta from there before persisting.
