refactor(blast,cli,serve): Zod-Core-Out architecture — vertical slice for blast

[stackbilt-admin]

Context

Charter's primitives are exposed through three surfaces: the programmatic API (@stackbilt/blast, @stackbilt/validate, etc.), the CLI (charter <cmd>), and the MCP server (charter serve). Today these surfaces drift:

• API contracts are TypeScript interfaces — compile-time only, no runtime validation, no machine-readable schema.
• CLI commands parse argv and format output against those types manually.
• charter serve exposes ADF-curated context as MCP resources but registers zero server.tool(...) calls — so agents can read governance but can't invoke primitives.

Result: adding a parameter to a core function means touching the API, the CLI adapter, any MCP tool wrapper, and the docs independently. The surfaces can silently disagree.

Proposal: Zod-Core-Out pattern

Make the Zod schema the single source of truth for each primitive's input/output. CLI and MCP become thin adapters that translate their respective input formats (argv, JSON-RPC) into the same schema, call the same pure core function, and format the same structured result for their respective consumers.

┌─────────────────────────┐
│  @stackbilt/blast       │   Pure core + Zod schemas
│  - BlastInputSchema     │   - z.describe() for LLMs
│  - BlastOutputSchema    │   - z.infer<> → TS types
│  - blastRadius()        │   - No I/O, no chalk, no prompts
└──────────┬──────────────┘
           │
     ┌─────┴─────┐
     ▼           ▼
┌─────────┐ ┌─────────────┐
│  CLI    │ │  MCP tool   │
│  argv → │ │  JSON-RPC → │
│  schema │ │  schema     │
│  → core │ │  → core     │
│  → ANSI │ │  → JSON     │
└─────────┘ └─────────────┘

Vertical slice: blast

Scope this PR to @stackbilt/blast end-to-end. Every other package follows the same template afterward.

Additive only (per OSS update policy):

• Add BlastInputSchema and BlastOutputSchema to packages/blast/src/index.ts.
• Keep existing BlastOptions / BlastRadiusResult interfaces — re-export as z.infer<> aliases so no consumer breaks.
• Add .describe() strings on every schema field — this is the LLM-facing documentation that MCP clients surface.
• Register charter_blast as an MCP tool in packages/cli/src/commands/serve.ts via server.tool(...) — it validates with BlastInputSchema.parse, calls blastRadius, returns structured JSON.
• Refactor packages/cli/src/commands/blast.ts to parse argv → BlastInputSchema → core → formatter. Human output unchanged.

Acceptance criteria

• @stackbilt/blast exports Zod schemas alongside existing types; BlastRadiusResult remains a valid type import.
• charter blast <path> output is byte-identical to current behavior (snapshot test).
• charter serve registers charter_blast as an MCP tool callable from Claude Code; tool schema is generated from Zod via zod-to-json-schema.
• Unit tests cover the core function with schema-validated inputs only (no child-process tests).
• No removal or rename of existing public API.

Why this first

blast is the right proof-of-concept because:

• The package is already dependency-free and headless — minimal refactor cost.
• Blast radius is an obvious agent-use-case ("what breaks if I change this file?").
• Once the pattern is proven, validate, drift, classify, and surface each become a ~1-day port.

Out of scope

• SSE transport for charter serve (separate issue).
• MCP tool wrappers for other packages (follow-up issues once the pattern lands).
• Breaking changes to existing types (policy: additive only).

[stackbilt-admin]

Review

Verdict: Technically sound, well-scoped, SDK-compatible. Three implementation details are underspecified in ways that will bite during PR review if not pinned first. One architectural decision isn't called out explicitly and should be.

What the proposal gets right (verified)

• "Zero server.tool(...) calls" — TRUE. packages/cli/src/commands/serve.ts uses server.registerTool() only (lines 84, 175). Four existing resource-style tools use the same registerTool machinery, so adding charter_blast slots cleanly into an established pattern.
• Blast is pure and headless — TRUE. packages/blast/src/index.ts imports only fs, path, and regex. Zero chalk/ora/enquirer/I-O imports. The package header literally states "Zero dependencies."
• BlastOptions/BlastRadiusResult have no external consumers — TRUE. Grep found zero cross-package imports. Re-exporting as z.infer<> aliases won't break anyone.
• @stackbilt/core already ships Zod v3.24.1 — TRUE. No new library to introduce at the monorepo level.
• Acceptance criteria are clean and testable — yes, minus the three gaps below.

Three implementation details that need pinning before the PR

1. Zod → JSON-schema conversion path is unspecified

The proposal says "tool schema is generated from Zod via zod-to-json-schema" but zod-to-json-schema is not in any package.json today, and MCP SDK 1.29.0's registerTool accepts either a Zod schema or a plain JSON-schema object — behavior differs on which. Pick one before the PR:

• (a) Pass the Zod schema directly to registerTool({ inputSchema: BlastInputSchema }) and rely on SDK's internal conversion, OR
• (b) Add zod-to-json-schema as a pinned devDependency and convert explicitly.

Either is fine, but the decision affects .describe() preservation, which is the whole LLM-facing value.

2. .optional().default() semantics for maxDepth

