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:

Sprinter Platform today

Published npm packages:

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

Comparison: Where Amble Is Still Ahead

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:

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:

{
  "@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

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.