Sprinter Platform Package Migration

# Sprinter Platform Package Migration

## Executive Summary

As of 2026-04-03, the `@sprinterai` npm surface is materially more adoption-ready than it was in the 2026-04-01 unification spec:

- `@sprinterai/core`, `@sprinterai/runtime`, `@sprinterai/supabase`, and `@sprinterai/typespec` are all published on npm at `0.7.1`
- npm install works in a clean temp project
- ESM imports resolve successfully for the package root and subpath exports
- earlier package gaps called out in the unification spec are now at least partially closed:
  - runtime now has `context`, `capture`, `document`, `feed`, `notification`, `search`, `entity`, `skill`
  - core now has `schema`, `render`, `stores/api-key-store`, `stores/audit-store`
  - supabase now has `auth`, `tenant`, `api-key-store`, `audit-store`, `comment-store`, `view-store`, `response-store`, `workflow-run-store`, and more

The main conclusion:

- **The biggest structural wins are now in the npm packages**
- **The biggest visible UI wins are mostly in the Sprinter registry, not in npm**
- **Amble should start consuming `@sprinterai` for headless logic first, then selectively pull registry UI**
- **Amble should not try to replace the entire view/block system in one shot**

## Current Snapshot

### Amble today

Measured in this repo on 2026-04-03:

- `features/` contains **188** directories
- the repo contains **1550** `ts` / `tsx` files under `features/`
- `package.json` currently consumes **zero** `@sprinterai/*` packages

Large local generic-platform areas that overlap strongly with Sprinter packages:

| Area | Current local size |
| --- | ---: |
| `features/tenant` | 4.2k LOC |
| `features/entities` | 42.3k LOC |
| `features/agents` | 14.3k LOC |
| `features/tools` | 11.3k LOC |
| `features/workflows` | 8.2k LOC |
| `features/responses` | 7.5k LOC |
| `features/views` | 20.6k LOC |
| `features/blocks` | 26.2k LOC |
| `features/chat` | 10.1k LOC |
| `features/navigation` | 5.9k LOC |

### Sprinter Platform today

Published npm packages:

| Package | Version | Role |
| --- | --- | --- |
| `@sprinterai/core` | `0.7.1` | types, builders, store interfaces, schema/render contracts |
| `@sprinterai/runtime` | `0.7.1` | tools, workflows, chat handler, context, capture, search, notifications |
| `@sprinterai/supabase` | `0.7.1` | auth adapter, tenant helpers, Supabase store implementations |
| `@sprinterai/typespec` | `0.7.1` | entity type markdown DSL parse/compile/generate |

Also available in the sibling `sprinter-platform` repo:

- a registry-backed UI library under `registry/new-york/blocks/*`
- Storybook stories for generic renderers and record cards
- package docs under `site/content/docs/packages/*`

Important distinction:

- **npm gives us headless platform logic**
- **registry gives us reusable UI code**

## Comparison: Where Sprinter Platform Is Ahead

| Area | Who is ahead | Why |
| --- | --- | --- |
| Package boundaries | Sprinter Platform | Clean split between `core`, `runtime`, `supabase`, `typespec`; Amble still keeps most platform logic inline inside feature modules |
| Auth + tenant primitives | Sprinter Platform | `@sprinterai/supabase` centralizes guards, claims, tenant context, URL building, and role helpers into a stable package surface |
| TypeSpec / entity definition pipeline | Sprinter Platform | `@sprinterai/typespec` is already extracted, documented, published, and importable; Amble still carries local parse/compile/generate copies |
| Schema utilities | Sprinter Platform | `@sprinterai/core/schema` now covers completeness checks, entity validation, and repair utilities |
| Workflow engine shape | Sprinter Platform | `@sprinterai/runtime/workflow` is smaller, more modular, and easier to test than Amble’s still-inline orchestration surface |
| Tool system shape | Sprinter Platform | `ToolRegistry`, `resolveTools`, `entity-tools-factory`, and AI bridge are packageized and subpath-exported |
| Context + capture runtime | Sprinter Platform | These were gaps on 2026-04-01; they now exist in `@sprinterai/runtime` and are importable |
| Search primitives | Sprinter Platform | `runtime/search` gives a cleaner package seam for hybrid/cosine-style search work than today’s scattered Amble search logic |
| Generic rendering contracts | Sprinter Platform | `@sprinterai/core/render` is a much clearer boundary than Amble’s broader `views` + `blocks` + component sprawl |
| Generic UI blocks | Sprinter Platform | Registry blocks are more isolated, story-backed, and easier to transplant selectively than Amble’s generic surfaces |