BlastOptions.maxDepth is optional at the type level with a runtime default of 3 baked into blastRadius() itself (index.ts:322). The CLI does the same check externally (blast.ts:41). If the Zod schema uses .optional() alone, passing nothing → undefined → the function's internal default fires → still 3. Fine. But if someone later moves the default into Zod as .optional().default(3) and removes the in-function default (which is the natural cleanup), both the MCP caller and the CLI caller's behavior change silently — including for callers passing maxDepth: 0 or undefined explicitly.

Pre-specify the exact schema. Suggest:
```ts
maxDepth: z.number().int().positive().optional().default(3)
```
…and delete the in-function default in the same commit so there's one source of truth.

3. "Snapshot-equal" is too strong without canonicalization

BlastRadiusResult.depthHistogram is Record<number, number> — JSON key order is engine-defined on numeric keys and can flip across Node majors. hotFiles is sorted by importer count descending, but ties break in insertion order (not deterministic across filesystems). Neither is currently a problem because there are no existing snapshot tests in packages/blast/__tests__/ or the CLI — but the moment you add one per this PR's acceptance criteria, you'll chase flakes.

Either:

• Canonicalize before comparing (sort keys, break hotFiles ties on filename), OR
• Replace "byte-identical snapshot" with "structural assertion" in the AC.

The architectural decision the proposal should call out

Where do BlastInputSchema/BlastOutputSchema live?

The proposal says packages/blast/src/index.ts. That's defensible but it means @stackbilt/blast gains a Zod runtime dependency (not devDep — the schema is used at runtime for .parse()). The "Zero dependencies" header comment becomes false.

Three options, pick one and justify:

1. Schemas in @stackbilt/blast (current proposal): adds Zod as a runtime dep. Cleanest for SoT. Blast's dep-free boast disappears.
2. Schemas in @stackbilt/cli (adapter-only): preserves blast purity. But then MCP tool clients that want to call blast programmatically don't get the schema from blast's public surface — breaks the "one schema, many adapters" claim.
3. Schemas in @stackbilt/core: Zod already lives there. But now @stackbilt/cli → @stackbilt/core → (schemas for blast), adding an interdependency that currently doesn't exist.

(1) is probably right — the Zod dep is ~60KB min+gz and blast already does non-trivial work, so the purity was aesthetic not functional. Just say that explicitly in the PR so it doesn't show up as an apparent regression in review.

Suggested acceptance criteria additions

• Zod→JSON-schema conversion path is pinned (either SDK-internal with a note, or a named library with version).
• BlastInputSchema.parse({}) produces maxDepth: 3 (proving default preservation); test with explicit 0 is documented as rejected.
• BlastOutputSchema validates a sample result including a depthHistogram with multiple keys and tied hotFiles, with a canonicalizer if snapshots are used.
• packages/blast/package.json is explicit about whether Zod is added as a dependency (runtime) vs devDependency (types only).

One nitpick

serve.ts:84 and :175 currently cast: (server.registerTool as Function). That's a workaround for SDK type friction that pre-dates this PR. The new charter_blast registration should use the correctly-typed overload so it doesn't inherit the cast — and ideally a follow-up removes the cast from the existing tools once the pattern is established.

---

Net: proceed, but resolve the three underspec issues and pick the schema-location lane before opening the PR. The vertical slice is the right call — validate, drift, classify, surface should be fast follow-ups once the pattern is nailed.

[stackbilt-admin]

Decisions on the review gaps

Pinning the four underspec items before implementation:

1. Zod → JSON-schema path

Pass Zod directly to server.registerTool. Matches the established pattern — all 4 existing tools in serve.ts use inputSchema: { <field>: z.string()... } (raw shape, SDK-internal conversion). No new library dependency. .describe() strings pass through to the LLM-facing tool schema.

2. maxDepth schema shape + SoT

maxDepth: z.number().int().min(1).optional().default(3)

• .min(1) preserves current CLI behavior (blast.ts:42 already rejects <1).
• .default(3) — schema is SoT. Remove options.maxDepth ?? 3 from blastRadius() (index.ts:322) in the same commit.
• Same for the CLI's internal parseInt(...) ?? 3 — argv goes through the schema.

3. Snapshot AC → structural assertions

Dropping the byte-identical snapshot goal. New AC:

• BlastOutputSchema.parse(result) passes on a representative fixture.
• hotFiles tie-breaks are made deterministic by secondary sort on filename (canonicalize in topHotFiles, not in tests).
• depthHistogram is validated via schema, not compared as a keyed object.

4. Schema location

Option (1): schemas live in @stackbilt/blast. Zod becomes a runtime dependency. The README's "zero runtime dependencies" claim gets updated — Zod ~12KB gz is the cost of the contract being authoritative at the package boundary.

Rationale: the alternative (schemas in CLI or core) breaks the "one schema, many adapters" promise. Programmatic consumers calling analyze(input) need the schema from blast's public surface, not from a downstream adapter package.

Plus one structural addition

Adding a new high-level analyze(input: BlastInput): BlastOutput function to @stackbilt/blast that composes buildGraph + blastRadius. This is what the CLI and MCP adapter both call. buildGraph and blastRadius stay public for low-level consumers — additive only.

On the nitpick

New charter_blast registration will use the typed overload without the as Function cast. Removing the cast from the existing 2 tools is a separate follow-up — out of scope for this slice.

---

Proceeding on branch refactor/blast-zod-core-out.