The authoritative, source-cited, granular task list for all genuinely-remaining work to take Oshun V1 from its current verified-zero-stub baseline to fully production-complete. Every item was re-verified against current source by six parallel read-only audits (file:line cited throughout). This supersedes the "remaining gaps" framing scattered across V1_DEPLOYMENT_REQUIREMENTS.md §8/§9 and WALKTHROUGH/results/journey-e2e-quality-audit-2026-06-05-wave6.md §H — those documents are reconciled inline (see Corrections below).

What "remaining" means here. The cleanly-completable in-repo correctness/ wiring gaps are already closed (studio surface real, stub-class eliminated, five+ generation journeys wired, native triggers firing, durability/autonomy shipped, the full e2e journey suite green). What remains is: (a) a small set of real code builds over existing-but-unwired engines, (b) a handful of deploy-time inputs (creds/infra/content), and (c) two forbidden stubs that must be replaced. Each is below with a granular task breakdown.

How to read this#

Each work item uses a fixed template:

• Status today — what exists, with file:line.
• The gap — what is missing to call it done.
• External dependency — exact creds/infra/provider, or "none, pure code."
• Granular tasks — ordered - [ ] checkboxes, file-level, covering the layers that apply: domain lib → BFF store → BFF route (preHandlers + scopes) → web data layer → UI island/page → unit tests → e2e → cross-link triangle → deploy/config.
• Acceptance criteria — observable + testable definition of done.
• Verification commands — exact invocations.
• Effort / risk — S/M/L + key risks.

Effort scale: S ≈ ≤½ day · M ≈ 1–3 days · L ≈ 1–2 weeks (one engineer).