## Comparison: Where Amble Is Still Ahead

| Area | Who is ahead | Why |
| --- | --- | --- |
| Production breadth | Amble | More end-to-end product features are already wired together in the app |
| View/block engine breadth | Amble | The current block and view system is broader and more integrated than the registry alone |
| Admin surfaces | Amble | More operational/admin pages are already working in the product |
| Product-specific workflows | Amble | `features/custom/*` and related orchestration are richer than anything in the generic packages |
| Multi-surface polish across the live app | Amble | The app has more real usage-driven fixes and business-specific behavior, even when the underlying abstractions are more tangled |

This matters because the migration should:

- **pull in Sprinter Platform where it gives us cleaner platform primitives**
- **keep Amble as the source of truth for product-specific behavior**
- **avoid a wholesale rewrite of `features/views` and `features/blocks`**

## Best Candidates To Pull In First

### Highest ROI from npm right now

1. `@sprinterai/typespec`
2. `@sprinterai/core/schema`
3. `@sprinterai/core/extraction`
4. `@sprinterai/supabase` auth + tenant helpers
5. `@sprinterai/runtime/context`
6. `@sprinterai/runtime/capture`
7. `@sprinterai/runtime/tool`
8. `@sprinterai/runtime/workflow`
9. `@sprinterai/runtime/search`

These are the best first targets because they are:

- relatively headless
- already published
- strongly aligned with Amble’s north star
- likely to delete real code instead of just wrapping it

### Highest visible UI wins from Sprinter registry

1. `render-registry/field-renderers`
2. `widget-data-table`
3. `entity-bulk-toolbar`
4. `entity-column-picker`
5. `widget-kanban`
6. `app-shell`
7. `document-manager`
8. `document-viewer`
9. `notification-center`
10. `audit-log-viewer`

These are strong UI candidates because they are:

- smaller than the equivalent Amble generic UI surfaces
- story-backed or registry-isolated
- easier to transplant incrementally
- visually cleaner than several of Amble’s generic components

## Important Constraint

The best visible UI pieces are **not** published as `@sprinterai/*` npm packages today.

That means the migration has two tracks:

- **NPM track:** consume `@sprinterai/*` headless packages
- **Registry track:** pull UI blocks from the Sprinter registry or sibling repo as owned source

Do not force the registry UI through npm just because the runtime packages are on npm. That would add friction without adding value.

## Recommended Migration Strategy

### Rule 1: Add a local compatibility layer first

Create a thin package-consumption seam before swapping call sites:

```text
lib/sprinter-platform/core.ts
lib/sprinter-platform/runtime.ts
lib/sprinter-platform/supabase.ts
lib/sprinter-platform/typespec.ts
```

Initial rule:

- application code imports from `lib/sprinter-platform/*`
- only the compatibility layer imports directly from `@sprinterai/*`

This keeps the blast radius down and lets us swap package internals without touching every feature module at once.

### Rule 2: Pin exact versions for the first adoption wave

Use exact versions first:

```json
{
  "@sprinterai/core": "0.7.1",
  "@sprinterai/runtime": "0.7.1",
  "@sprinterai/supabase": "0.7.1",
  "@sprinterai/typespec": "0.7.1"
}
```

Only move to caret ranges after the first migration batch is stable in Amble.

### Rule 3: Pull pure functions before stores

Adoption order should be:

1. pure utilities
2. type builders / schemas
3. auth + tenant wrappers
4. runtime orchestration
5. store factories
6. selective UI transplant

This is the fastest path to code deletion with the lowest regression risk.

## Batch Plan

## Batch 1 — Low-Risk Package Wins

**Goal:** Start consuming published packages where the swap is mostly mechanical and low-risk.

### Scope

