{"slug":"architecture/CONNECTOR_RUNTIME_PROOF","title":"Connector Runtime Proof — GitHub → Spine → Projection","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/CONNECTOR_RUNTIME_PROOF.mdx","bytes":4498,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Tier:** B (Build proof). Canon: `SPINE_MODEL.md`, `PROJECTION_MODEL.md`, `AGENTS.md`.\n> **Date:** June 12, 2026 | **Status:** transformation PROVEN (offline, tested); runtime GATED on P1 deploy.\n\nThe strategic question: **can external reality enter the Spine and produce useful projections?**\nGitHub is the chosen first proof (rich entities, no OAuth dance to validate the mapping, central to IW).\n\n```text\nGitHub → Nango Connector → Connector Registry → SPINE (entity resolution) → D1 → Projection → Workbench/Twin\n```\n\n---\n\n## 1. Proven now (offline, unit-tested) ✅\n\n**External reality → canonical Spine entities.** This is the architectural heart — that GitHub\nrecords become _canonical_ Spine types, never raw GitHub blobs.\n\n| GitHub       | Canonical type | Why                                                                     |\n| ------------ | -------------- | ----------------------------------------------------------------------- |\n| repo         | `repository`   | canonical (PRODUCT_ENGINEERING)                                         |\n| issue        | `task`         | engineering work item; blocked-work flagged from labels                 |\n| pull request | `pull_request` | canonical; merged/draft/open status                                     |\n| commit       | `activity`     | matches canonical `push → activity` alias                               |\n| contributor  | `contact`      | a contributor is a Person — entity resolution unifies them across tools |\n\n- Mapper: `packages/connectors/src/project-management/github-spine-mapping.ts` (pure functions).\n- Tests: `…/github-spine-mapping.test.ts` — 7 tests, incl. PR-disguised-as-issue detection and the\n  invariant that **every** emitted entity uses a canonical type with `source`/`source_id` provenance.\n- Sync adapter `syncGitHub` (`packages/connectors/src/sync-adapters.ts`) now routes all GitHub data\n  through the mapper (was: repo→`project`, issue→`ticket` only).\n- Spine routing: `getDomainForType` (`services/pipeline/src/spine/index.ts`) now sends engineering\n  types (`repository`, `pull_request`, …) to the **build** partition so the Engineering projection\n  co-locates instead of scattering into `cross_data`.\n- **Engineering projection read path:** `GET /api/v1/workspace/engineering`\n  (`services/gateway/src/workspace-spine.ts` → `getEngineeringProjection`) reads `build_data`\n  D1-direct and shapes Active Repositories · Open PRs · Recent Commits · Blocked Work. Tested\n  (`engineering-projection.test.ts`, 3 tests) incl. the no-raw-leak invariant; degrades to an empty\n  projection before any data is synced.\n\n## 2. Gated on P1 (needs deployed infra + Nango connection) ⛔\n\nThese require the Cloudflare deploy + a live GitHub connection (see `DEPLOYMENT_RUNBOOK.md`):\n\n- **Connector layer:** register the GitHub connection via Nango; persist sync cursor/state; accept\n  webhooks (`services/webhook-ingress` → `services/connector-sync`).\n- **Spine write:** sync → normalizer → pipeline → D1 `build_data` partition (tenant-scoped).\n- **Projection:** an Engineering projection (Open PRs · Recent Commits · Active Repos · Blocked Work)\n  read D1-direct via the gateway (`PROJECTION_MODEL.md`), derived from Spine entities only.\n- **Twin:** answer \"what changed in engineering this week?\" from the Spine — no live GitHub query.\n\n## 3. Success criteria (the proof is complete when…)\n\n- [x] GitHub payloads map to canonical entities (no raw records downstream) — **tested**\n- [x] Engineering types co-locate in one Spine partition — **routing in place**\n- [x] Engineering projection read path (D1-direct, shaped, no-leak) — **built + tested**\n- [ ] A live GitHub connection syncs into D1 (cursor tracked) — _needs P1_\n- [ ] The projection renders live data in the Engineering workbench (frontend hook) — _needs P1 data_\n- [ ] The Twin answers an engineering question from the Spine — _needs P1_\n\n## 4. Why this generalizes\n\nOnce GitHub → Spine → Projection runs end-to-end, the pattern repeats for HubSpot, Notion, Google\nWorkspace, Slack, Linear: each is a new mapper (`map<Tool>` → canonical types) plus the same\nruntime. The runtime is shared; only the per-tool mapping changes — and that mapping is now a\nproven, unit-tested pattern.\n\n---\n\n_Transformation proven offline; runtime is one deploy away. When P1 lands, wire a live GitHub\nconnection and check off §3._\n"}