Cross-cutting rules (from CLAUDE.md — non-negotiable): zero stubs (no result-faking; fail loud or ask); wire real data end-to-end (no fixtures/ fallbacks as the product); commit + push to both branch and main; never touch libs/euterpe/** or apps/euterpe-studio-web/** (concurrent session); domain-correctness tests (assert computed values, not truthiness).

✅ Forbidden stubs found — FIXED (Quality Standards violations)#

The adversarial audit found two genuine result-faking stubs (they fabricated a result they did not compute — the exact bright line CLAUDE.md forbids). Both are now eliminated (Item 2.3(b)):

1. apps/oshun/bff/src/telegram/webhook.ts:67-71 — transcribeTelegramVoice returns the literal string `voice transcript from ${fileId}` instead of transcribing. FIXED — now resolveSttVoiceProvider({ env: process.env }).
2. apps/oshun/telegram-bot/src/index.ts:119-123 — same: returns `Telegram voice note ${fileId}`. FIXED — now resolveSttVoiceProvider({ telegramBotToken: env.botToken, env: process.env }).

The real STT provider (libs/oshun/messaging-channels/src/telegram/stt-provider.ts: Telegram getFile → download → OpenAI-compatible transcription, injectable fetch) is fail-closed — without a bot token + OSHUN_STT_API_KEY it throws stt_not_configured and the bot handler replies honestly ("could not transcribe"). It NEVER fabricates a transcript (proven by stt-provider.test.ts).

(Lower-severity, in a non-shipped advisor lib: @aphrodite/crypto-payments ExchangeRateService rate-fetch is mocked at libs/aphrodite/crypto-payments/ src/index.ts:220-235,260-269 and its EVM monitor is simulated at :855-863. This lib is not the path to wire — see Corrections + Item 4.3.)

Corrections to V1_DEPLOYMENT_REQUIREMENTS.md (verified against source)#

The deployment doc is mostly accurate but the audit found these material inaccuracies — fix the doc as part of the relevant items:

Master sequencing & dependency graph#

Build in this order — several items unblock others:

KEYSTONE (build first):
  1.1 Release-gate measurement bridge ──┬─→ 1.2 provider measurement emission
                                        ├─→ 1.3 caption-dub/a11y (media path)
                                        └─→ 1.4 AI video

SHARED PRIMITIVE:
  @oshun/payments-bridge ReceiptSigner ─┬─→ 4.1 deletion attestation
  (Ed25519 signed receipts)             └─→ 4.3 payment receipts

INTEGRATION HUB:
  adminAuditEventsStore ────────────────┬─→ 5.1 incident write verbs (emit events)
                                        ├─→ 5.3 abuse reports (emit events)
                                        └─→ 5.2 audit explorer (reads events)

RECIPIENT RESOLUTION CHAIN:
  2.1 channel-binding store ────────────┬─→ 2.3 push recipient resolution
                                        ├─→ 2.4 reminder delivery targeting
                                        └─→ 2.2 email-verify (shares transport)

INDEPENDENT (any order):
  1.5 Sophia (config) · 3.1 persona · 3.2 SSO · 3.3 LMS · 4.2 library sync
  6.x PWA/SSR tests · 7.x deploy infra

Quick wins (S, high value, do early): 1.5 (Sophia config+test), 6.1 (captive-portal correctness bug), 6.4/6.5 (SSR unit tests), 2.5 (.env.example

• health endpoint), 5.2 (port the existing admin audit explorer to web).

Genuinely blocked (document, don't fake) — UPDATED 2026-06-09 (several formerly-blocked items were unblocked by user product decisions + built): 1.6 (upload→model-governance) BUILT (user confirmed V1 scope → upload→ registry→admit() route shipped 8115643e9f); 1.4 video BUILT (curated video/video-from-image cards + fal LTX provider, d9e4d8ca9c); 4.3 in-repo composition BUILT (fail-closed payments composition, ec6897241d). What genuinely remains deploy/runtime-bound: 1.3 caption-dub dubbing/ASR ML service; the deploy halves of 1.4 (a real video safety-scanner/watermark/C2PA — the gate honestly blocks every in-repo clip until then) and 4.3 (the live InvoiceTargetProvisioner settlement provider — chain RPC/BTCPay/OpenNode, which owns rate+amount+address so the BFF never fabricates them); 3.2-login (a live IdP); plus all Playwright e2e + browser visual passes (RAM/infra) and Part-7 provisioning. For each, the in-repo seam ships fail-closed and the external capability binds at deploy.

Part 1 — AI Generation Providers & Release Pipeline#

1.1 Release-gate measurement bridge (KEYSTONE — build first)#

• Status today: The Isis release gate is fully wired and enforced — evaluateGenerationRelease runs on every worker output (generation/jobs-route.ts:237), maps to complete/needs_review/blocked, fail-closes on a missing/invalid measurement (generation/release-gate.ts:140-145, tested release-gate.test.ts:72-92). The canonical contract is CanonicalReleaseGateMeasurement (libs/oshun/generation-control-isis/src/release-gate-model.ts:289). But no code anywhere constructs a measurement — grep for safetyScanScore: finds only the gate + a type, never a builder. Executors only forward a measurement if the adapter supplies one; none do.
• The gap: A shared, tested helper that builds a valid measurement from real per-provider governance signals (safety scan, watermark coverage, C2PA-present, quality, output kind). Without it, items 1.2/1.3(media)/1.4 all dead-end at jobs-route.ts:237.
• The exact contract a provider must emit (all fields required, runtime-checked): outputKind (image/video/audio/3d-model/…); safetyScanScore∈[0,1] floor 0.9 (release-gate-model.ts:208,339); provenanceManifestPresent (false→block, :354); watermarkCoverage∈[0,1] per-kind floor (image/texture/material=1, video/audio/ animation=0.99, else 0; :189,384); qualityAggregate∈[0,1] per-kind floor (image/audio/texture=0.75, video/anim/material=0.7, 3d=0.65…; :174,407→review); policyComplianceClear/rightsAndLicenseClear/outputShapeValid (false→block, :421/432/447); humanReviewTriggers[] (:270, non-empty→review unless reviewerAssigned); reviewerAssigned, customerFacing. Optional releaseAdmissions[] (dispatch-guard.ts:29, any admitted:false→block) and releaseKind:'analysis' escape hatch for non-media outputs only (release-gate.ts:132).
• External dependency: None for the helper (pure code). The signals it consumes are external (a real safety scan, a watermarker, a C2PA signer) — see 1.2.
• Granular tasks:
  • Create apps/oshun/bff/src/generation/provider-measurement.ts exporting buildReleaseMeasurement(signals): CanonicalReleaseGateMeasurement — maps a provider's safety-scan result, watermark-coverage ratio, C2PA-present flag, quality score, and output kind into the canonical envelope. Must never default a signal to a passing constant — an absent signal yields an output that the gate (correctly) blocks.
  • Unit test provider-measurement.test.ts: feed the helper's output through evaluateGenerationRelease and assert complete for a clean image, and the correct blocked/needs_review for each below-floor field (one assertion per floor — would fail if a floor regressed or a field were dropped).
  • Doc: correct V1_DEPLOYMENT_REQUIREMENTS.md §8 to state that a credential activates the provider call but the measurement bridge is what releases the output to the customer.
• Acceptance criteria: A single tested helper produces a valid measurement; feeding it through the live gate yields complete for a clean image and the exact blocked/needs_review decision for every below-floor field. No signal is fabricated.
• Verification: cd apps/oshun/bff && npx vitest run src/generation/release-gate.test.ts src/generation/provider-measurement.test.ts
• Effort / risk: S. Risk: the single highest stub-temptation in the repo — hardcoding safetyScanScore:0.95/watermarkCoverage:1 to "make it pass" is a forbidden stub. Each signal must trace to a real scan/watermark/signature.

1.2 Provider credential matrix + measurement emission#

• Status today: All four resolvers exist, are fail-closed, and are registered in the worker (apps/oshun/bff/src/server.ts:416-435): illustration/explainer → resolveImageProviderGenerate() (generation/image-provider-env.ts:76, Stability SD3.5, OSHUN_STABILITY_API_KEY); music → resolveMusicProviderGenerate() (Suno, OSHUN_SUNO_API_KEY); sky-briefing → resolveSkyBriefingProviderGenerate() (Meshy, OSHUN_MESHY_API_KEY); narration → resolveNarrationProviderGenerate() (ElevenLabs, OSHUN_ELEVENLABS_API_KEY+_VOICE_ID). Front doors wired (curated cards → createCuratedGenerationExecutor; music /v1/isis/music/generate; sky-briefing /v1/isis/nyx-3d/generate).
• The gap: None of the four adapters emit a releaseMeasurement — adaptImageProviderGenerate returns only {id,url} and discards the provider response (which even carries metadata.c2pa.signed, types.ts:524). Consequence: even a perfectly-credentialed job lands blocked/governance_measurement_absent.
• External dependency: Per-provider credentials (deploy-bound); a safety-scan signal (Stability has no top-level safety field — map its moderation verdict or run a classifier); a watermark step to legitimately claim coverage; a C2PA manifest (OSHUN_LIVING_SCENES_C2PA_*; signer exists at libs/yemaya/living-scenes-runtime/src/provenance/c2pa/ed25519-signer.ts:30).
• Granular tasks:
  • Build 1.1 first. (Done in the keystone session — provider-measurement.ts.)
  • (image) Extend image-provider-env.ts adaptImageProviderGenerate to read the full ImageGenerationResponse (c2pa.signed, dimensions, moderation verdict), call buildReleaseMeasurement, return {id,url,releaseMeasurement}. (DONE — the adapter now ALWAYS emits a releaseMeasurement (closing the keystone gap where it discarded governance signals + every image dead-ended at governance_measurement_absent): provenanceManifestPresent from result.metadata?.c2pa?.signed, outputShapeValid from the url, policyComplianceClear from the moderation flag, rightsAndLicenseClear true (first-party generation), watermark/quality null (deploy-bound, below). The executor already forwards it (image-executor.ts:68). 10 image-provider-env tests fed through the REAL gate.)
  • (image) Implement a real safetyScanScore source (map Stability moderation/finishReason, or add an output safety-scan pass) — no constant. (DONE — generation/image-safety-classifier.ts: a fail-closed ImageSafetyClassifier + resolveImageSafetyClassifier(env) + createOpenAiCompatibleImageSafetyClassifier — POSTs the output image to an OpenAI-moderations-compatible vision endpoint (OSHUN_IMAGE_MODERATION_API_BASE/_API_KEY/_MODEL) and maps the per-category violation scores to safetyScanScore = 1 − max(violation). NO CONSTANT: unconfigured → null → gate blocks; a moderation HTTP error → throws → the adapter catches → null → blocks (never released unscanned, never a fabricated passing score — verified by 6 classifier tests + 5 gate-fed adapter tests incl. the throwing-classifier path).)
  • (image) Add/verify a watermark step before asserting coverage; wire C2PA signing via the ed25519 signer for provenanceManifestPresent. _(provenance is now READ from the provider response (metadata.c2pa.signed → Stability=false → honestly blocks on provenance). The remaining BFF-side watermark step + C2PA SIGNING are deploy-bound: both need the generated bytes fetched + processed (sharp watermark / ed25519 C2PA manifest) + RE-STORED in the asset store (OSHUN_ASSET_STORE_\*) so the signed/watermarked bytes are what's delivered — claiming coverage/provenance without persisting the processed output would be dishonest. So the measurement honestly blocks on watermark (null→image floor 1) + provenance until those deploy-bound steps land.)_ _2026-09-18: open for an agent. "Deploy-bound" meant an asset store; the dev stack has one (MinIO on :9000, docker/docker-compose.dev.yml). The residue is the step itself: fetch the generated bytes, watermark them, sign a C2PA manifest with the ed25519 signer, store the processed bytes and deliver those, with a spec against the local store._
  • (narration) Same in narration-provider-env.ts (outputKind:'audio'). _(DONE — and this is the genuinely-VALUABLE one of the three remaining adapters: for TTS the output content IS the spoken text (ElevenLabs faithfully speaks the input), so a real text-moderation scan of request.text is a faithful output-content safety scan, not a proxy. Built generation/text-safety-classifier.ts — a fail-closed resolveTextSafetyClassifier(env) + OpenAI-moderations-compatible adapter (OSHUN_TEXT_MODERATION_API_BASE/_API_KEY/_MODEL, falling back to the shared OSHUN_IMAGE_MODERATION_\*endpoint) →safetyScanScore = 1 − max(category violation); unconfigured → null → gate blocks; HTTP error → throws → adapter catches → null → blocks. NO CONSTANT. The adapter now ALWAYS emits a measurement: safety from the classifier, provenance false (ElevenLabs no C2PA), watermark/quality null (deploy-bound), policy from the moderation flag, rights true (first-party licence — domain truth). cloned-voice-used deliberately NOT set — narration uses a FIXED, deploy-configured, platform-licensed voice (OSHUN*ELEVENLABS_VOICE_ID), not a per-request clone of a real person; a future per-user voice-cloning surface would set it. 7 text-classifier + 10 narration tests fed through the REAL gate (no-classifier→block-on-safety (score 0, never a constant); clean→block-on-provenance+watermark NOT safety; flagged→policy+safety; cloned-voice trigger absent; moderation-outage→fail-closed; scans the actual spoken text). Audio full release still needs the deploy-bound audio watermark + C2PA + asset-store, like image.)*
  • (music) Same in music-provider-env.ts (outputKind:'audio'). (DONE — emits an honest measurement. Curated music is INSTRUMENTAL (no lyrics/vocals — translateMusicRequest hard-sets instrumental:true) and there is NO in-repo audio-content safety scanner, so there is no honest output-safety signal: safetyScanScore:null→0→the gate BLOCKS at the safety floor (never released ungoverned, never a fabricated score), exactly mirroring image's no-classifier fail-closed path (policyComplianceClear:false too). Provenance false (Suno no C2PA), watermark null (audio floor 0.99), quality null, rights true (first-party licence). Emitting the measurement replaces the generic governance_measurement_absent with the SPECIFIC missing-signal block reasons (better deploy diagnostics) + lands the scaffolding a deploy-bound audio scanner/watermark/C2PA plugs into. 7 tests fed through the REAL gate (blocks on safety+provenance+watermark; rights clear; nothing fabricated).)
  • (sky-briefing) Same in sky-briefing-provider-env.ts (outputKind:'3d-model', watermark floor 0 → N/A but the envelope is still required or it blocks). (DONE — honest measurement: no in-repo 3D-geometry safety scanner → safetyScanScore:null→blocks at the safety floor (never fabricated); provenance false (Meshy no C2PA); policyComplianceClear:false (no scan ran); watermark null but the gate treats the 3d-model watermark floor 0 as N/A (so it does NOT block on watermark — the test asserts not.toContain('watermark')); quality null; rights true. 7 tests fed through the REAL gate (blocks on safety+provenance, NOT watermark; rights clear; nothing fabricated).)
  • (executors) Confirm music/narration/sky-briefing executors forward releaseMeasurement (image already does, image-executor.ts:68); add the spread where missing. (DONE — extended NarrationProviderGenerate, MusicProviderGenerate, and SkyBriefingProviderGenerate return types with the optional releaseMeasurement, and added the conditional spread to all three executors (createNarrationGenerationExecutor/Music/SkyBriefing), mirroring image-executor.ts:68 verbatim. The worker's evaluateGenerationRelease strips the envelope and evaluates it. Full generation dir green (132 tests), BFF tsc 0, eslint 0.)
  • (unit) Per *-provider-env.test.ts: assert the adapter emits a measurement that clears (or correctly fails) the per-kind floors; assert fail-closed (no fabricated measurement) when the safety scan is unavailable. (DONE for ALL FOUR providers — each *-provider-env.test.ts runs the emitted measurement through the REAL evaluateGenerationRelease and asserts per-floor decisions, not truthiness. IMAGE (image-provider-env.test.ts, 10) + image-safety-classifier.test.ts (6): no-classifier→blocked-on-safety (score 0, never a constant); clean→blocked on deploy-bound provenance+watermark NOT safety; flagged→policy+safety; C2PA passthrough; outage→fail-closed. NARRATION (narration-provider-env.test.ts, 10) + text-safety-classifier.test.ts (7): same matrix over the text classifier + asserts the cloned-voice trigger is absent + the actual spoken text is scanned. MUSIC (music-provider-env.test.ts, 7): blocks on safety+provenance+watermark, rights clear, nothing fabricated. SKY-BRIEFING (sky-briefing-provider-env.test.ts, 7): blocks on safety+provenance, NOT watermark (3d floor 0 N/A), rights clear. Full generation dir green (132 tests).)
  • (e2e) Extend jobs-route.test.ts: enqueue→process→status with a measurement-emitting provider → complete; with a measurement-less one → blocked. (DONE — verified 2026-06-09: the described enqueue→process→ status coverage ALREADY EXISTS in jobs-route.test.ts (13 tests, all green) and was mislabeled a "RAM-bound e2e" — it is a vitest test, not a browser e2e. The two exact cases the box asks for: (1) it('enqueues (202) then completes a job whose output clears the Isis release gate') injects a provider executor returning passingImageMeasurement() → asserts status==='complete' (measurement-emitting → complete); (2) it('BLOCKS a produced output that carries no governance evidence (fail-closed)') injects an executor returning no releaseMeasurement → asserts status==='blocked' + error==='governance_measurement_absent' (measurement-less → blocked). Plus below-floor-safety→blocked, below-floor-quality→needs_review, malformed-measurement→blocked, provider-error→failed, retry→complete — every gate outcome fed through the REAL evaluateGenerationRelease, asserting specific statuses not truthiness. Re-ran npx vitest run src/generation/jobs-route.test.ts → 13/13 pass in 125ms.)
  • (deploy) Document per-provider activation set (key + safety + watermark 2026-09-18: open for an agent as documentation: the residue is the section 8 table of what each provider needs before its output may be released; the audio and 3D scanners it would name do not exist and are their own tasks.
    • C2PA) in §8. _(Image + narration moderation both documented in .env.example: OSHUN_IMAGE_MODERATION__(image vision scan) andOSHUN*TEXT_MODERATION*_ (narration spoken-text scan, falling back to the image endpoint) with the fail-closed + "releases only with moderation + watermark + C2PA" notes, and a note that music (instrumental) + sky-briefing (3D) have no in-repo output-content scanner so both honestly block until deploy-bound audio/3D scanners land. The remaining audio/3D safety+watermark services are deploy-bound (no standard endpoint to document yet).)_
• Acceptance criteria: With a credentialed provider AND the bridge, a curated-card submit → process → GET /v1/generation/jobs/:id returns complete + asset + governance.permitted:true; without a real safety scan it stays blocked (never released ungoverned).
• Verification: cd apps/oshun/bff && npx vitest run src/generation/
• Effort / risk: M each. Highest stub-risk in the codebase (see 1.1).

1.3 caption-dub + accessibility-pass providers#

• Status today: Executors wired fail-closed (server.ts:428,434). accessibility-pass is partly real already: resolveAccessibilityProvider (accessibility/deterministic-accessibility-provider.ts:74) runs contrast-analysis in-repo (decodes asset bytes → WCAG ratio, :30-44) when the asset store is configured; ML passes (alt-text/transcript) honestly return requires-external-provider (:54-62); analysis output releases via the releaseKind:'analysis' exemption. The asset-store seam exists + is fail-closed: resolveAssetStore() (assets/asset-store.ts:25, wraps @oshun/storage S3, gated on OSHUN_ASSET_STORE_*). caption-dub has no provider — createCaptionDubExecutor(null); visual-dubbing lib confirmed planners-only (no fetch/execute).
• The gap: caption-dub needs a dubbing/ASR/TTS service + asset store + output store + a media releaseMeasurement. accessibility-pass ML passes need an alt-text/transcript service; the deterministic contrast path just needs the asset store configured.
• External dependency: caption-dub → dubbing/ASR ML service + object store + measurement signals. a11y → object store (for the deterministic path) + optional alt-text/transcript ML service.
• Granular tasks:
  • (a11y, lowest-hanging) Set OSHUN_ASSET_STORE_*; submit an accessibility-pass contrast-analysis card; confirm complete with a real WCAG ratio. Add a test injecting an AssetResolver returning known PNG bytes and assert expect(ratio).toBeCloseTo(4.5,1) (domain-correctness). _(Domain-correctness test DONE — accessibility/ contrast-analysis.test.ts (5 tests) drives the pure dominantPairContrast (RGBA, no PNG-decode needed — cleaner + tests the SAME WCAG math the AssetResolver path wraps). Asserts REAL computed WCAG values, not hardcoded: black on quantized-white (#f8f8f8, since 255 & 0xf8 = 248) → toBeCloseTo(19.77,1) + AA + AAA; the AA-boundary #707070-on-white → ≥4.5 but <7 (passes AA not AAA); two near grays (#808080/#888888) → <1.5, fails AA; dominant-pair selection (background=most-frequent); transparent pixels (alpha<128) skipped; single-colour → throws. The hand-derived 19.77 / 4.66 WCAG values matched the impl exactly. The remaining OSHUN_ASSET_STORE_\* activation + the end-to-end card→completeconfirm are deploy-bound, not code.)_ _2026-09-18: open for an agent. The residue is the end-to-end confirm against the dev stack's MinIO: setOSHUN*ASSET_STORE*\*through a throwaway env script, submit the card, and assertcomplete with a real ratio._
  • (caption-dub) Create generation/caption-dub-provider-env.ts (mirror narration-provider-env.ts): resolve a dubbing client from env (fail-closed null), inject the AssetResolver from resolveAssetStore, emit {id,url,releaseMeasurement} (outputKind:'video'|'audio'). _(DONE 2026-06-10 — caption-dub-provider-env.ts resolves the REAL ElevenLabs Dubbing API (POST /v1/dubbing multipart → poll GET /v1/dubbing/{id} → download /audio/{lang} + /transcript/{lang}, xi-api-key auth) from OSHUN_DUBBING_ELEVENLABS_API_KEY (falls back to the narration OSHUN_ELEVENLABS_API_KEY), gated fail-closed on BOTH the key AND OSHUN_ASSET_STORE_\*(asset-store.ts grew a read-write AssetObjectStore: storeBytes= S3 upload + signed download URL — dubbed outputs persist atcaption-dub/{dubbingId}/{lang}.{ext}). Multi-locale: BCP-47 tags collapse to primary-subtag dubbing languages (es-MX+es→ oneesdub), each gets its own dub/store/scan, and the executor seam forwards a per-localeoutputs[]. 25 new tests (caption-dub-provider-env.test.ts) assert the exact multipart fields, poll/timeout/failed paths, stored keys/bytes, min-score aggregation, and gate outcomes through the REAL evaluateGenerationRelease.)_
  • (caption-dub) In server.ts:428 replace createCaptionDubExecutor(null) with createCaptionDubExecutor(resolveCaptionDubProvider()). (DONE 2026-06-10 — server.ts now wires createCaptionDubExecutor(resolveCaptionDubProviderGenerate()); fail-closed provider_not_configured unless key + asset store are both present, verified by test "feeds a fail-closed executor when unconfigured".)
  • (a11y ML) Add an optional ML a11y provider behind its own env; compose so contrast stays in-repo and ML passes use the service when configured. (DONE 2026-06-10 — accessibility/ml-accessibility-service.ts: an OpenAI-compatible ML service behind OSHUN_A11Y_ML_API_BASE + OSHUN_A11Y_ML_API_KEY (model overrides OSHUN_A11Y_ML_VISION_MODEL / OSHUN_A11Y_ML_TRANSCRIPTION_MODEL): alt-text via vision /chat/completions (image as a magic-byte-sniffed data URL + a screen-reader-specific instruction), transcript via Whisper-compatible /audio/transcriptions multipart (filename from sniffed audio container). Unrecognised bytes / HTTP errors / empty model output all THROW — never a fabricated alt text or transcript. Composed in deterministic-accessibility-provider.ts: contrast stays in-repo, alt-text/transcript run the ML service when configured and report requires-external-provider (with the error detail) when absent or failing; caption-verification stays honestly external (needs the caption track). AccessibilityPassResult grew altText/transcript. 12 new ML-service tests + 6 new/extended provider-composition tests, BFF suite green + tsc clean.)
  • (measurement) Build the media releaseMeasurement via 1.1; set cloned-voice-used if voice cloning is used. (DONE 2026-06-10 — the adapter builds the media measurement via 1.1's buildReleaseMeasurement: outputKind 'video'|'audio' from the dubbed media's content type; safetyScanScore = a REAL text-moderation scan of the DUBBED TRANSCRIPT (SRT → spoken text; the same faithful output-content reasoning as narration), MINIMUM across locales, null→blocked on any scan/transcript outage or absent classifier; provenance false + watermark null + quality null (honestly absent, deploy-bound); and humanReviewTriggers:['cloned-voice-used'] on EVERY dub — ElevenLabs dubbing clones the source speakers' voices — so a dub releases only with an assigned reviewer. Fed through the real gate in tests: clean scan → blocked on provenance+watermark+human-review, NOT safety-scan.)
  • (unit) caption-dub: locale normalization (translateCaptionDubRequest)
    • measurement forwarding + fail-closed without provider. a11y: ML passes return requires-external-provider without the service. (Done — verified 2026-06-09, 9 tests green: caption-dub-executor.test.ts (4) covers translateCaptionDubRequest de-dup + lower-case of BCP-47 target locales + keeps the source asset, fail-closed provider_not_configured with no provider, runs through an injected provider, and forwards the release measurement; accessibility-pass-executor.test.ts (5) covers the same fail-closed + de-dup, the no-url releaseKind:analysis exemption, and MEDIA measurement forwarding. These exercise the in-repo translation + fail-closed seams that need no provider; the dubbing/ASR/a11y ML providers stay deploy-bound.)
  • (e2e) Curated-card submit → enqueue → process → status for both kinds with injected providers. (DONE 2026-06-10 — jobs-route.test.ts grew an "asset-transform cards through the pipeline" block (3 tests, 16/16 green): caption-dub runs the REAL adapter (dubbing/store/classifier doubles) through enqueue→process→status — the dub is produced + stored (per-locale outputs asserted) but fail-closes at the gate on provenance+watermark+human-review (clean transcript scan, so NOT safety-scan); a second case with fully-passing audio evidence releases complete; accessibility-pass runs the real deterministic provider + ML double over an encoded PNG → complete analysis report with the REAL WCAG ratio toBeCloseTo(19.77,1) + AA + the ML alt text, and the stripped releaseKind envelope asserted.)
  • (cross-link + deploy) Link the curated-card journey; document the dubbing/ASR/a11y env + OSHUN_ASSET_STORE_* in §8/§9. (DONE 2026-06-10 — .env.example documents the new OSHUN_DUBBING_ELEVENLABS_API_KEY/OSHUN_DUBBING_API_BASE (falls back to the narration key) + OSHUN_A11Y_ML_API_BASE/_API_KEY/_VISION_MODEL/ _TRANSCRIPTION_MODEL blocks with the full fail-closed/cloned-voice/ transcript-scan semantics, and the asset-store block now notes dubbed outputs persist there with signed URLs. V1_DEPLOYMENT_REQUIREMENTS.md §8 table rows for caption-dub + accessibility-pass now carry their real env vars + providers ("all eight curated-card kinds ship a concrete in-repo provider"), §9's provider row became an infrastructure row (store/keys/moderation/review-rota/provenance), and the Summary was re-counted. Cross-link: WALKTHROUGH/studio/generation/studio-generation-curated-cards.md's open-gap bullet updated from "providers deploy-bound" to the real provider wiring, leaving the surface-level asset-picker as the remaining UI gap.)
• Acceptance criteria: With OSHUN_ASSET_STORE_*, a contrast-analysis card returns a real WCAG verdict; with a dubbing service + store, a caption-dub card returns dubbed media that clears the gate; without them, both honestly 503/blocked.
• Verification: cd apps/oshun/bff && npx vitest run src/generation/caption-dub-executor.test.ts src/generation/accessibility-pass-executor.test.ts src/accessibility/
• Effort / risk: S (activate deterministic a11y) / L (caption-dub). Risk: returning a fabricated dub/transcript instead of requires-external-provider.

1.4 AI video model for Living Scenes (ComfyUI/RunPod enhancement) (BUILT 2026-06-09 — via curated cards + fal LTX-Video; user: "build the content-drop producer too" → "proceed")#

2026-06-09 — AI-VIDEO BUILT (commit d9e4d8ca9c) via the CURATED-CARD front-door (the same admission→enqueue→worker→adapter→gate chain as the image keystone), NOT the living-scenes render-route / /v1/isis/generate variant the granular tasks below describe — so those alternative boxes stay [ ] (different mechanism). The user chose text-to-video + image-to-video with richer-control inputs via AskUserQuestion. Two new curated cards (video, video-from-image) in @isis/curated-cards (types + exhaustive-switch validators + catalog), and the BFF vertical: generation/video-executor.ts (seam + two translators + two fail-closed executors forwarding governance evidence) + generation/video-provider-env.ts (resolves the REAL fal.ai-hosted LTX-Video provider from @isis/ai-providers — generateVideo t2v + imageToVideo i2v — fail-closed null without OSHUN_VIDEO_FAL_KEY) + two worker-registry kinds. HONEST GATE POSTURE: no in-repo video safety scanner / watermarker / C2PA signer, so the measurement carries safetyScanScore=null + provenance=false + watermark=null → every in-repo clip is faithfully BLOCKED (specific missing-signal reasons, never a fabricated score), released only once those deploy-bound steps land — mirrors the music/sky-briefing adapters. The card was the genuine product gap (a VideoCardInputs contract); the provider already existed. Used the real LTX provider, NOT the ComfyUI provider-manager (the cleaner same-as-image path). Added the @isis/ai-providers/providers/video-generation tsconfig path mapping (vitest's resolver needs it). 23 tests (6 lib + 7 executor + 8 provider-env-through-real-gate

• 2 curated-exec) + catalog enumeration; generation suite 162 green; tsc/eslint/ stub-scan clean; .env.example documents the vars.

• Status today: The deterministic V1 producer works with no model: POST /v1/living-scenes/render → renderLivingSceneSegmentToPng, seizure-gated, watermarked PNG (living-scenes/render-route.ts:42,66). The ComfyUI/RunPod client is real + ready (libs/yemaya/comfyui-integration/src/provider-manager/provider-manager.ts:1 — multi-provider, failover, submit/poll). The gate front-door POST /v1/isis/generate exists but is wired with notConfiguredProviderExecutor() (server.ts:248) → 503.
• The gap: No ComfyUI executor is injected (neither /v1/isis/generate nor a video worker kind). The render route has no provider seam and does not call the gate — so the doc's "flows through the gate" is not currently true via render. No releaseMeasurement from the video client.
• External dependency: A running ComfyUI/RunPod endpoint + model weights + creds; measurement signals (1.1); OSHUN_LIVING_SCENES_C2PA_*.
• Granular tasks:
  • Create generation/video-provider-env.ts (resolve the real fal LTX-Video provider from env; adapter over t2v/i2v → {id,url,releaseMeasurement}; fail-closed null). DONE d9e4d8ca9c (LTX-Video, not the provider-manager).
  • Create generation/video-executor.ts (mirror image-executor.ts; outputKind:'video'). DONE — two executors (t2v + i2v), fail-closed, forward governance evidence verbatim.
  • (preferred) Add video / video-from-image executors to the worker registry (server.ts) so they flow through the wired gate. DONE.
  • Not built — rejected alternative: (optional) Replace notConfiguredProviderExecutor() for /v1/isis/generate — NOT done (curated-card front-door used instead).
  • Not built — rejected alternative: (render-route, if chosen) living-scenes render-route variant — NOT chosen (curated-card path is the cleaner same-as-image front-door).
  • Build the video releaseMeasurement (1.1). DONE — honest fail-closed (safety/provenance/watermark all absent → blocks; never fabricated).
  • (unit) Inject a fake provider: unconfigured → fail-closed; configured → measurement fed through the REAL gate asserts blocked-on-safety/provenance/ watermark; t2v vs i2v routing; out-of-enum aspect/resolution defaults. DONE (8 provider-env + 7 executor tests). NB an in-repo "measurement-clear → complete" case is impossible without a safety scanner, so the tests assert the honest always-blocked path, not a fabricated pass.
  • (deploy) Document the endpoint + weights + creds in §2/§8 (the .env.example OSHUN_VIDEO_* block is done; the §2/§8 deploy doc is not). (DONE 2026-06-09 — corrected V1_DEPLOYMENT_REQUIREMENTS.md, which had gone factually STALE after 1.4 shipped: §2 now describes the built fal LTX-Video curated-card path (OSHUN_VIDEO_FAL_KEY, fail-closed, gate-blocked until a deploy-bound video safety-scan/watermark/C2PA lands) + keeps the ComfyUI path as the optional self-hosted alternative; §8 added the video/video-from-image provider-table row + corrected "six → eight V1 curated cards"; §9 corrected the now-FALSE "video is not a V1 curated card" claim (it became one in 1.4 — only general-3D remains out of scope). Also un-stale'd §8's "per-provider signal extraction is the remaining wiring" paragraph — all nine executors now forward measurements (sessions 6–7).)
• Acceptance criteria: With a ComfyUI/RunPod endpoint, a video job returns generated, watermarked, seizure-safe video that clears the gate; without it, 503/blocked; the deterministic render path is unaffected.
• Verification: cd apps/oshun/bff && npx vitest run src/living-scenes/ src/isis/generation-route.test.ts src/generation/ · cd libs/yemaya/comfyui-integration && npx vitest run
• Effort / risk: L. Risk: never ship a generative path that skips the gate or the seizure check.

1.5 Sophia /answer prose synthesis (already built — config + test + doc only)#

• Status today: Fully implemented and wired (corrects §9). Retrieval + extractive grounding real (domain-stubs.ts:306-374, sophia/answer-composer.ts:74, abstention :80-83). The abstractive seam: createOpenAiCompatibleSynthesizer (sophia/answer-synthesizer.ts:139 — temp 0, JSON mode, 6s timeout, honesty sanitization at :98 drops un-cited claims), resolved fail-closed by resolveSophiaAnswerSynthesizer (answer-synthesizer-env.ts:16, needs OSHUN_LLM_API_BASE+_KEY+_MODEL), wired app.ts:527, used with fail-soft fallback to extractive on any error (domain-stubs.ts:335-360). Web form already posts it (app/sophia/SophiaAskForm.tsx:27).
• The gap: Effectively none in code: (1) set 3 env vars; (2) reconcile the stale routes/sophia.ts:20 503 comment; (3) optionally add an e2e proving the LLM path
  • fallback.
• External dependency: An OpenAI-compatible LLM endpoint + key (any vendor/self-host).
• Granular tasks:
  • Add OSHUN_LLM_API_BASE/_API_KEY/_MODEL to deploy config; add a §8 row.
  • Fix the stale comment at routes/sophia.ts:20; correct §9 to "seam built + wired; activate via env."
  • (e2e) Inject a fetchImpl (the synthesizer accepts one, :129) returning a canned completion; assert the abstractive answer cites only valid Nisaba ids; assert a 500/timeout falls back to extractive (no 500 surfaced, grounding intact).
  • (unit) Confirm sanitize (:98) drops a claim citing an unknown id and coerces model-only→synthesized (extend tests if not already covered).
• Acceptance criteria: With OSHUN_LLM_* set, POST /v1/sophia/answer returns abstractive prose whose every claim cites a real Nisaba id, abstaining when evidence is absent; with the endpoint erroring it returns the extractive answer (never a 500, never un-cited prose); unset → extractive composer answers.
• Verification: cd apps/oshun/bff && npx vitest run src/sophia/ src/routes/
• Effort / risk: S. Honesty guards + fallback already enforced; minimal risk.

1.6 upload → model-governance enforcement (BUILT 2026-06-09 — user confirmed V1 scope)#

• Status today: The real model-governance is the output gate (1.1), already live. The three pieces §9 implies should connect do not: Civitai intake is an image/LoRA review verdict with no governance metadata + no registry entry (isis/civitai-intake-store.ts); ModelGovernanceStore.admit() (isis/model-governance-store.ts:190) is for already-registered 3D models with full license metadata (@isis/model-governance-3d, returns unknown_model for unregistered, :195); there is no in-BFF 3D-model upload/registration flow to produce the modelId + license admit() needs.
• The gap: Bridging them requires inventing an upload contract that doesn't exist.
• External dependency: Not creds/infra — a missing product contract (an upload that captures license + IP + registers into the registry + calls admit()).
• Granular tasks:
  • (decision, blocking) Confirm with product whether upload→registry→admit() is in V1 scope. If NO → correct §9: "covered by the output gate (1.1); upload-admission deferred — no upload contract." If YES, then: (DECIDED 2026-06-09 — user confirmed upload IS in V1 scope; built below.)
  • Define the upload contract (artifact + license category + IP declaration → ThreeDModelGovernanceLicenseRegistryEntry, model-governance-store.ts:5). (The route validates a full ThreeDModelGovernanceLicenseRegistryEntryInput: modelId/displayName/licenseName + a valid licenseCategory (incl. the operator-supplied category) + the COMPLETE per-right matrix (all six rights, each status+commercialStatus from the real enums) — a partial or malformed license is rejected, never silently defaulted.)
  • Make the 3D license registry durable/writable (today static DEFAULT_3D_MODEL_LICENSE_REGISTRY, :162). (ModelGovernanceStore.register() rebuilds the registry with the new entry via create3DModelLicenseRegistry — validates + de-dupes (additive, never overwrites a curated id, never half-writes). Snapshot-durable: wireDurableModelGovernance(dbHandle.store) (server.ts) persists the operator uploads + re-registers them at boot, so an uploaded model survives a restart; a now-invalid/colliding persisted entry is skipped defensively.)
  • Add POST /v1/admin/isis/model-governance/upload (admin-scoped, mirror admin-model-governance.ts) that registers then admit()s at the boundary. (Built — register → admit at the boundary (server-stamped evaluationId): 201 { registered, assessment } / 409 duplicate_model / 400 invalid_payload / 403 non-admin. 25 tests: 12 store (admit + register + durability) + 4 upload route (201 register+admit+GET-resident, 409 duplicate, 400 malformed, 403 scope). tsc + eslint clean.)
  • (tests) Domain-correctness: non-commercial license in a commercial-SaaS topology → deny/requiresReview; prohibited-IP prompt → blocked. (Done — verified 2026-06-09: new apps/oshun/bff/src/isis/model-governance-store.test.ts (6 tests) drives the live ModelGovernanceStore.admit() over known-correct @isis/model-governance-3d verdicts: flexicubes (non-commercial) in a serverless-burst commercial-saas deployment → commercial DENY → admitted: false; permissive trellis-2 + a "Pikachu/Pokemon" prompt → IP DENY → blocked (proves the stricter-of-two); permissive + no IP → admitted; unknown_model + duplicate_evaluation rejected (never fabricates a posture); the record carries BOTH sub-verdicts. Tests the EXISTING registered-model admission — the upload→registry contract above stays product-blocked.)
• Acceptance criteria: Either the doc is corrected (real model-governance = output gate, upload-admission out of scope), or an upload registers + admits a model and a verdict is recorded + surfaced.
• Verification: cd apps/oshun/bff && npx vitest run src/isis/model-governance-store.test.ts
• Effort / risk: S to confirm-blocked + doc-fix; L if a real contract is built. Risk: do NOT fabricate a fake upload→admit bridge to "close" it.

Part 2 — Messaging, Reminders & Notifications#

Foundation is real, not stubbed. Every transport (libs/oshun/messaging-channels/ src/transports.ts), the delivery router (delivery.ts:91), the config gate (provider-config-env.ts:49, all-vars-present test :56-129), the reminder cycle/worker, and all four producer mappers (reminder-producers.ts) are production-grade with passing tests. Remaining work = wiring + UI + domain bulk queries + creds.

2.1 Channel-binding UI (WhatsApp / SMS / email, per-user)#

• Status today: "Hardcoded demo array" CONFIRMED — DEMO_SERVICES (apps/oshun/web/src/components/ProfileSettingsPanel.tsx:145-156), rendered :1367-1437, Connect/Manage button :1416-1433 has no onClick. Telegram is the only real channel-bind (routes/telegram.ts:61-87) but it's not persisted. TelegramChannelBindingsStore (messaging-channels/telegram-bindings-store.ts:111)
  • admin routes are for editorial channel publishing — different concern, don't conflate. MessageRecipient already models all addresses (delivery.ts:25-34). Device tokens persist (routes/device-tokens.ts); no email/SMS/WhatsApp recipient store exists.
• The gap: Per-user, per-channel binding lifecycle (request → send code → verify → mark verified → unbind), a durable store, BFF routes, a real UI replacing DEMO_SERVICES, and resolution of bindings into MessageRecipient at delivery time.
• External dependency: SMS verify → Twilio; WhatsApp → Meta; email → SendGrid. Store + routes + UI are pure code, ship fail-closed (binding stays pending, verify-code send returns missing-config without creds).
• Granular tasks:
  • (domain lib) libs/oshun/messaging-channels/src/channel-bindings.ts: BindableChannel='email'|'sms'|'whatsapp', ChannelBinding{userId,channel,address, status,codeHash,codeExpiresAt,verifiedAt,attempts}, generateVerificationCode() (crypto 6-digit), constant-time hashCode/verifyCode, pure requestBinding/ confirmBinding/unbind reducers; export from index. (Built + exported. Type named BindableChannelBinding (not ChannelBinding) to avoid a barrel collision with preferences.ts's existing verified-opt-in ChannelBinding. Crypto uses @noble/hashes SHA-256 + the Web Crypto CSPRNG (getRandomValues, rejection-sampled, no modulo bias) — NOT node:crypto, which the lint rule forbids in this client-transpiled lib (webpack noops it). Constant-time hex compare; salt = the binding identity so a code can't be replayed across addresses; status machine pending→verified/locked/unbound with a bounded attempt budget + TTL expiry. The BFF store / route / recipient-resolution / UI are the deferred wrappers over this foundation.)
  • (domain tests) channel-bindings.test.ts: code expiry, max-attempts lockout, wrong-code rejection, idempotent re-request, unbind, constant-time path. (15 domain-correctness tests: code format + crypto variety (200 draws → >50 distinct), issued-code verifies, custom TTL, wrong-code rejection, cross-address non-replay (salt), malformed-hash → false (no throw), verify clears the secret, 5-attempt lockout (then even the correct code is refused), expiry-beats-correct-code, not-pending, re-request rotates the code + resets attempts, unbind clears. All green; lint + tsc clean.)
  • (BFF store) apps/oshun/bff/src/messaging-channels/channel-bindings-store.ts (mirror telegram-bindings-store.ts Map+reset); snapshot-durable like reminders (reminders-route.ts:65-75). (Per-(user,channel) nested Map wrapping the domain reducers; request/confirm/unbind/list/get + isBindableChannel guard; the full binding (incl. code hash) lives here, the route projects a secret-free view. SNAPSHOT-DURABLE 2026-06-09: ChannelBindingsSnapshot (every user's bindings flattened — each binding self-describes its userId+channel) + bindSnapshotSink/restoreSnapshot + a private persist() on a new single setBinding() write-chokepoint (covers request/confirm/unbind); wireDurableChannelBindings(store) hydrates on boot then binds the write-through sink, wired in server.ts on the SAME deploy-bound DurableSnapshotStore as the persona-lifecycle / operator-incident / device-tokens stores. So a member's VERIFIED channels — and a PENDING verification's salted codeHash — survive a restart instead of forcing every member to re-verify after a deploy. 13 store tests: issued-code-verifies, persisted verify/wrong-attempt/lockout/expiry, per-user isolation, re-request rotation, reset, + 3 durability (a verified binding survives a restart; a pending code still verifies post-restart [codeHash persisted]; per-user isolation across re-hydrate).)
  • (BFF route) routes/channel-bindings.ts: GET /v1/profile/channels, POST /v1/profile/channels/:channel/bind (→ send code or missing-config), POST .../verify, DELETE .../:channel. preHandler:[authProtection, abuseProtection], user-scoped via request.authContext.userId (copy routes/profile.ts:148-174 + device-tokens.ts:71-78); register near registerDeviceTokenRoutes (app.ts:562). (Built + registered. Outcome map: verified→200, wrong-code/expired→400, locked→423, not-pending→409, not-found→404, invalid-channel→400. Delivery is fail-closed — missing-config in prod (no transport wired yet), preview (code exposed) in non-prod for the dev round-trip; never claims a send it didn't perform. The real per-channel transport dispatch is the deferred deploy-bound piece, matching the email-verify precedent. createApp boots with it; no /v1/profile/channels collision.)
  • (BFF route tests) 401, bind→missing-config, bind→pending (injected transport), verify happy/wrong-code, unbind, cross-user isolation. (8 tests: 401, bind→pending+preview-code (hash never leaked), bind→ missing-config in prod (injected isProduction), verify happy/wrong-code, 404 verify-with-no-pending, 400 unknown-channel, unbind + 404, per-user isolation. NOTE: a body-less DELETE must NOT send content-type: application/json (Fastify 400s on empty-body parse); and a user token needs ≥1 scope (empty scopes → 401 at authz.ts:266/366).)
  • (recipient resolution) Resolve verified bindings into MessageRecipient in the reminder produce/deliver path (server.ts:330-344; today reminders are in-app-only, reminders/streak-reminder-producer.ts:79). (Pure verifiedBindingsToRecipient(bindings) maps VERIFIED channels only onto MessageRecipient (email→email, sms→phoneE164, whatsapp→whatsappTo; pending/locked/unbound contribute nothing — never deliver to an unverified address). produceStreakRemindersForUsers gains an optional resolveRecipient?(userId) (default {} = in-app only), wired in server.ts to verifiedBindingsToRecipient(channelBindingsStore.list(userId)) so a verified channel rides alongside in-app delivery. 4 tests (2 helper + 2 producer); tsc/lint clean. The actual SEND still needs the per-channel transport creds (deploy-bound).)
  • (web data layer) apps/oshun/web/src/profile/channel-bindings-client.ts (mirror profile-sync.ts + notifications/push-registration.ts). (Thin typed channelBindingsClient (list/bind/verify/unbind) over the shared api client (/v1/profile/channels…), mirroring data-export-client.ts / consent-client.ts. Typed views are secret-free (no code hash). 4 unit tests asserting paths + bodies. The ChannelBindingsSection UI that replaces DEMO_SERVICES is the remaining layer.)
  • (UI) Replace DEMO_SERVICES + the static section with a real ChannelBindingsSection: live status, address input, send-code → code-entry → verify, unbind; keep/migrate data-profile-service* hooks. DONE — resolved the product-design flag by ADDING (not replacing). Verified against source that DEMO_SERVICES (ProfileSettingsPanel.tsx) is connected ACCOUNTS (Google / Apple Health / Spotify / Notion OAuth integrations), a DIFFERENT feature — replacing it would destroy that surface. So built apps/oshun/web/src/components/profile/ChannelBindingsSection.tsx ('use client', consuming channelBindingsClient) and ADDED it as a new "Notification channels" CollapsibleSection at the END of ProfileSettingsPanel (so no positional section-index shift), with the sibling vi.mock('../profile/ChannelBindingsSection',…) in the panel test. It renders each channel by status — verified → address + Remove; pending → code entry + Verify/Cancel (+ the dev preview code); unbound → address input + Send code — driving channelBindingsClient.{list,bind,verify,unbind} with honest per-row errors (never claims a send/verify it didn't perform). 5 component tests (mount affordances, bind→preview→verify happy path, wrong-code error, unbind, list-error) green; bounded tsc 0; eslint 0. The data-profile-service* connected-accounts hooks are untouched (correct — a different surface). NB: ProfileSettingsPanel.test.tsx carries 8 PRE-EXISTING failures on branch HEAD (verified via git stash; stale positional sections[N]/links.length assertions from the earlier unconditional "Operator access" section/shortcut addition) — UNRELATED to 2.1 and not introduced here. Browser visual pass deferred (RAM-bound).)
  • (UI unit test) Extend ProfileSettingsPanel.test.tsx: pending→verified, verify-error, unbind. (Done — verified 2026-06-09: the channel-binding UI states are covered by the DEDICATED components/profile/ChannelBindingsSection.test.tsx (5 tests, green): bind → dev-preview-code → verify (pending→verified); a wrong code → honest error + NOT marked verified (verify-error); unbind; mount affordances; list-load error. That's the correct home — ProfileSettingsPanel mocks the section, and the panel test carries pre-existing positional-index failures unrelated to this work, so extending it would risk green tests.)
  • (e2e) e2e/profile-channel-bindings.spec.ts (pattern from profile-consent-controls.spec.ts): route the endpoints, drive bind→verify→unbind. (DONE 2026-06-09 — built + GREEN against the real BFF (seedCustomerSession + the dev preview-code path, NO external creds). Two tests, both pass incl. the suite auto-axe scan: (1) email send code → verify → revoke full lifecycle (initial unbound → pending + dev code → verified + address → unbound); (2) a WRONG code → "incorrect" error + stays pending (no fabricated verify). Drives the shipped ChannelBindingsSection in ProfileSettingsPanel. This e2e caught + I fixed FOUR real bugs source-reading missed: (a) the address/code <input>s had no accessible name → axe label critical → added aria-labels; (b) the row re-list()-ed after each mutation, which the PWA service worker serves stale (it caches /v1/* GETs by URL, ignoring cache-control: no-store) → the UI never reflected a just-made bind → switched to optimistic updates from each mutation's server-confirmed response (real data, never fabricated) + added no-store on the route; (c) the verify route returned a 4xx for a wrong code, so the api-client threw and DISCARDED the outcome the UI needs → now returns 200 carrying the outcome (verified/wrong-code/expired/locked/not-pending), 404 only for not-found (route test updated); (d) the BFF CORS allow-methods omitted DELETE/PUT/PATCH (@fastify/cors default GET,HEAD,POST), so EVERY cross-origin unbind/sync/delete the api-client makes was browser-blocked → added the verbs. The spec blocks the SW + uses a unique-per-run customer for deterministic isolation. Verified: BFF tsc 0, web bounded tsc 0, eslint 0, route 8/8, store 10/10, component 5/5, e2e 2/2.)
  • (cross-link + deploy) Update coverage tracker; add OSHUN_TWILIO_*/ _WHATSAPP_*/_SENDGRID_* to .env.example; note fail-closed in §4. _(Cross-link DONE — coverage.md + the journey's E2E-coverage section now list profile-channel-bindings (lifecycle + the 4 bugs). Env vars ALREADY present: .env.example documents OSHUN_TWILIO_ACCOUNT_SID/_AUTH_TOKEN/_FROM (SMS), OSHUN_SENDGRID_API_KEY/OSHUN_SMTP_HOST (email) + OSHUN_WHATSAPP_\*— the general messaging transports the channel-binding code-delivery REUSES once wired; adding channel-binding-specific rows would be inert (7.6 no-inert-rows). The per-channel verification-code SEND is still deploy-bound (route reports missing-configin prod /previewin non-prod — never claims a send) → a dedicated §4 note left for when that transport dispatch is wired.)_ _2026-09-18: open for an agent. The residue is the per-channel verification-code send: wire the route to the messaging transports, prove email against Mailpit (:8025), and keep SMS and WhatsApp failing closed until vendor keys exist. This is the same defect as P1 ofdocs/audits/V1*RESIDUAL_BACKLOG_2026-06-11.md; close them together.*
• Acceptance criteria: A signed-in user enters an address, gets a real code (creds set) or honest "not configured", verifies, sees verified, can unbind; persists across restart; a verified channel populates MessageRecipient; no DEMO_SERVICES remains; user isolation holds.
• Verification: cd libs/oshun/messaging-channels && npx vitest run src/channel-bindings.test.ts · cd apps/oshun/bff && npx vitest run src/routes/channel-bindings-route.test.ts · cd apps/oshun/web && npx vitest run src/components/__tests__/ProfileSettingsPanel.test.tsx · cd apps/oshun/web && npx playwright test e2e/profile-channel-bindings.spec.ts --workers=1
• Effort / risk: L. Risk: constant-time compare + attempt rate-limiting (reuse abuse-protection preHandler); PII (phone/email) rides the snapshot store, not a new sink.

2.2 Email-verify round-trip#

• Status today: signUp sets emailVerified:false unless OSHUN_DEV_AUTO_VERIFY_EMAIL=true/test (auth/customer-auth-store.ts:142-157). No send-verification or verify-token endpoint exists (routes/auth.ts:309-380 has only signup/login/logout/recovery/me/sessions). The only email-ish round-trip (recovery) returns the code in-body in dev and never calls SendGrid. SendGrid transport is real (transports.ts:66-98). Mailpit is in docker/docker-compose.dev.yml:260-271 (SMTP :1025, UI :8025) but the harness doesn't use it.
• The gap: (a) a send-verification endpoint; (b) a verify endpoint flipping emailVerified; (c) transport-shape decision — SendGrid is HTTPS, Mailpit is SMTP, so a real round-trip e2e needs either an SMTP transport pointed at Mailpit or an HTTP-capture fake of SendGrid.
• External dependency: Prod send = SendGrid (OSHUN_SENDGRID_API_KEY, OSHUN_MESSAGING_EMAIL_FROM). E2E round-trip = SMTP transport→Mailpit, or capture the SendGrid HTTP call via the fetchImpl seam (transports.ts:73).
• Granular tasks:
  • (domain/token) Add a verification-token mint+verify with TTL (reuse the recovery-code generator customer-auth-store.ts:804-813), bound to userId+email. (New createEmailVerificationToken — 32-byte hex, 24h TTL via OSHUN_AUTH_EMAIL_VERIFICATION_TTL_MS.)
  • (store) Extend CustomerAuthStateStore with issueEmailVerification/ confirmEmailVerification + a verificationTokensByToken Map (mirror recoveryCodesByCode, :108). (Single-use, TTL-bound; flips emailVerified; re-request invalidates prior. Prod delivery is 'missing-config' — it never claims an 'email' send it didn't perform.)
  • (send) On signUp success, send the verification link via sendEmailViaSendgrid (fail-soft, return verificationDelivery:'email'| 'missing-config'|'preview' like recovery :273). (Done — and wired on BOTH signup AND the explicit POST /v1/auth/verify-email/request via one code path. New auth/verification-email-sender.ts: resolveVerificationEmailSender(env) is fail-closed null unless OSHUN_SENDGRID_API_KEY + OSHUN_MESSAGING_EMAIL_FROM + OSHUN_WEB_BASE_URL are all set; buildVerificationEmailContent builds the {base}/auth/verify-email?token=… link/subject/body; the sender POSTs via sendEmailViaSendgrid bounded by an 8s timeout (a hung provider → not-delivered, never stalls signup). issueEmailVerification is now async (userId, sender?): when the sender accepts the message → delivery 'email' and the token is NEVER exposed (it went by email); a throwing/false/timed-out send is swallowed fail-soft and falls through to the honest 'preview'(non-prod)/'missing-config'(prod) path — 'email' is claimed ONLY on a real provider accept. The signup response now carries a verification block; a send failure never fails the signup. registerAuthRoutes resolves the sender from env (override via options for tests). 9 new tests (4 store-send incl. throwing/false/null fail-soft + token-never-leaked-when-delivered; 5 sender-module incl. fail-closed-null, real SendGrid POST body carries the verify link, non-2xx → false, throw → propagates; + 2 route tests: signup→preview without a sender, signup→email with an injected sender). Updated the 7 existing store/route callers to await. tsc + eslint clean; 20/20 + 18 auth-route + 5 profile-route green.)
  • (routes) POST /v1/auth/verify-email/request (auth-gated) + POST /v1/auth/verify-email/confirm (public, abuse-protected); register on both /auth/* and /v1/auth/*.
  • (decision) SMTP transport — add sendEmailViaSmtp so e2e can point OSHUN_SMTP_HOST/PORT at Mailpit and assert via http://localhost:8025/api/v1/messages; gate selection in buildMessageProviderConfigFromEnv (prefer SMTP when set). OR (alt) write the round-trip e2e against an injected fetchImpl capturing the SendGrid POST and extracting the token; document Mailpit isn't used (HTTPS). (DONE — chose the real SMTP transport (not the fetchImpl-capture alt). New libs/oshun/messaging-channels/src/smtp-email-transport.ts sendEmailViaSmtp is a real, dependency-free RFC 5321 client over node:net/node:tls (greeting→EHLO→optional STARTTLS→optional AUTH PLAIN/LOGIN→MAIL FROM→RCPT TO→DATA→QUIT; multiline replies; RFC 5322 message build; dot-stuffing; header-injection guard; injectable socket factory + TLS upgrade). NEVER fabricates success — any non-2xx reply / dropped connection / reply timeout → {ok:false}. Wired into BOTH the email-verify sender (resolveVerificationEmailSender prefers SMTP via OSHUN_SMTP_HOST, else SendGrid; fail-closed) AND the messaging router (MessageProviderConfig.email.smtp + buildMessageProviderConfigFromEnv gate OSHUN_SMTP_HOST/_PORT/_SECURE/_STARTTLS/_USERNAME/_PASSWORD, precedence over SendGrid; delivery.ts email-ses branch). 15 transport tests against a real in-process node:net SMTP server (no mocking: plain Mailpit path, AUTH PLAIN/LOGIN, dot-stuff round-trip, STARTTLS sequencing, MAIL-FROM reject, connection-refused, reply-timeout, multiline EHLO) + 9 wiring tests (4 sender SMTP branch + 5 router/env). lib tsc 0, BFF tsc 0, eslint 0. .env.example documents the OSHUN_SMTP* block + the Mailpit round-trip note. The Playwright email-verify-roundtrip.spec.ts against a live BFF + Mailpit stays the deferred e2e box below — RAM-bound on this box — but is now de-risked: the transport + both consumers are real and in-process-verified.)_
  • (unit/route tests) token mint/expiry, confirm flips emailVerified, expired/replayed rejected, re-request invalidates prior; /me reflects verified. (9 tests: 6 store + 3 route, via a bare-Fastify registerAuthRoutes with NODE_ENV overridden off auto-verify.)
  • (e2e) e2e/email-verify-roundtrip.spec.ts: signup (auto-verify off) → poll Mailpit or read captured token → open link → assert verified. (DONE 2026-06-09 — GREEN (2/2 incl. auto-axe). Uses the dev preview-token path (read the captured token), NOT Mailpit, so it needs no SMTP creds: a fresh signup (NODE_ENV=development, OSHUN_DEV_AUTO_VERIFY_EMAIL unset → emailVerified false) returns verification.verificationToken; the spec opens /auth/verify-email?token=…, asserts the page confirms it (→ "Email verified"), then opens the SAME link again and asserts an honest "no longer valid" (single-use — the BFF consumes the token), + a missing-token link → "incomplete". BUILT THE MISSING LANDING PAGE (real gap closed): the BFF emails a {base}/auth/verify-email?token=… link but NO page existed there (the link was DEAD — 404/redirect). Added app/auth/verify-email/page.tsx (server: reads the token from searchParams) + components/auth/VerifyEmailConfirm.tsx ('use client': confirms the token on mount against the PUBLIC POST /v1/auth/verify-email/confirm — StrictMode-safe useRef guard so the single-use token isn't double-consumed — and reports verified / already-verified / invalid-expired-consumed / missing-token; never fakes success, uses <Link> per the Next rule). Also fixed the public-route gates so the signed-out recipient isn't bounced to /welcome: added /auth/verify-email to BOTH proxy.ts PUBLIC_PATHS (server 307 gate) and auth-session.ts isPublicShellPath (client gate). 4 island unit tests + auth-session tests green; web bounded tsc 0, eslint 0, stub-scan clean. No dedicated journey doc exists for email-verify, so the spec is standalone account-security coverage.)
  • (cross-link + deploy) Add OSHUN_SENDGRID_*/OSHUN_MESSAGING_EMAIL_* (+ OSHUN_SMTP_* if chosen) to .env.example; note OSHUN_DEV_AUTO_VERIFY_EMAIL must be unset for the test. _(.env.example DONE — OSHUN_SENDGRID_API_KEY + OSHUN_MESSAGING_EMAIL_FROM were already present (2.5); added OSHUN_WEB_BASE_URL (the link origin) + rewrote the email-verify block to document the now-wired fail-soft send + the unset-OSHUN_DEV_AUTO_VERIFY_EMAIL test caveat. The coverage-tracker cross-link rides with the deferred e2e (it needs the live-BFF round-trip to claim coverage); OSHUN_SMTP_\* is the separate SMTP-transport decision below.)_ 2026-09-18: open for an agent. The residue is the coverage-tracker cross-link, which waits for the live-BFF e2e of this section; the stack boots by hand on the Linux server.
• Acceptance criteria: A fresh signup (auto-verify off) creates emailVerified:false, triggers a real email (captured by Mailpit/HTTP fake), and the link flips emailVerified:true (via /v1/auth/me); replayed/expired tokens rejected; no creds → honest missing-config.
• Verification: docker compose -f docker/docker-compose.dev.yml ps | grep mailpit · cd apps/oshun/bff && npx vitest run src/routes/auth.test.ts src/auth/customer-auth-store.test.ts · cd apps/oshun/web && npx playwright test e2e/email-verify-roundtrip.spec.ts --workers=1
• Effort / risk: M (HTTP-capture) / L (SMTP transport). Risk: don't claim a "Mailpit round-trip" while shipping only an HTTPS transport; token single-use + TTL.

2.3 Push / STT / two-way calendar#

2.3(a) Push (FCM/APNs)#

• Status today: Transports fully real (FCM transports.ts:132-165, APNs ES256 HTTP/2 :183-258, routed correctly delivery.ts:132-165). Device-token registration live (routes/device-tokens.ts:65-205, web client notifications/push-registration.ts). Config gate provider-config-env.ts:76-104.
• The gap: (i) APNs needs an HTTP/2 fetchImpl injected (Node fetch is HTTP/1.1) — nothing injects it (V1_DEPLOYMENT_REQUIREMENTS.md:67); (ii) device tokens are in-memory + not read into MessageRecipient.deviceToken; (iii) no e2e (can't drive a real device).
• External dependency: FCM/APNs creds + web VAPID + an HTTP/2 fetch lib.
• Granular tasks:
  • Inject an HTTP/2 fetchImpl (Node http2/undici H2) at the BFF root into the delivery path so push-apns can POST (seam: provider-config-env.ts:154-166, transports.ts:217); warn on boot if APNs configured but fetch is H1. DONE — per-channel injection (the key correctness fix). The H2 adapter createHttp2TransportFetch (http2-transport-fetch.ts, real node:http2, 4 h2c-server tests) was built; now WIRED. CRITICAL: the delivery path uses a SINGLE shared fetchImpl across all 7 channels, so a naive global H2 injection would force SendGrid/Twilio/FCM/Meta/Slack/Discord (all HTTP/1.1 endpoints) through node:http2 too — wrong. So deliverDispatchedMessage gained a SEPARATE optional apnsFetchImpl used ONLY by the push-apns case (apnsFetchImpl ?? fetchImpl); threaded through deliverWithEnvProviders + ReminderCycleInput; the BFF runScheduledReminderCycle (reminders/reminders-route.ts) injects createHttp2TransportFetch() so a scheduled Apple-device reminder actually delivers over H2 instead of failing on H1. Reachable TODAY via POST /v1/reminders/{schedule,run-cycle} (a client schedules channel:'push',pushProvider:'apns',recipient:{deviceToken}). Boot signal: server.ts logs the H2 wiring when APNs is configured; the pure tested guard apnsHttp2BootWarning (provider-config-env.ts) flags the misconfig (APNs creds set, no H2 wired). 7 new tests: 3 in delivery.test.ts (APNs uses apnsFetchImpl NOT the shared fetch; FCM stays on the shared fetch; fallback to shared when unwired) + 4 in provider-config-env.test.ts (boot-warn warn/silent/silent + deliverWithEnvProviders routes APNs through apnsFetchImpl). lib tsc 0, BFF tsc 0, eslint 0, stub-scan clean.
  • Persist device-tokens.ts tokensByUser via the snapshot store. (DONE 2026-06-09 — device-tokens.ts is now snapshot-durable, mirroring the reminder / personalization / conversation stores: a flat DeviceTokenSnapshot (each token carries its userId, so it reconstructs the per-user map), captureSnapshot/restoreSnapshot, a write-through sink, and wireDurableDeviceTokens(store) (hydrate at boot + fire-and-forget save) wired in server.ts beside the other durable stores (conditional on dbHandle.store; in-memory without a DB). register/unregister persist; hydrate uses a non-persisting putToken. 3 route-level tests over a real serialization boundary (inMemorySnapshotStore): a registered token + an unregister BOTH survive a simulated restart (register → flush → reset → re-hydrate → GET), + per-user isolation. BFF tsc 0, eslint 0, stub-scan clean. NB the GET redacts the raw token string (asserted on the returned tokenType/deviceId/platform metadata). Supersedes the earlier "needs Prisma not snapshot" caution — snapshot durability is the established V1 baseline for user-scoped stores (personalization/conversation use it); a Prisma table is a deploy-time scale optimization.) (Deploy-bound — the durable snapshot mechanism fits small operator/admin whole-document stores, not a large per-user token table; same deferral as the other in-memory stores in this checklist. The accessor getTokensForUser exists module-private in device-tokens.ts.)
  • Read device tokens into recipient.deviceToken at reminder time (FCM vs APNs by stored tokenType). (DONE 2026-06-10 — the two prerequisites the DEEPER-BLOCKED note named have since landed (session 6 built the Expo + Web-Push transports; the device-token store became snapshot-durable 06-09), so this resolved cleanly: device-tokens.ts exports resolveDevicePushBinding(userId) — picks the user's most-recently-ACTIVE registered token and maps stored tokenType→transport: fcm/apns→recipient.deviceToken, expo→expoPushToken, web-push→parses the stored JSON.stringify(subscription.toJSON()) into webPushSubscription (malformed → skipped honestly, falls back to the next-newest deliverable token; none → null → reminder stays in-app only). The lib's ReminderRecipientBinding grew pushProvider? (+ the PushRecipientBinding type) forwarded by toReminder, so the planner routes channel:'push' to the token's REAL transport (push-fcm/push-apns/push-expo/push-webpush) instead of the coarse FCM default. All four BFF producers (streak/assignment/session/content-drop) accept resolvePushBinding and merge it with the verified-binding recipient; server.ts's worker produce hook passes resolveDevicePushBinding to all four. One most-recently-active device per reminder — consistent with the one-external-send-per-reminder deliveryId architecture (note 3's fan-out concern is thereby respected, not fought). 9 new tests: 6 resolver (each tokenType, newest-wins, malformed-web-push fallback, all-undeliverable→null, no-tokens→null) + 2 producer + 1 lib forwarding; BFF + lib tsc clean, suites green.)
  • Extend transports.test.ts for the H2 path (authorization bearer JWT, apns-topic, apns-push-type) with an injected H2 double; assert apns-id/FCM-name. (Duplicate coverage — http2-transport-fetch.test.ts already drives the H2 adapter (incl. apns-id passthrough) against a real h2c server, and transports.test.ts:146-259 already tests sendPushViaApns exhaustively (ES256 JWT, prod+sandbox, apns-id, content-available, rejection) with an injected fetch. The NEW per-channel routing (APNs→H2 vs others→H1) is now covered end-to-end in delivery.test.ts. Re-testing the union in transports.test.ts adds nothing.) Not a task (2026-09-18): its own note records that the coverage already exists in http2-transport-fetch.test.ts, transports.test.ts and delivery.test.ts.
  • Add e2e/push-registration.spec.ts (web push reg against a mocked /v1/device-tokens). _(DONE 2026-06-10 — and fixed the deeper product gap behind it: registerForPushNotifications had ZERO callers (the web app never offered push enablement). NotificationPreferences grew a "This device" registration row under the master push toggle (data-profile-push-device, status checking/unsupported/unavailable/permission-denied/unregistered/ registered/error — honest fail-closed copy for each): register → browser permission + SW subscription → POST /v1/device-tokens (same-origin, the stringified subscription JSON the BFF's resolveDevicePushBinding parses back); unregister → browser unsubscribe + DELETE. VAPID public key from NEXT_PUBLIC_VAPID_PUBLIC_KEY (documented in .env.example beside OSHUN_VAPID_\*) with a **OSHUN_WEB_PUSH_VAPID_PUBLIC_KEY** runtime override seam (host page / e2e harness — no rebuild). The 4-test spec stubs ONLY the browser Push API boundary (fake SW registration + granted permission — headless chromium has no push service) and asserts the REAL wire shape both ways (endpoint + p256dh/auth keys round-trip), the 503-BFF→error honesty path, and the no-VAPID→unavailablefail-closed state. 4/4 green at 1 worker; the adjacentprofile-notification-preferences.spec.ts re-run green (5/5, no regression); web tsc clean; coverage.md row updated.)_
  • Add FCM/APNs/VAPID vars to .env.example; document the H2 requirement. _FCM (OSHUN_FCM_ACCESS_TOKEN/_PROJECT_ID) + APNs (the four OSHUN_APNS_*+ optional\_SANDBOX) are documented; the APNs comment now accurately states APNs requires HTTP/2 and the BFF wires it automatically (no env). CORRECTION 2026-06-09: the original note ("VAPID has no BFF var") was written in session 1 and is now STALE — session 6 built the Web-Push (RFC 8291/8292) + Expo transports, and buildMessageProviderConfigFromEnv (provider-config-env.ts:136,143-145) DOES read OSHUN_VAPID_PUBLIC_KEY/ \_PRIVATE_KEY/\_SUBJECT(all three required →config.webPush) and OSHUN_EXPO_ACCESS_TOKEN(optional push-security) as live BFF vars. These were wired but never documented (the env-doc was the gap, not the rule). NOW DOCUMENTED — added the Push-Expo + Push-Web-Push (VAPID) blocks to .env.example beside the FCM/APNs block, with the optional-Expo / all-three-VAPID / recipient-gated semantics. (The web client still gets the VAPID *public* key via injected config + the mobile app via EXPO_PUBLIC_VAPID_PUBLIC_KEY; the BFF needs the full keypair to sign.)_
• Acceptance criteria: With creds + H2 fetch, push-apns POSTs a signed request to api.push.apple.com/3/device/<token> returning apns-id; tokens persist + resolve into recipients; web-push reg e2e passes; without creds → missing-config.

2.3(b) STT (speech-to-text) — FIXES TWO FORBIDDEN STUBS#

• Status today: Browser Web Speech path is real but not CI-drivable (assistant/AssistantPanel.tsx:10). Telegram voice transcription is two fabricated-transcript stubs: apps/oshun/bff/src/telegram/webhook.ts:67-71 returns `voice transcript from ${fileId}`; apps/oshun/telegram-bot/src/index.ts:119-123 returns `Telegram voice note ${fileId}`. No server-side STT provider exists.
• The gap: A real VoiceProvider.transcribeTelegramVoice (libs/oshun/messaging-channels/src/telegram/bot.ts:70-72) replacing the stubs, fail-closed when unconfigured.
• External dependency: An STT provider (Whisper/Deepgram/Google Speech) + key.
• Granular tasks:
  • Add libs/oshun/messaging-channels/src/stt-provider.ts implementing VoiceProvider against the chosen API (injectable fetchImpl), fail-closed (stt_not_configured) without a key — never a fabricated transcript. (Placed at src/telegram/stt-provider.ts beside bot.ts; real 3-step path: Telegram getFile → download → OpenAI-compatible /audio/transcriptions.)
  • Replace the two stub bodies (webhook.ts:67-71, telegram-bot/src/index.ts:119-123) to call the provider, or surface "voice transcription unavailable" when unconfigured. (Both call resolveSttVoiceProvider; bot handler now replies honestly on throw/empty — also updated the e2e that pinned the old stub.)
  • Add the STT key to buildMessageProviderConfigFromEnv (all-vars-present gate). (Gate implemented in resolveSttVoiceProvider instead — STT is INBOUND transcription, not an outbound delivery channel, so it must not enter the delivery config / configured-channels list. Same fail-closed all-vars-present semantics, tested.)
  • stt-provider.test.ts: real transcript extraction, error path, and missing-config (assert it NEVER returns a fake transcript — stub-elimination check).
  • Add the STT key to .env.example.
• Acceptance criteria: A Telegram voice note is transcribed by a real provider when configured; honestly reports unavailable otherwise; both placeholder strings gone; tests prove a wrong/absent key never yields a fake transcript.

2.3(c) Two-way calendar#

• Status today: A complete two-way framework exists + is tested + fails loud (libs/shared/inbound-integrations/src/calendar.ts: CalendarTransport with upsert/delete :146-152, exportEvent throws when no transport :402-414, providers google/apple/outlook :13). Mobile composes it (apps/oshun/mobile/src/calendar/mobileCalendarSync.ts). One-way .ics export exists for Nyx. No provider transport implements CalendarTransport, and the framework is not wired into any BFF route.
• The gap: A provider transport + a BFF route/store; the domain is done.
• External dependency: Google Calendar API / CalDAV / Microsoft Graph creds + OAuth.
• Granular tasks:
  • Implement CalendarTransport for ≥1 provider (Google or CalDAV): fetchEvents, upsertEvent, deleteEvent (injectable fetchImpl). (Done — libs/shared/inbound-integrations/src/calendar-google-transport.ts createGoogleCalendarTransport({resolveAccessToken, fetchImpl?}) implements all three. The framework's CalendarDateTime/CalendarAttendee/ CalendarEventStatus are modeled on the Google Calendar API v3 event shape, so mapGoogleEventToProviderEvent is near-1:1 (summary→title, id→externalId, start/end/attendees/recurrence pass through; unknown status→fail-safe 'confirmed'; '(untitled)' fallback). fetchEvents = real windowed GET (timeMin/timeMax/singleEvents), paginated via nextPageToken (no silent cap), incremental sets showDeleted + updatedMin (so deletes propagate); upsertEvent = POST(create)/PUT(update-by-externalId); deleteEvent = DELETE (410 Gone = idempotent success). Fail-LOUD: an empty/throwing resolveAccessToken rejects BEFORE any network call (never proceeds tokenless, never fabricates events); a non-ok HTTP throws. The OAuth2 token exchange/refresh behind resolveAccessToken + the BFF route/store (routes/calendar-sync.ts) + e2e are the deploy-bound/remaining pieces. 13 spec tests (mapping timed/all-day/cancelled/attendees, pagination, incremental showDeleted, fail-loud token + HTTP, POST-vs-PUT, 410-success). tsc + eslint + stub-scan clean. PLUS a framework-integration spec (calendar-google-transport-framework.spec.ts, 2 tests): the real createCalendarConnectorFramework reconciliation engine + MemoryCalendarSyncStore driving the REAL Google transport over a fake fetch — proves a live-shaped Google event JSON flows through the transport and is accepted by the framework's import (creates:1, summary→title, watermark persisted) and export (PUT update; the framework requires a non-empty externalId — it updates a linked event, not a blind create). This composition test is the "does the new provider actually work with the orchestration" proof. PLUS the OAuth2 auth side — createGoogleOAuthAccessTokenResolver exchanges a stored refresh token for an access token at Google's token endpoint (grant_type=refresh_token), composing directly into the transport's resolveAccessToken. Fail-LOUD: an absent refresh token (never exchanges), a non-2xx exchange, or a response with no access_token all throw — never an empty/fabricated token. 4 more tests (17 total in the transport spec). So Google calendar is now usable end-to-end given a deploy-bound client-id/secret + refresh token; only the interactive OAuth consent flow + the BFF routes/calendar-sync.ts + store remain.)
  • routes/calendar-sync.ts: OAuth start/callback, POST /v1/calendar/sync (import), POST /v1/calendar/export (writeback), GET /v1/calendar/connectors; bind a CalendarSyncStore (Memory dev / durable prod); auth-gate per user. (Built the env-config/admin model (mirroring the LMS connector surface, 3.3) rather than a per-user one — consistent with the existing tenant-connector pattern: calendar/calendar-runtime-env.ts createCalendarRuntimeFromEnv reads OSHUN_CALENDAR_CONNECTORS (JSON), validates each (malformed JSON + invalid descriptors retained with issues, never silently skipped), and builds the framework over the REAL Google transport + OAuth resolver (client creds from env; per-connector refresh token via the descriptor's refreshTokenRef → env) + MemoryCalendarSyncStore. google-only — the only transport implemented, so a non-google connector is surfaced as unsupported_provider, not dropped. routes/calendar-sync.ts: GET /v1/admin/calendar/connectors (secret-free summary + invalid w/issues, no refreshTokenRef leaked) + POST /v1/admin/calendar/connectors/:id/import (runs the framework's real reconciliation → the import run; 404 unknown, 409 CalendarConnectorError), admin-scoped, registered in app.ts (createApp boots, /v1/admin/calendar/connectors→401 unauth). The /export writeback route is now done too — POST /v1/admin/calendar/connectors/:id/export runs framework.exportEvent (the connector identity is server-authoritative so a client can't spoof the tenant/connector/provider; 400 without an externalId — the framework updates a linked event; 404 unknown). So the two-way list/import/export trio is complete. 11 tests (runtime valid/unsupported/malformed + route auth/list/import/export/404/400). tsc + eslint + stub clean. The interactive OAuth flow's CODE is now built too — buildGoogleCalendarAuthorizationUrl (consent URL with access_type=offline + prompt=consent so a refresh token is actually returned) + exchangeGoogleCalendarAuthorizationCode (grant_type=authorization_code → access + refresh tokens, fail-loud on empty-code/non-2xx/no-token), 5 more tests (22 in the transport spec). The per-user interactive connect flow is now built too — calendar/calendar-oauth-connection-store.ts (single-use TTL-bound CSRF state tokens bound to the user + per-user connections; the refresh token is server-side, NEVER projected to the client) + routes/calendar-connect.ts: POST /v1/calendar/connect (auth; 503 unconfigured; else the consent URL), GET /v1/calendar/callback (public, CSRF-state-validated → code exchange → store the refresh token as a per-user connection → 302 to the web app; 502 if Google returns no refresh token — never persists a non-renewable one), GET .../connections (secret-free), DELETE .../:id. Registered in app.ts (createApp boots). 9 tests (store single-use/TTL/isolation + full connect→callback round-trip + forged-state 400 + no-refresh-token 502 + disconnect); OSHUN_GOOGLE_CALENDAR_REDIRECT_URI documented. The per-user connection store is now SNAPSHOT-DURABLE 2026-06-09 — CalendarOAuthConnectionsSnapshot (established connections ONLY; the ephemeral single-use/TTL CSRF state tokens are deliberately NOT persisted) + bindSnapshotSink/restoreSnapshot + persist() on saveConnection/removeConnection; wireDurableCalendarOAuthConnections(store) wired in server.ts on the SAME deploy-bound DurableSnapshotStore as the persona-lifecycle / channel-bindings / SSO stores. So a member's calendar links (incl. refresh token, needed for a post-restart refresh) survive a restart instead of forcing a reconnect. Gained a dedicated store unit test (6 store-logic + 3 durability incl. one asserting the CSRF state does NOT span a restart). Remaining: only the lib-level MemoryCalendarSyncStore sync-state durability (deploy-bound).) 2026-09-18: open for an agent. The residue the note names is one thing: make the library's MemoryCalendarSyncStore sync state durable (Postgres, per the repository's persistence policy), with a restart test.
  • Map domain items (Tara rituals, Arete reminders, Nyx events, mobileCalendarSync.ts:13-21) → CalendarEvent. (DONE 2026-06-10 — BFF calendar/domain-calendar-events.ts maps the user's REAL schedule (not the mobile fixtures): tara_ritual ← the durable upcoming-session store; metis_study_session ← the durable due-assignment store; nyx_event ← the user's enabled Nyx event reminders (honours an explicit channels selection — only 'external-calendar'-eligible reminders export); arete_reminder ← the REAL at-risk daily streak (same isStreakAtRisk signal as the reminder producer, block ending at the UTC day deadline). Block lengths are documented product defaults (30/15/60 min — calendar blocks need an end the upstream records don't carry). domainCalendarItemToCalendarEvent mirrors the mobile buildCalendarExportEvent conventions exactly (stable oshun-<kind>-<slug> externalIds + the raw.oshun metadata envelope) so either surface's exports reconcile identically. PLUS the consumer that makes it live: routes/calendar-events.ts — GET /v1/calendar/events (the caller's real exportable schedule, user-isolated) and POST /v1/calendar/export (writes it to the caller's OWN connected Google calendar via a per-user transport built on their stored refresh token; 503 unconfigured / 409 no connection / per-item honest failure outcomes), registered in app.ts. 14 new tests (7 mapper + 7 route incl. per-user transport identity + cross-user isolation + fail-soft domain outage); tsc + stub-scan clean.)
  • Transport-double tests: import normalization (normalizeCalendarEvent:657), upsert/delete, fail-loud when transport missing (:402-414). (DONE 2026-06-10 — import normalization + upsert/delete were ALREADY covered by calendar.spec.ts ("imports provider events, normalizes them, and stores watermarks"; "exports and deletes events through the provider transport"; ownership/calendar-mismatch/import-only rejects). The genuinely missing case was fail-loud-on-missing-transport — added: a fetch-only transport (no upsertEvent/deleteEvent) → exportEvent rejects calendar_export_unavailable and deleteExportedEvent rejects calendar_delete_unavailable (never a silent no-op write-back). Lib spec 13/13 green.)
  • e2e/calendar-two-way.spec.ts against a mocked transport: connect → import → export → assert upsert called. (DONE 2026-06-10 — built as the BFF full-chain flow test routes/calendar-two-way-flow.test.ts (the web e2e variant is not yet drivable: the web app has NO calendar-connect UI — see the new task below — and a browser e2e cannot intercept the BFF's server-side Google token exchange, so the API-level chain with the transport as the ONLY double is the faithful version of this box). One app instance, all three real route modules: POST /v1/calendar/connect → consent URL → GET /v1/calendar/callback (exchange double) → the refresh token is stored on the caller's connection; POST /v1/admin/calendar/connectors/:id/import → run applied with creates:1 from the double's provider event; POST /v1/calendar/export → the caller's REAL seeded session upserts through THEIR connection — upserts[0].event.externalId === 'oshun-tara_ritual-session-sunrise-sit' asserted. Full calendar suite 44/44 green, tsc clean.)
  • (web UI — gap spotted 2026-06-10) The per-user calendar connect surface does not exist in the web app: nothing calls POST /v1/calendar/connect, and the BFF callback redirects to /account/integrations?calendar=connected which has NO page (404). Build the integrations surface (connect/disconnect Google calendar via the real per-user routes, list connections, trigger POST /v1/calendar/export, handle the ?calendar=connected return) + a Playwright spec; then point the fixture-driven ConsumerShellCalendarSyncPanel (/activity) at GET /v1/calendar/events instead of its hardcoded items. (DONE 2026-06-10 (first half) — new profile "Calendar sync" section (CalendarSyncSection.tsx + calendar-connections-client.ts), deep-linked ?path=calendar (added to WEB_PROFILE_ROUTE_PATHS + aliases): connect → real POST /v1/calendar/connect → browser sent to the consent URL; the BFF callback redirect retargeted from the 404 /account/integrations to /profile?path=calendar&calendar=connected (connect-route test updated); connections listed secret-free with disconnect; the REAL exportable schedule previewed from GET /v1/calendar/events; "Export to my calendar" posts the browser time zone and renders per-item outcomes (failures listed with the provider error, never fabricated); honest unavailable copy on 503. 4-test Playwright spec profile-calendar-sync.spec.ts (Google consent mocked at ITS boundary via an accounts.google.com route intercept → bounce back connected; service worker blocked — it serves stale /v1 GETs). ALSO repaired 8 PRE-EXISTING ProfileSettingsPanel.test failures (stale index-pinned section lookups broken by the unconditional Operator-access section a prior session added at the top): replaced every sections[N] with a title-based sectionByTitle helper + the shortcut-count assert with an explicit id-list — 62/62 green (was 54/62). REMAINING (second half, tracked below): repoint the fixture-driven ConsumerShellCalendarSyncPanel on /activity at the real GET /v1/calendar/events.)
  • (web UI — /activity panel) Point the fixture-driven ConsumerShellCalendarSyncPanel (/activity, hardcoded REVIEW_PROVIDER_EVENTS + fixed 2026-05-07 clock + shell-core fixture items) at the real per-user data: items from GET /v1/calendar/events, connection state from GET /v1/calendar/connections, and the sync/export action through POST /v1/calendar/export; update calendar-sync.spec.ts (it currently pins the fixture item ids). (DONE 2026-06-10 — the panel's ENTIRE fixture layer is gone: items ← GET /v1/calendar/events, providers ← GET /v1/calendar/connections (Google live; Apple/Outlook honestly disabled — "Not available yet", never claimed connected), and "Sync now" performs a REAL pull through the NEW GET /v1/calendar/provider-events (per-user transport fetchEvents over the caller's connection, now-anchored 14-day window, 502 fail-loud on provider errors — 3 new route tests, 10/10 file green). The shell-core reconciliation engine now runs over real provider state (live-calendar-sync.ts mappers incl. raw.oshun round-trip metadata parsing); fixed clock → live clock; honest loading/load-error/sync-error/unconnected states with a deep link to Profile → Calendar sync; header copy de-puffed. Panel unit tests REWRITTEN against the live layer (5 tests: real items only, honest provider states, live pull → inbound reschedule + missing-source conflict through the REAL engine, failed-pull honesty, failed-load honesty); calendar-sync.spec.ts rewritten (3 e2e: live sync review, unconnected guidance, mobile) — all green; ActivityDashboard suite 83/83; web tsc clean.)
  • Add OAuth vars to .env.example; document in a new §. (Done — a "Two-way calendar sync (Google)" block documents OSHUN_CALENDAR_CONNECTORS (the per-tenant descriptor JSON, mirroring OSHUN_LMS_CONNECTORS), OSHUN_GOOGLE_CALENDAR_CLIENT_ID/_SECRET, and the refresh-token-by-ref convention, with the google-only + fail-loud + deferred-OAuth-consent caveats.)
• Acceptance criteria: With a configured provider, connect → imported events appear → a local change writes back; unconfigured export fails loud; the .ics Nyx path still works.
• Effort / risk (2.3 overall): push M, STT M, calendar L. Risks: APNs H2 (silent failure on H1); STT stub-elimination is mandatory; calendar OAuth complexity.

2.4 Reminder producers (due-assignment / upcoming-session / content-drop) (ALL THREE TWINS BUILT 2026-06-09 — matrix complete)#

2026-06-09 — user chose to add the model + build the producers. DUE-ASSIGNMENT BUILT (10 unit + 1 Redis-integration tests, commit f2c0dbd710) via a BFF-side durable projection rather than an LMS-native bulk query + admin cron route (cleaner — no change to the LMS lib): reminders/due-assignment-store.ts (snapshot-durable, listDueAssignmentsBetween), reminders/assignment-event-consumer.ts (the real WRITER — projects lms.assignment.{upserted,cleared} events the LMS publishes), reminders/assignment-reminder-producer.ts (feeds the lib's produceAssignmentReminders). Wired into the BFF reminder worker's produce hook with the same verified-binding recipients as the streak producer; the stable assignment:courseId:assignmentId:userId sessionId dedups. The due date is an ABSOLUTE instant → no per-user timezone model needed (the original blocker).

2026-06-09 — UPCOMING-SESSION TWIN NOW BUILT (commit bd309dc417), the symmetric follow-up via the identical worker-hook + event-consumer shape: 10 unit

• 1 Redis-integration tests (full reminders suite 44 passing; tsc + eslint clean; adversarial stub-scan zero hits). reminders/upcoming-session-store.ts (snapshot-durable BFF projection, listUpcomingSessionsBetween, absolute startsAtUnixSeconds), reminders/session-event-consumer.ts (the real WRITER — projects session.{upserted,cancelled} on the shared Redis bus, keyPrefix oshun:session), reminders/session-reminder-producer.ts (feeds the lib's produceV3SessionReminders). Wired into the BFF reminder worker's produce hook (return [...streaks, ...nyx, ...assignments, ...sessions]) with the same verified-binding recipients; the session-native sessionId dedups; durable hydrate at boot + shutdown teardown. The granular tasks below describe the alternative Nyx/Metis-native-store + admin-cron-route shape; the worker-hook + event-consumer shape was built instead — so they stay [ ] (different mechanism).

2026-06-09 — CONTENT-DROP TWIN NOW BUILT (commit 286132837b; user: "build the content-drop producer too"). The 4th lib mapper produceContentDropReminders now has an automatic worker source via the identical worker-hook + event-consumer shape: 10 unit + 1 Redis-integration tests (full reminders suite 54 passing; tsc + eslint clean; adversarial stub-scan zero hits). reminders/content-drop-store.ts (snapshot-durable BFF projection, listContentDropsBetween, absolute publishAtUnixSeconds), reminders/content-drop-event-consumer.ts (the real WRITER — projects content.drop.{scheduled,cancelled} on the shared Redis bus, keyPrefix oshun:content), reminders/content-drop-reminder-producer.ts (feeds the lib's produceContentDropReminders → "