From 872f1f2e558d24b99e1fd78bc95fe9c535507c2c Mon Sep 17 00:00:00 2001 From: TJ Baker <1617679+zaridan@users.noreply.github.com> Date: Fri, 10 Jul 2026 12:19:13 -0700 Subject: [PATCH] =?UTF-8?q?docs:=20refresh=20STATUS.md=20=E2=80=94=20threa?= =?UTF-8?q?ding=20core=20(parse/tokens/decision)=20shipped?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The living status page still described the pre-code foundation. Update it to reflect the merged mail-engine threading core (parser, reply tokens, message-id extractor, threading decision) and the next steps (store, send). Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01TqG66PPZreBrj17VbAqe3b --- STATUS.md | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/STATUS.md b/STATUS.md index 12dbda7..f718e0b 100644 --- a/STATUS.md +++ b/STATUS.md @@ -1,26 +1,35 @@ # Helpthread — Status -**Current state:** pre-code foundation is laid — charter, specs, provider interfaces, fixtures, and a full CI/quality skeleton are in place; the mail engine itself has not been started. +**Current state:** the mail engine's threading core is built and merged — an inbound reply can be parsed, its signed reply token verified, and routed to the correct conversation end-to-end. Persistence (store) and outbound (send) are next. All work lands through a guarded pipeline: every PR runs typecheck, lint, tests-with-coverage, secret scanning, and CodeQL, plus AI review (CodeRabbit) and — for security- and threading-critical code — an independent Codex pass. ## Now -**Phase 1 — Core engine, dogfooded.** Laying the guarded foundation the engine lands into: every PR runs typecheck, lint, tests-with-coverage, a secret scan, CodeQL, and OpenSSF Scorecard before anything merges. No engine code has shipped yet. +**Phase 1 — Core engine, dogfooded.** The threading decision is complete; building outward toward a runnable, dogfoodable slice. ## Done +**Foundation** - Founding charter ([CHARTER.md](CHARTER.md)) — mission, principles, licensing, architecture, roadmap. -- Behavioral specs: the conversation API contract (`specs/api/conversations-v1.md`), mail threading (`specs/mail/threading.md`). -- Platform provider interfaces (`src/providers/`) — queue, scheduler, blob storage, inbound email — the seam that keeps the engine Vercel-first, not Vercel-only. +- Behavioral specs: conversation API contract (`specs/api/conversations-v1.md`), mail threading (`specs/mail/threading.md`). +- Platform provider interfaces (`src/providers/`) — queue, scheduler, blob storage, inbound email — Vercel-first, not Vercel-only. - Black-box acceptance fixtures (`fixtures/mail/`). -- This CI/quality foundation: TypeScript (strict, NodeNext) + Biome (lint/format) + Vitest (tests + v8 coverage), CI workflow (quality + secret scan), CodeQL, and OpenSSF Scorecard. +- CI/quality foundation: TypeScript (strict, NodeNext) + Biome + Vitest (v8 coverage); CI (quality + secret scan), CodeQL, OpenSSF Scorecard; branch protection requires all checks green. + +**Mail engine — threading core** +- **Inbound parser** (`src/mail/parse.ts`) — raw RFC 5322/MIME → a normalized `ParsedEmail` (built on postal-mime). Surfaces the threading-critical headers; captures HTML verbatim. +- **Signed reply tokens** (`src/mail/reply-token.ts`) — HMAC-SHA256 tokens minted into outbound Message-IDs and verified on reply, with key rotation. The cryptographic basis for trustworthy threading. +- **RFC 5322 message-id extractor** (`src/mail/message-id.ts`) — comment/quoted-string-aware tokenization, shared by the parser and the threading decision. +- **Threading decision** (`src/mail/thread.ts`) — the 5-rule algorithm: a verified token routes a reply to its conversation; no valid token starts a new one; subject is never used. ## Next -Engine increments, in dependency order: parse inbound mail → thread conversations → store → send (with signed reply tokens in outbound Message-IDs). The six-operation conversation API and an agent inbox UI follow per the charter's API-first rule. +- **Store** — persist conversations and threads (local Postgres via a portable, thin SQL layer) so the decision's `{conversationId, threadId}` lands somewhere real; handle tokens pointing at closed/deleted conversations. +- **Send** — outbound replies that mint the reply tokens the whole system depends on. +- Then: the six-operation conversation API and an agent inbox UI (API-first, per the charter). ## Not yet / deferred -- Live Vercel + Supabase deployment — deferred until the first deployable milestone; provider adapters are stubbed behind interfaces, not built yet. +- Live Vercel + Supabase deployment — deferred to the first deployable milestone; provider adapters are interfaces, not yet built. - Agent inbox UI. - Marketplace (paid modules, license keys, module registry).