- replace local entity type DSL with `@sprinterai/typespec`
- replace local extraction dependency helpers with `@sprinterai/core/extraction`
- replace local schema validation/repair helpers with `@sprinterai/core/schema`
- replace any local field-display formatting helpers that overlap with `@sprinterai/core/utils`
- add the compatibility layer under `lib/sprinter-platform/*`

### Best Amble targets

- `features/entities/type-spec/*`
- `features/entities/extraction/dep-sort.ts`
- `features/entities/extraction/cascade.ts`
- `features/entities/extraction/consensus.ts`
- `features/responses/validation.ts`
- any duplicated display-format helper logic in generic entity rendering

### Why this batch first

- it gives immediate code deletion
- it validates package import reliability inside Amble
- it does not require changing the live UX architecture
- it reduces future drift between Amble and Sprinter Platform

### Expected impact

- **user-visible improvement:** low to medium
- **platform cleanup:** high
- **estimated removable code:** **3k to 5k LOC**

## Batch 2 — Auth, Tenant, and Supabase Spine

**Goal:** Stop hand-maintaining core auth/tenant plumbing in Amble where the package already has a stronger seam.

### Scope

- wrap Amble auth through `@sprinterai/supabase`
- wrap tenant context and URL helpers through `@sprinterai/supabase`
- adopt package client factories where they match current usage
- begin using `createSupabaseStores` in a sidecar adapter for a few services

### Best Amble targets

- `features/tenant/auth.ts`
- `features/tenant/context.ts`
- `features/tenant/constants.ts`
- `features/tenant/roles.ts`
- `lib/supabase/*` where client factory overlap exists

### Why this batch second

- it consolidates some of the most sensitive platform code
- it removes duplicated RBAC / tenant-resolution logic
- it sets up the store migration batches cleanly

### Expected impact

- **user-visible improvement:** low
- **platform cleanup:** very high
- **estimated removable code:** **4k to 7k LOC**

## Batch 3 — Runtime Core: Tools, Workflows, Context, Capture

**Goal:** Replace the homegrown headless runtime layer with the packaged runtime where it is already better-factored.

### Scope

- adopt `@sprinterai/runtime/tool`
- adopt `@sprinterai/runtime/workflow`
- adopt `@sprinterai/runtime/context`
- adopt `@sprinterai/runtime/capture`
- adopt `@sprinterai/runtime/search` where it fits current entity/document search plans
- migrate response-scoring helpers where package logic is already cleaner

### Best Amble targets

- `features/tools/*`
- `features/workflows/*`
- `features/context/*`
- `features/capture/server/*`
- `features/responses/server/*`

### Why this batch matters

This is the first batch that meaningfully reduces Amble’s platform sprawl around the north-star loop:

- fields
- DAG execution
- tools
- context
- response promotion

### Expected impact

- **user-visible improvement:** medium
- **platform cleanup:** very high
- **estimated removable code:** **8k to 12k LOC**

## Batch 4 — Selective Registry UI Pull

**Goal:** Get the most obvious design and generic-UI improvements without rewriting Amble’s whole rendering system.

### Scope

- transplant Sprinter registry field renderers
- transplant data-table toolbar / bulk toolbar / column picker patterns
- transplant widget-kanban patterns where they improve generic list surfaces
- transplant app-shell patterns where they simplify the shell
- transplant document manager / viewer, notification center, and audit log viewer if the local surfaces are weaker

### Best Amble targets

- `features/entities/components/data-table/*`
- `features/entities/components/entity-card/*`
- `features/entities/components/kanban/*`
- `components/app-shell/*`
- `features/navigation/components/*`
- targeted document / notification / audit components

### Why this is not Batch 1

- these pieces are **not npm packages**
- they require design and integration judgment
- the local app already has deeper wiring in some of these surfaces

### Expected impact

- **user-visible improvement:** very high
- **platform cleanup:** medium
- **estimated removable code:** **5k to 8k LOC**

## Batch 5 — Store-Backed Service Convergence

**Goal:** Move more server-side feature implementations onto package stores after the compatibility layer and runtime spine are proven.

### Scope

- entities server access paths
- agents server access paths
- chat server storage helpers
- document store access
- skills, memory, comments, notifications, api keys, audit, webhooks
- feed resolver/store-backed ranking if package fit is confirmed

