fix(ai): tighten content-block types + add nightly schema-vs-type drift guard

[sroussey]

Summary

Follow-up hardening for PR #555. Tightens three runtime input types in @workglow/ai to eliminate (or document) drift between hand-written types and the JSON schemas they shadow, and adds a nightly type-drift guard so future schema or ContentBlock changes can't drift silently.

This PR targets main and is independent of PR #557 (which targets a different base).

Per-finding rationale

H-1 — AiChatTaskInput['prompt'] and ToolCallingTaskInput['prompt']

• AiChatTask.ts previously inlined the four ContentBlock variants as a literal union. Replaced with string | readonly ContentBlock[] so the runtime type reuses ContentBlock directly and a change to ContentBlock flows through automatically. The schema's items are already ContentBlockSchema, so this is the canonical match.
• ToolCallingTask.ts previously used string | (string | { type: "text" | "image" | "audio"; [x]: unknown })[] — a looser shape mirroring the JSON schema. Replaced with string | readonly (string | ContentBlock)[]. This is intentionally tighter than the schema (which still uses additionalProperties: true for UI flexibility); the drift test pins this divergence so a future schema broadening or ContentBlock change cannot drift silently.

H-2 — ChunkRetrievalTaskInput

The schema's if/then/else (when query: string, model is required) is invisible to json-schema-to-ts / FromSchema, so the hand-written discriminated union is intentionally stricter than what FromSchema would resolve to. Renamed inputSchema to the exported ChunkRetrievalInputSchema (so the drift test can reference it) and added a JSDoc block above the type explaining the intentional divergence. No behavior change.

H-3 — Drift guardrail

• packages/ai/src/task/__tests__/types.test-d.ts — vitest typecheck-mode tests using built-in expectTypeOf. Three assertions:
  • AiChat: positive assertions that the prompt type accepts every ContentBlock variant (text, image, tool_use, tool_result) and the union itself, plus FromSchema<typeof AiChatInputSchema>['prompt'] resolves to a non-trivial type. This is the right drift signal — FromSchema's resolution differs from the runtime type in non-meaningful ways (mutable array vs readonly, is_error?: vs is_error: boolean | undefined), so structural equality is too brittle.
  • ToolCalling: not.toEqualTypeOf — pins the intentional divergence. If the schema or ContentBlock ever bring the types into equality, the author should re-verify whether the tightening is still desired.
  • ChunkRetrieval: not.toEqualTypeOf — pins the if/then/else divergence. The moment FromSchema honours if/then/else, this test fails and the runtime type can switch to a FromSchema-derived form.
• .github/workflows/nightly-typecheck.yml — nightly + workflow_dispatch job that runs the drift test via bunx vitest run --typecheck --typecheck.only. Kept separate from test.yml so per-PR signal stays focused; the nightly catches drift the moment it lands on main.

A late commit (ci(ai): run drift guard in vitest typecheck mode) corrects the workflow command — .test-d.ts files are picked up by vitest's typecheck include pattern (*.{test,spec}-d.ts), not its default runtime include, so --typecheck --typecheck.only is required.

Test plan

• bunx vitest run --typecheck --typecheck.only packages/ai/src/task/__tests__/types.test-d.ts — 3/3 tests pass
• bun scripts/test.ts ai vitest — 36 files / 238 tests pass
• bun run typecheck:budget — OK (34 packages within budget); packages/ai instantiation count is flat vs baseline (the substitutions reuse already-resolved types, no extra instantiation)
• Nightly workflow lands on main after merge; the next scheduled run (or a manual workflow_dispatch) verifies CI-side

https://claude.ai/code/session_01562Z29a2UQDNBVAcJGyUoY

---

Generated by Claude Code

[sroussey]

Closing in favour of PR #565. The README changes from this PR were already committed to main directly (bc0918d). The remaining applicable fixes (export ChunkRetrievalInputSchema, drift-guard test, tsconfig update, nightly CI workflow) are cherry-picked into #565 targeting main.

---

Generated by Claude Code