Skip to content

docs: refresh STATUS.md (threading core shipped) #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zaridan merged 1 commit into from
Jul 10, 2026
Merged

docs: refresh STATUS.md (threading core shipped) #10

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 16 additions & 7 deletions STATUS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

@coderabbitai coderabbitai Bot Jul 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Avoid claiming end-to-end routing before Store ships.

src/mail/thread.ts currently produces an append decision with {conversationId, threadId}; it does not persist or route the reply, and line 26 explicitly makes persistence future work. Please describe this as identifying the target conversation/thread rather than routing it end-to-end.

Suggested wording 
-**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.
+**Current state:** the mail engine's threading core is built and merged — an inbound reply can be parsed, its signed reply token verified, and its target conversation/thread identified. Persistence (store) and outbound (send) are next.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
**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.
**Current state:** the mail engine's threading core is built and merged — an inbound reply can be parsed, its signed reply token verified, and its target conversation/thread identified. 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.
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@STATUS.md` at line 3, Update the “Current state” wording to avoid claiming
end-to-end routing: describe the mail engine as parsing inbound replies,
verifying signed tokens, and identifying the target conversation and thread.
Remove or revise the routing claim and retain that persistence and outbound
sending are still future work.


## 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).

Expand Down
Loading