### Best Amble targets

- `features/entities/server/*`
- `features/agents/server/*`
- `features/chat/server/*`
- `features/documents/server/*`
- `features/skills/server/*`
- `features/memory/server/*`
- `features/comments/server/*`
- `features/notifications/*`
- `features/api-keys/*`
- `features/webhooks/*`
- `features/feed/server/*`

### Expected impact

- **user-visible improvement:** medium
- **platform cleanup:** high
- **estimated removable code:** **6k to 10k LOC**

## Realistic Code Reduction

### Conservative estimate

| Migration area | Candidate overlapping local code | Realistic deletable code |
| --- | ---: | ---: |
| Headless runtime + logic | ~29.7k LOC | 10k to 14k LOC |
| Store / auth / tenant / service layer | ~26.8k LOC | 9k to 14k LOC |
| Generic UI shell + list/detail surfaces | ~18.5k LOC | 5k to 8k LOC |
| **Total realistic reduction** | **~75k LOC touched by overlap** | **24k to 36k LOC removable** |

### Upper bound

If Amble eventually converges much more aggressively on Sprinter’s generic UI and store model, the upper bound is likely closer to:

- **35k to 45k LOC removable**

That is **not** the recommended first-wave target.

## Recommended Order If We Want The Biggest Improvement First

### Highest strategic improvement first

1. Batch 1
2. Batch 2
3. Batch 3
4. Batch 4
5. Batch 5

This is the right order if the goal is:

- less platform drift
- lower maintenance cost
- fewer custom seams
- safer long-term convergence with Sprinter Platform

### Highest visible UX improvement first

1. Batch 4
2. Batch 1
3. Batch 2
4. Batch 3
5. Batch 5

This is the right order if the goal is:

- better generic list/detail/table polish quickly
- stronger shell consistency
- improved design quality in obvious user-facing surfaces

## Recommendation

Use a blended order:

1. **Batch 1 now**
2. **A thin slice of Batch 4 immediately after**
3. **Batch 2 next**
4. **Batch 3 after the auth/store spine is stable**
5. **Batch 5 only after runtime adoption proves out**

Concretely, the first migration wave should be:

1. add exact `@sprinterai/*@0.7.1` dependencies
2. add `lib/sprinter-platform/*` compatibility wrappers
3. replace local TypeSpec, extraction-sort, and schema utilities
4. pull in Sprinter field renderers and the small bulk-toolbar / column-picker UI patterns

That combination gives:

- immediate package adoption
- real code deletion
- visible UI improvement
- low blast radius

## What Not To Do

- do not rewrite `features/views` and `features/blocks` wholesale in the first migration
- do not import `@sprinterai/*` directly across the codebase without a compatibility seam
- do not treat registry UI as npm dependencies when it should be copied or vendored as source
- do not run package migrations blindly against Amble’s database without verifying table/contract parity
- do not touch `features/custom/*` except where generic interfaces need adapters

## Immediate Next Actions

1. Add the four exact package dependencies at `0.7.1`.
2. Create `lib/sprinter-platform/{core,runtime,supabase,typespec}.ts`.
3. Migrate `features/entities/type-spec/*` to `@sprinterai/typespec`.
4. Migrate `features/entities/extraction/{dep-sort,cascade,consensus}.ts` to `@sprinterai/core/extraction`.
5. Migrate local schema-repair/completeness helpers to `@sprinterai/core/schema`.
6. Pull Sprinter registry field renderers and wire them into Amble’s generic entity surfaces.
7. Pull Sprinter bulk-toolbar and column-picker patterns into the current data table.
8. After that lands, start the auth/tenant wrapper migration.

## Validation Notes

This plan is based on:

- inspection of the local Amble codebase
- inspection of the sibling `~/Projects/sprinter-platform` workspace
- npm metadata for `@sprinterai/*`
- successful clean-room npm install and ESM import smoke checks for `0.7.1`

It does **not** yet prove:

- full Amble build compatibility with those packages
- zero schema drift between current Amble DB usage and packaged Supabase stores
- registry UI parity for every existing Amble surface

Those must be validated batch by batch.