From 05f5b3cae5129986999c414eb591ddadb55c9da4 Mon Sep 17 00:00:00 2001 From: Kames Date: Fri, 7 Aug 2026 07:22:36 -0700 Subject: [PATCH 1/3] checkoint: migration docs --- .planning/candidate-assignment/README.md | 13 + .planning/candidate-assignment/assignment.md | 191 +++++++++++++++ .../candidate-assignment/evaluation-guide.md | 87 +++++++ .../candidate-assignment/widget-brief.md | 90 +++++++ .planning/claude-migration/00-overview.md | 145 ++++++++++++ .../claude-migration/01-track-ingestion.md | 64 +++++ .../02-track-projections-db.md | 52 ++++ .../03-track-parsing-classification.md | 78 ++++++ .../claude-migration/04-track-enrichment.md | 77 ++++++ .../05-track-seed-pipeline.md | 84 +++++++ .../06-track-api-explorer-qa.md | 63 +++++ .planning/claude-migration/README.md | 25 ++ .../codex-migration/00-executive-overview.md | 118 +++++++++ .../codex-migration/01-target-architecture.md | 211 +++++++++++++++++ .../codex-migration/02-impact-inventory.md | 212 +++++++++++++++++ .../codex-migration/03-engineering-tracks.md | 223 ++++++++++++++++++ .../codex-migration/04-cutover-runbook.md | 146 ++++++++++++ .../05-decisions-risks-and-tests.md | 143 +++++++++++ .../06-scheme-resolution-matrix.md | 87 +++++++ .planning/codex-migration/index.md | 54 +++++ 20 files changed, 2163 insertions(+) create mode 100644 .planning/candidate-assignment/README.md create mode 100644 .planning/candidate-assignment/assignment.md create mode 100644 .planning/candidate-assignment/evaluation-guide.md create mode 100644 .planning/candidate-assignment/widget-brief.md create mode 100644 .planning/claude-migration/00-overview.md create mode 100644 .planning/claude-migration/01-track-ingestion.md create mode 100644 .planning/claude-migration/02-track-projections-db.md create mode 100644 .planning/claude-migration/03-track-parsing-classification.md create mode 100644 .planning/claude-migration/04-track-enrichment.md create mode 100644 .planning/claude-migration/05-track-seed-pipeline.md create mode 100644 .planning/claude-migration/06-track-api-explorer-qa.md create mode 100644 .planning/claude-migration/README.md create mode 100644 .planning/codex-migration/00-executive-overview.md create mode 100644 .planning/codex-migration/01-target-architecture.md create mode 100644 .planning/codex-migration/02-impact-inventory.md create mode 100644 .planning/codex-migration/03-engineering-tracks.md create mode 100644 .planning/codex-migration/04-cutover-runbook.md create mode 100644 .planning/codex-migration/05-decisions-risks-and-tests.md create mode 100644 .planning/codex-migration/06-scheme-resolution-matrix.md create mode 100644 .planning/codex-migration/index.md diff --git a/.planning/candidate-assignment/README.md b/.planning/candidate-assignment/README.md new file mode 100644 index 0000000..7fc32db --- /dev/null +++ b/.planning/candidate-assignment/README.md @@ -0,0 +1,13 @@ +# Candidate Assignment + +Take-home assignment for CTO / Lead Engineer candidates, anchored in +`intuition-core` and the widget prototype. + +| File | Audience | Purpose | +| --- | --- | --- | +| [`assignment.md`](./assignment.md) | Candidate | The take-home: orient on Core, argue the developer-community vs. enterprise fork, frame the widget product | +| [`widget-brief.md`](./widget-brief.md) | Candidate | Self-contained widget context (the prototype repo is private) | +| [`evaluation-guide.md`](./evaluation-guide.md) | **Internal only** | Rubric, calibration notes, red flags, process | +| `assets/market-widget.png` | Candidate | Market-widget screenshot — **re-export from card-playground; not yet present** | + +Send candidates: `assignment.md` + `widget-brief.md` + the asset. Nothing else. diff --git a/.planning/candidate-assignment/assignment.md b/.planning/candidate-assignment/assignment.md new file mode 100644 index 0000000..0332978 --- /dev/null +++ b/.planning/candidate-assignment/assignment.md @@ -0,0 +1,191 @@ +# Intuition Core — Technical Leadership Take-Home + +*For CTO and Lead Engineer candidates. Please read the whole document before starting.* + +--- + +## Why this assignment looks the way it does + +We are not testing whether you can write code under a timer. We are testing the +thing the job actually is: **reasoning about a real system with real trade-offs +and committing to a direction you can defend.** Everything below is anchored in +our actual open-source codebase — [`intuition-core`](https://github.com/0xIntuition/intuition-core) — +and in a real product decision we are facing right now. There is no hidden +"correct" answer we are matching you against. We grade the quality of the +reasoning, the specificity of the plan, and your willingness to say what you +would *not* do. + +**Time expectation:** 4–6 focused hours, spread over up to one week. Do not +polish; a sharp memo beats a beautiful deck. Using AI tools (Claude, Cursor, +etc.) is fine and expected — but you must be able to defend every claim live, +and we will push on them in the debrief. + +**Deliverables (all three parts):** + +1. A short **state-of-the-system note** (½–1 page) +2. A **direction memo** answering the strategic fork (2–3 pages) +3. A **widget product brief** (1–2 pages) +4. *Optional:* one small code artifact (cap it at 2 hours — see Part 4) + +Submit as markdown or PDF, plus a link to any code. We will then do a 60–90 +minute live debrief where we challenge your positions. + +--- + +## Part 0 — Context: what Intuition Core is + +Intuition Core is the open-sourced Intuition backend — "the open backend, in a +box." One `docker compose up` gives you a self-hosted shard of the Intuition +knowledge graph: + +- **Chain ingestion** (Rust): `crates/rindexer-ingestion` indexes the + MultiVault contract into a TimescaleDB event store; `crates/projections` + turns events into read models and knowledge-graph tables. +- **Atom intelligence pipeline** (TypeScript/Bun): `services/workers` runs the + parse → classify → enrich pipeline; `services/atom-services` exposes it over + HTTP. Classification has **17 built-in URL plugins** (GitHub, Spotify, + Wikipedia, X, …) and enrichment has **36 provider plugins** — the keyless set + (OpenGraph, JSON-LD, Wikipedia, Wikidata) works with zero API keys. +- **Query API** (`services/api`): the read/write HTTP API over the KG database. +- **Explorer** (`apps/explorer`): a built-in dashboard — service health, worker + pipeline throughput, live atoms/triples/events. +- **Deterministic IDs**: the atom ID you derive locally is the exact ID the + protocol registers onchain — publishing is a state change, not a migration. + +The minimal stack requires **zero paid accounts**, including chain indexing +(the Intuition testnet RPC is public and keyless). Start with `README.md`, +`docs/architecture.md`, and `docs/data-model.md`. + +--- + +## Part 1 — Get oriented (~1 hour) + +Clone the repo, stand the stack up (`README.md` quick start), and watch data +flow through the explorer. Skim the docs and the code at whatever depth you +need. + +**Deliverable — state-of-the-system note (½–1 page):** + +- What is this system genuinely good at, as built? +- What are the two or three things that most worry you (architecture, ops, + DX, security — your call)? +- One thing you would change in the first month, and why that one. + +If you can't get the stack running, say so and what you tried — the failure +mode itself is data, and the rest of the assignment does not depend on it. + +--- + +## Part 2 — The fork in the road (the core question) + +Intuition Core can only be optimized for one master over the next 12 months. +These are the two real paths in front of us: + +### Path A — The developer community path + +Optimize Core for **an expansive, organic developer community**: easy to run, +lightweight, hackathon-friendly. Every decision favors time-to-first-atom on a +laptop: fewer moving parts, fewer required services, better defaults, better +docs, a plugin API that a stranger can ship against in an afternoon. Growth +comes from many small integrations and builders who pick Intuition because it +was the easiest knowledge graph to start with. + +### Path B — The enterprise path + +Optimize Core for **a handful of large, sophisticated operators** and paid +APIs/services. Think partners like Spotify or Polymarket who want to augment +their existing catalog or database with Intuition's knowledge graph and +serve an enhanced experience to their customers. This path means things like an +advanced Kafka-based messaging backbone, many more enrichments and plugins, +multi-tenant concerns, SLAs, and a generally more intricate architecture that +few people run but which carries serious traffic and revenue. + +### What we want from you — the direction memo (2–3 pages): + +1. **Pick a path.** (A sequenced argument — "A now, B at trigger X" — is + allowed, but a trigger is a measurable condition, not a vibe.) +2. **Ground it in the code.** Name the concrete changes to *this repo* your + path implies in the first 90 days — which services, crates, or packages + change, what gets added, and crucially **what gets deleted or explicitly + not built**. Generic roadmaps score zero; `services/atom-services` and + `crates/projections` are real code you can point at. +3. **The road not taken.** What does your choice cost us? Steelman the other + path in one honest paragraph. +4. **How you'd know.** 3–5 metrics that would tell you within two quarters + whether the bet is working, and what reading would make you reverse. +5. **Team shape.** Roughly what team (size and skills) executes this, and + what you would do personally in month one. + +--- + +## Part 3 — The widget: a product on top of Core + +We have prototyped an **embeddable Intuition widget** — a way to carry the +knowledge graph onto any third-party website in one paste. The full brief with +the embed API, widget variants, and architecture of the prototype is in +[`widget-brief.md`](./widget-brief.md). Read it; it is short and self-contained. + +The headline: a site drops in + +```html +
+ +``` + +and gets a live, style-isolated card — identity, a live Trust/TVL sparkline, +supporter avatars, and a **Trust CTA** — stamped *Powered by Intuition*, backed +by a purpose-built read-only widget API over the same KG database Core ships. + +**The question:** How would you use this widget to grow Intuition — and **which +partner would you approach first and build a prototype for?** (Polymarket and +Spotify are examples of the archetype, not constraints.) + +**Deliverable — widget product brief (1–2 pages):** + +1. **The growth thesis.** What loop does the widget create? Who sees it, what + do they do, and how does that compound for Intuition? Be explicit about + whether the widget serves your Part 2 path, the other one, or bridges them. +2. **The partner.** Name one first partner, what *their* users get on day one, + and why the partner says yes. What data does the graph need to contain for + the prototype to be genuinely useful rather than a demo? +3. **Prototype to production.** The prototype is a scaffold. List, in order, + what it takes to make this real: hardening the widget API (it is currently + no-auth, permissive-CORS, CDN-cached by design — what survives, what + doesn't?), latency and freshness, abuse/embedding risks, versioning a + script third parties have pasted and will never update, and how it lands in + or beside `intuition-core`. +4. **The first 30 days.** A concrete sequence from "today" to "widget live on + the partner's site," including the non-engineering steps. + +--- + +## Part 4 — Optional code artifact (max 2 hours) + +If — and only if — it strengthens your argument, ship one small thing. +Examples: a new enrichment or classification plugin (see +`docs/writing-an-enrichment-plugin.md`), a widget-serving endpoint sketch on +`services/api`, a Compose profile that supports your Part 2 direction, or a +mock widget for your chosen partner. A rough PR with a clear description beats +a polished one with none. Skipping this part carries no penalty. + +--- + +## The debrief + +60–90 minutes, live. You walk us through the direction memo (10 min), then we +argue: we will take the opposite side of your Part 2 pick, poke at your partner +choice, and go deep on one technical claim from your Part 3 hardening list. +We are evaluating how you reason under pushback — changing your mind for a good +reason scores *up*, not down. + +## Ground rules + +- The repo is public; your submission stays private to the hiring team. +- We are hiring, not sourcing free strategy — we cap your time, and we will + not use your specific partner plan unless you join us and build it. +- Questions during the week are welcome and free: ask them the way you would + as CTO — good questions are signal too. diff --git a/.planning/candidate-assignment/evaluation-guide.md b/.planning/candidate-assignment/evaluation-guide.md new file mode 100644 index 0000000..dfeaf9b --- /dev/null +++ b/.planning/candidate-assignment/evaluation-guide.md @@ -0,0 +1,87 @@ +# Internal — Evaluation Guide + +*Not shared with candidates. How to run and score the take-home in +`assignment.md`.* + +## First principles behind the design + +- **Test judgment, not labor.** A CTO's scarce skill is committing to a + direction with incomplete information and being right about what *not* to + build. Hence one contested fork, hard time caps, and an optional code part. +- **The fork is genuinely contested on purpose.** We internally lean Path A + (developer community). We do NOT grade on matching that. A candidate who + argues Path B rigorously and names what it costs beats one who guesses A + and hand-waves. Calibrate interviewers on this before scoring. +- **The widget is the hidden synthesis test.** The strongest answers notice + the widget *bridges* the fork: it is Path-A-style distribution (one-paste, + organic, "Powered by Intuition" loop) aimed at Path-B-style partners + (Spotify/Polymarket archetypes). Candidates who treat Part 3 as disconnected + from Part 2 are missing the systems view. +- **Anchor everything in the repo** so we measure comprehension of *our* + system, not generic startup talk. "Generic roadmaps score zero" is stated in + the assignment; enforce it. +- **Respect the candidate.** 4–6 hours, no free consulting (we commit not to + use their partner plan), AI tools allowed but defended live. This protects + our brand with exactly the senior people we want. + +## Scoring + +Score each dimension 1–4 (1 = miss, 2 = adequate, 3 = strong, 4 = exceptional). +Written submission first, then adjust after the debrief. + +| Dimension | What a 4 looks like | Weight (CTO) | Weight (Lead Eng) | +| --- | --- | --- | --- | +| **Codebase comprehension** | Part 1 worries are specific and real (e.g. the Rust/TS pipeline seam, projections lag, worker retry semantics, docs vs. behavior drift) — not "add tests" | ×1 | ×2 | +| **Strategic reasoning** | Part 2 pick follows from evidence; the reversal condition is measurable; the steelman of the other path is honest enough to sting | ×2 | ×1 | +| **Prioritization / subtraction** | Names things to delete or refuse to build, in this repo, and accepts the cost | ×2 | ×1.5 | +| **Product sense (widget)** | Partner choice has a believable "why they say yes"; identifies the data-coverage prerequisite (a widget over an empty graph is a demo, not a product); sees the brand/growth loop | ×1.5 | ×1 | +| **Technical depth (widget hardening)** | Engages the real constraints: no-auth + `*` CORS survives because data is public, but needs rate limiting/abuse controls; CDN cache vs. freshness of trust numbers; the forever-pasted `v1.js` versioning problem; where widget-api lives relative to Core | ×1.5 | ×2 | +| **Communication** | Memos are decision documents: position up front, evidence, costs, next steps | ×1.5 | ×1 | +| **Debrief under pushback** | Defends with evidence, concedes with reasons, never bluffs about the code | ×1.5 | ×1.5 | + +Rough bar: weighted average ≥ 3.0 → advance; 2.5–3.0 → discuss; < 2.5 → pass. + +## Strong signals + +- Ran the stack and reports something they *saw* (explorer throughput, a + worker failure mode), not just something they read. +- Sequenced answer to the fork with a real trigger ("A until a partner signs a + paid LOI; the Kafka backbone is a two-quarter build we start only then"). +- Notices deterministic IDs are a strategic asset for both paths (local dev + parity for A; integration guarantees for B) — that's reading the README + closely and thinking. +- In Part 3, addresses partner-side incentives (what Spotify's PM gets) and + the cold-start data problem, not just our side. +- Asks us a sharp question mid-week. + +## Red flags + +- Roadmap that never names a file, service, or crate. +- Chooses both paths ("we can do A and B") without sequencing or cost. +- Widget hardening list that "adds auth" reflexively without noticing the + public-data/no-auth design is intentional — shows they didn't read the brief. +- Over-delivers massively (20 pages, big PR) — ignores constraints; that's a + signal about how they'll treat team constraints too. +- In debrief, defends every point regardless of evidence, or folds instantly. + +## CTO vs Lead Engineer + +Same assignment, different weighting (table above) and different debrief focus: +for **CTO**, spend the debrief on Part 2 and the partner strategy; for **Lead +Engineer**, spend it on Part 1 worries and the Part 3 hardening list, and treat +Part 4 (code artifact) as a soft expectation rather than optional. + +## Process / next steps + +1. **Pilot internally**: have one of us do the assignment cold, timed, to + validate the 4–6h cap and find ambiguities. Fix, then freeze the text. +2. **Re-export the widget screenshot** from the card-playground embed pages + into `assets/market-widget.png` (the brief references it). +3. **Package for sending**: `assignment.md` + `widget-brief.md` + the asset. + The evaluation guide never leaves this repo. +4. Send with a named contact for questions and a scheduled debrief slot at + send time (forces the time-box to be real). +5. Two scorers per submission, score independently before comparing; debrief + run by one scorer + one observer. +6. After 2–3 candidates, revisit the rubric weights against what actually + differentiated them. diff --git a/.planning/candidate-assignment/widget-brief.md b/.planning/candidate-assignment/widget-brief.md new file mode 100644 index 0000000..4d27459 --- /dev/null +++ b/.planning/candidate-assignment/widget-brief.md @@ -0,0 +1,90 @@ +# Widget Brief — the embeddable Intuition card + +*Self-contained context for Part 3 of the take-home. The prototype lives in a +private repo; everything you need to reason about it is below.* + +## What it is + +An embeddable widget that carries the Intuition Knowledge Graph onto any +website — an **item**, a **stack** (curated collection), a **claim** +(subject → predicate → object), or its live **market** data — in one paste. + +### The marquee variant: the Market Widget + +The fullest expression of a card. For any graph item (an app like Next.js, a +token like Ether, a person like Ada Lovelace) it renders: + +- **Identity** — image, classification badge (`SOFTWAREAPPLICATION`, `TOKEN`, + `PERSON`, …), title, subtitle +- **A live Trust/TVL sparkline** with a % change chip +- **Total Trust** (e.g. `322.5 Ŧ`) and a row of **supporter avatars** (`+137`) +- **A "TRUST" CTA button** — the on-ramp from a third-party page into an + Intuition transaction +- A **"Powered by Intuition"** footer mark — the brand loop +- Dark and light themes + +> A screenshot export of the three market cards (Next.js / Ether / Ada +> Lovelace, dark + light) belongs in `assets/market-widget.png` — re-export +> from the design playground if missing. + +## Two delivery mechanisms (same rendering core) + +**1. iframe + loader (default — zero conflict):** + +```html +
+ +``` + +The loader finds every `.intuition-widget` element, injects a sandboxed +`