feat(sdk): compile structured outputs to json_schema

[kjgbot]

Outcome

Adds structured output: JSON Schema declarations to llm and agent
StepSpecs and compiles them onto the existing kernel
verification.json_schema primitive. No kernel files or vocabulary changed.

• YAML and object StepSpecs accept output: <JSON Schema>; normalized specs
  carry the equivalent verification and the kernel boundary never sees a new
  field.
• Non-object schemas and simultaneous output + verification declarations
  fail closed, including callers that invoke toKernelSpec directly.
• The canonical hn-monitor authoring YAML uses output: without changing its
  canonical kernel step.
• Live journal assertions pin accepted parsed JSON and rejected output: null
  plus the failed schema verdict.
• The SDK deliberately does not publish an unchecked phantom parsed-result
  type. Typed f.llm / f.agent return values remain open in v2 authoring ergonomics: close the gaps found in the research-flow / v1 comparison #132 until the
  imperative surface has a real consumer.

Refs #132.

Scope boundary

This is issue #132 slice 1 only. It does not publish
@relayflows/surface, implement imperative typed return values, or close #132.
v1 explicit verification: remains supported.

Review repairs at 5ab0fee

The fresh review found that the original expectTypeOf assertion was never
typechecked and that OutputFromSchema / TOutput were speculative public API.
This head:

• adds sdk/tsconfig.tests.json, runs it from normal npm test, and gates it
  in the exact-head artifact workflow;
• removes the unused phantom result API;
• centralizes output validation and pins direct raw toKernelSpec calls;
• makes the internal normalization path fail closed;
• documents the lowering contract in docs/SURFACE.md.

Literal red type-gate evidence

With one deliberately false assertion temporarily added:

$ ./node_modules/.bin/tsc -p tsconfig.tests.json
tests/typed-output.test.ts(35,57): error TS2344: Type 'string' does not satisfy the constraint '"Expected: string, Actual: undefined" | "Expected: string, Actual: ..."'.
EXIT=2

The false assertion was removed before commit.

Literal green evidence

$ ./node_modules/.bin/tsc -p tsconfig.tests.json && ./node_modules/.bin/vitest run tests/typed-output.test.ts --reporter=verbose

Test Files  1 passed (1)
     Tests  14 passed (14)
EXIT=0

$ ./node_modules/.bin/tsc && node scripts/make-cli-executable.mjs && ./node_modules/.bin/tsc -p tsconfig.tests.json
[no output]
EXIT=0

Complete SDK/live-kernel run after rebuilding sdk/dist:

$ PATH=/opt/homebrew/Cellar/node/26.7.0/bin:$PATH RELAYFLOWD_BIN=/Users/khaliqgant/.relayflows-toolchain/target/1914866954/debug/relayflowd ./node_modules/.bin/vitest run

stdout | tests/live-kernel.test.ts > built flows CLI against live relayflowd > hn-monitor analyze-story reaches done through the real Claude analyzer CLI
LIVE_ANALYZER ready: claude -p --model claude-haiku-4-5-20251001 round-trip OK

stdout | tests/live-kernel.test.ts > surface resume after a real daemon kill > resumes a three-step run with each successful completion exactly once
LIVE_KERNEL kill -9 pid=35187 run=01M1HAP5BE5B53H453ATBWQFR2 while step=two state=Running

Test Files  18 passed (18)
     Tests  251 passed (251)
Duration  57.88s
EXIT=0

$ git diff --check
[no output]
EXIT=0

Environment note

No kernel source changed. The live run names the prebuilt relayflowd binary
used because the host cargo shim remains broken; this is not represented as a
fresh kernel build. The GitHub workflow builds relayflowd from the exact PR
head on Linux before assembling the artifact.

[coderabbitai]

Warning

Review limit reached

Next included review available in 17 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: ab524ffd-e362-4add-8608-a1d383c2d289

📥 Commits

Reviewing files that changed from the base of the PR and between 5ab0fee and 54361d7.

📒 Files selected for processing (3)

• ops/reviews/20260902-1620-pr133-history.md
• ops/reviews/20260902-1620-pr133-structure.md
• ops/reviews/20260902-1625-pr133-maintainability.md

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: fca379f0-8b50-4f7d-bb52-e006eac41a33

📥 Commits

Reviewing files that changed from the base of the PR and between a0d42ff and 5ab0fee.

📒 Files selected for processing (12)

• .github/workflows/cloud-runtime-artifact.yml
• docs/SURFACE.md
• sdk/package.json
• sdk/src/compile.ts
• sdk/src/index.ts
• sdk/src/output-schema.ts
• sdk/src/spec.ts
• sdk/src/validate.ts
• sdk/tests/live-kernel.test.ts
• sdk/tests/typed-output.test.ts
• sdk/tsconfig.tests.json
• testdata/hn-monitor.flow.yaml

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The SDK adds output JSON Schema declarations for LLM and agent steps. Validation rejects malformed or conflicting declarations. Compilation maps valid declarations to verification.json_schema, and runtime tests cover successful and rejected outputs.

Changes

Structured output support

Layer / File(s)	Summary
Authoring contract and validation sdk/src/output-schema.ts, sdk/src/spec.ts, sdk/src/index.ts, sdk/src/validate.ts	LLM and agent steps accept public output schemas. Validation checks object shape and rejects combined output and verification declarations.
Compilation to kernel verification sdk/src/compile.ts, sdk/tests/typed-output.test.ts, testdata/hn-monitor.flow.yaml, docs/SURFACE.md	Valid output declarations compile to json_schema verification. Tests cover TypeScript, YAML, public-boundary conversion, conflicts, malformed schemas, and the updated fixture.
Runtime output and rejection behavior sdk/tests/live-kernel.test.ts	Live-kernel tests verify promoted output after successful validation and null output after retry exhaustion.
SDK build and test validation sdk/tsconfig.tests.json, sdk/package.json, .github/workflows/cloud-runtime-artifact.yml	The SDK test workflow adds test type-checking. The artifact workflow builds and tests the SDK before building the standalone CLI.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 5ab0f

The PR adds validated JSON Schema output declarations while preserving existing verification behavior and reports passing typecheck and test coverage; no actionable merge-blocking risk remains.

Poem

A rabbit reads each line,
The patch grows clear beneath the moon,
Small changes hop in place,
Tests guard the garden path,
Reviews bloom before the dawn.

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Essentials by visiting https://app.coderabbit.ai/settings/billing.

_{Comment @coderabbitai help to get the list of available commands.}