company_dns

V4 initial development release roadmap

Status: Tracking doc (2026-09-30) — a checklist, not a design doc. Each major area below has its own detailed plan doc where one exists; this doc sequences them toward one goal and adds the cross-cutting items none of them individually own. Update checkboxes here as work lands; keep the design detail in the linked docs, not duplicated here. Owner: michael.hay@mediumroast.io Scope: everything standing between where V4 is today (a working, security-hardened, dynamically-logged server with no deployment pipeline, no client examples, and large untested surfaces) and a real initial development release running in K8s — not necessarily replacing V3 in production yet (§0 makes that an explicit decision, not an assumption).

Decided (2026-09-30), from a user perspective, not the endpoint-by- endpoint framing this doc’s first draft defaulted to, then corrected twice against the real V3 OpenAPI spec (see §3’s full rewrite — the first two drafts of §3 were both wrong, kept below only as visible history of how the scope actually got nailed down): full V3.0 parity ships in the initial dev/staging release for everything US-scoped (NA SIC full dataset, NA EDGAR including the catalog-backed ciks/detail/summary endpoints, Wikipedia/merged v2), plus one new V4-only capability (semantic search for SIC, with chunking for descriptions longer than the embedding model’s input limit — not yet built). Non-US SIC systems (EU, International/ISIC, Japan — UK excluded indefinitely) are real, tracked, but explicitly NOT part of this release — they gate a later, separate V4.0.0 milestone that replaces V3 in production, staged as source data becomes available (Japan next, others “over time”). UX is explicitly decoupled onto its own track (§1); client SDKs ship Python and TypeScript only for v1, Go and Rust deferred (§7); updating the top-level repo docs is its own tracked item (§8).

0. First: decide what “initial development release” actually means

Not decided anywhere yet — needed before the rest of this doc’s sequencing makes sense.

1. UX — explicitly a separate track, not this release’s critical path

Decided directly: “New UX – we’ll work that separately.” UX work stays on company-dns-ux.md’s own timeline and does not gate this roadmap’s release. Kept as its own section only so the decision to decouple it is recorded, not because there’s a checklist here to work through.

2. Document rate limiting in the API docs

Owning doc: v4-security-hardening.md §5 step 4 — explicitly flagged and skipped as “optional polish” when rate limiting shipped. Time to close it.

Done 2026-10-07 (v4-release-to-staging.md step 1): every operation except /health documents 429 and 401; the spec’s info.description explains the User-Agent ladder, the rate limits and the experimental SQL endpoint, and links to the README’s Security and Profiles sections (the README links back to /docs).

Owning doc: v4-deployment.md §3.2 (data- bundling options, still undecided) and §6 (real production data size, still unknown). Ground truth for this section: V3’s real, live OpenAPI spec, pulled directly from https://company-dns.mediumroast.io/openapi.json (45 paths total) — not memory, not assumption. This section went through two wrong readings before landing here; corrected directly against that spec rather than guessed a third time.

What the real V3 spec actually contains, and what it means for v1:

Update 2026-10-07: the 15 per-system EU NACE, ISIC and Japan endpoints and the two /v2/ aliases are built (the count of non-US endpoints in V3’s code is 17 including UK, not 22), and they match V3’s real responses; UK stays excluded.

3a. Non-US SIC systems — real, tracked, gates V4.0.0, not this release

Decided directly: “They are in scope minus the UK for now. At this time only the US is available with Japan coming next and others over time. The final location for download will be an initially deferred decision… This is the gating factor for V4.0.0 cutover from V3.0.0. However we can run dev or staging environments until these are ready.”

This is a named, real milestone — not a vague “someday” — just one this specific roadmap doesn’t complete. Tracked here so it isn’t lost, detailed design deferred to its own doc once work on it actually starts (matching this project’s own pattern: a plan doc gets written once there’s real substance to plan, not preemptively).

4. Test coverage: audit, then a roadmap, not just “add tests”

Real, measured current state (grepped directly, not estimated): crates/cache, crates/edgar, crates/sic, crates/firmographics have zero #[test]/#[tokio::test] functions. crates/wikipedia has 5 (client.rs, promoted from the wikipedia spike). crates/server has 21 — but every one of them is in the rate-limiting-derived modules (user_agent.rs, trusted_origin.rs, secret_ua.rs); the actual HTTP route handlers (sic_description/edgar_ciks/etc.), rate_limit.rs’s own tiering logic, and logging.rs have no direct unit tests at all — every verification of them this session was live, manual curl testing, which is real evidence but not a repeatable, CI-enforced safety net.

5. Deployment scaffolding and binary slimming

Owning doc: v4-deployment.md — fully designed, nothing in it spiked or implemented yet. This is the single largest remaining body of work in this roadmap.

6. Testing: automated and human

7. Sample client SDKs: Python and TypeScript for v1, Go and Rust deferred

Decided directly: “New client SDKs (Python and Typescript to start, others deferred).” Go and Rust move out of this release’s scope entirely — not designed, not stubbed, revisit once Python/ TypeScript prove out the approach. Net new work either way, nothing started. Directly serves company-dns-ux.md §1’s framing of this project as “a reference implementation of real, useful things you can build on top of this data” — sample SDKs are exactly that, made concrete.

8. Additional items not in the original list, added here

Raised from this session’s own accumulated knowledge of what’s actually outstanding, not from the original 7-item list:

9. Suggested sequencing

Not a strict waterfall — several tracks can run in parallel — but real dependencies exist worth calling out:

  1. §0 first — nothing else in this doc has a stable target without it.
  2. §3 is now decided (this session, after two corrections) — its remaining checkboxes (the two /v2/ alias URLs, the semantic-search chunking feature, sourcing the full US SIC dataset, the data- bundling decision) can proceed immediately, and narrow scope for §4 (what needs tests), §5 (what needs bundling/deploying), §6 (what gets tested), and §7 (what the SDKs demonstrate).
  3. §3a is explicitly parked, not sequenced into this roadmap at all — it proceeds on its own, separate timeline (data availability, not this roadmap’s pace) and doesn’t block, or get blocked by, anything else here. Revisit this roadmap’s own sequencing only once §3a’s gate gets closer to clearing.
  4. §4 and §5 in parallel — test coverage doesn’t block deployment scaffolding or vice versa, but both feed §6.
  5. §2 is small and independent — can land anytime, no dependencies.
  6. §1 (UX) is fully decoupled — explicitly not a dependency for any other section anymore; §7’s SDKs proceed against §3’s now- decided endpoint scope without waiting on it.
  7. §6 depends on §4 and §5 both being real, not just designed — the human UAT pass specifically needs a real deployed company-dns-dev (§5) to walk through.
  8. §8’s items are cross-cutting — CORS and the secrets audit belong before release; the top-level repo docs update pairs naturally with whichever milestone §0’s exit criteria treats as “release,” so it can land last without blocking earlier work; monitoring/alerting can trail slightly behind without blocking an initial dev-tier release.
This site is open source. Improve this page.