feat: add live-model validation for Vercel schema selection (#44)

Author: rlippmann

typescript/examples/schema_selection/README.md

@@ -21,6 +21,8 @@ selects it.
 ### `vercel_ai_sdk_generate_object`
 
 Shows a host selecting a structured-output schema from compiled policy state.
+The provider-free tests are canonical, and the example also offers an opt-in
+live-model validation through Vercel AI SDK `generateObject`.
 
 ## Technology-specific examples
 

typescript/examples/schema_selection/vercel_ai_sdk_generate_object/README.md

@@ -16,6 +16,7 @@ Flow:
 - `generateObject` is the downstream host behavior, not the authority layer.
 - No model output mutates compiler state.
 - If compiler state does not authorize a schema, the host omits schema selection.
+- The provider-free tests are the canonical proof for this example.
 
 ## Boundary
 
@@ -30,12 +31,12 @@ Flow:
 Given policy state:
 
 ```text
-use python_script
-prohibit shell_command
+use refund_intake
+prohibit technical_support
 ```
 
-the host offers the `python_script` schema and does not offer the
-`shell_command` schema.
+the host offers the `refund_intake` schema and does not offer the
+`technical_support` schema.
 
 If state prohibits every known schema, the host omits schema selection and does
 not build a `generateObject` request.
@@ -47,9 +48,41 @@ Tests assert:
 - compiler state -> selected schema
 - selected schema -> request config
 - omit schema when state does not authorize one
+- contradiction triggers clarification while preserving the previously
+  authorized schema in current state
 
 Primary tests are deterministic and do not call a model.
 
+## Opt-in live-model validation
+
+The example also includes an opt-in Tier 3 path that uses the real Vercel AI
+SDK `generateObject` call with the same host-side schema selection logic.
+
+Use the same prompt across states:
+
+```text
+Customer customer-123 says: I need help with order A-100.
+```
+
+What to observe:
+
+- absent state: no schema is authorized, so the host does not call
+  `generateObject`
+- `use refund_intake`: the host selects the `refund_intake` schema and the live
+  output has refund-intake shape
+- `use technical_support`: the host selects the `technical_support` schema and
+  the live output has technical-support shape
+
+The live-model proof stays focused on absent, `refund_intake`, and
+`technical_support` selection.
+
+If you probe contradiction separately, the current deterministic behavior is:
+
+- `use refund_intake` followed by `prohibit refund_intake` produces
+  clarification from the compiler
+- the previously authorized `refund_intake` schema remains selected in current
+  state until that contradiction is resolved
+
 ## Install
 
 ```bash
@@ -65,6 +98,21 @@ npm run typecheck
 npm test
 ```
 
+Run the opt-in live-model validation:
+
+```bash
+export RUN_VERCEL_AI_SDK_LIVE_MODEL=1
+export OPENAI_API_KEY=...
+export MODEL=gpt-4o-mini
+npm test -- --test-name-pattern="live model generateObject output changes with authoritative schema selection"
+```
+
+Live-model contract:
+
+- `OPENAI_API_KEY` is required
+- `MODEL` defaults to `gpt-4o-mini`
+- canonical provider-free tests remain the primary proof
+
 ## Run the example
 
 ```bash

typescript/examples/schema_selection/vercel_ai_sdk_generate_object/package-lock.json

@@ -10,7 +10,9 @@
     "example": "node dist/src/index.js"
   },
   "dependencies": {
+    "@ai-sdk/openai": "^4.0.7",
     "@rlippmann/context-compiler": "^0.7.5",
+    "ai": "^7.0.15",
     "zod": "^3.25.76"
   },
   "devDependencies": {

typescript/examples/schema_selection/vercel_ai_sdk_generate_object/package.json

@@ -9,7 +9,7 @@ import { z, type ZodTypeAny } from "zod";
 
 declare const process: { argv: string[]; exitCode?: number };
 
-export type StructuredSchemaName = "python_script" | "shell_command";
+export type StructuredSchemaName = "refund_intake" | "technical_support";
 
 export type StructuredSchema = {
   name: StructuredSchemaName;
@@ -27,30 +27,35 @@ export type GenerateObjectLike<TObject> = (
   request: GenerateObjectRequest
 ) => Promise<{ object: TObject }>;
 
-const PYTHON_SCRIPT_SCHEMA = z.object({
-  code: z.string().describe("A complete Python script.")
+const REFUND_INTAKE_SCHEMA = z.object({
+  kind: z.literal("refund"),
+  customerId: z.string().describe("Customer identifier for the refund request."),
+  orderId: z.string().describe("Order identifier for the refund request."),
+  reason: z.string().describe("Customer reason for requesting the refund.")
 });
 
-const SHELL_COMMAND_SCHEMA = z.object({
-  command: z.string().describe("A single shell command.")
+const TECHNICAL_SUPPORT_SCHEMA = z.object({
+  kind: z.literal("technical_support"),
+  customerId: z.string().describe("Customer identifier for the support request."),
+  issue: z.string().describe("Customer issue that needs technical support.")
 });
 
 const SCHEMA_REGISTRY: Record<StructuredSchemaName, StructuredSchema> = {
-  python_script: {
-    name: "python_script",
-    description: "Generate a Python script object.",
-    schema: PYTHON_SCRIPT_SCHEMA
+  refund_intake: {
+    name: "refund_intake",
+    description: "Generate a refund intake object.",
+    schema: REFUND_INTAKE_SCHEMA
   },
-  shell_command: {
-    name: "shell_command",
-    description: "Generate a shell command object.",
-    schema: SHELL_COMMAND_SCHEMA
+  technical_support: {
+    name: "technical_support",
+    description: "Generate a technical support intake object.",
+    schema: TECHNICAL_SUPPORT_SCHEMA
   }
 };
 
 const KNOWN_SCHEMAS: readonly StructuredSchemaName[] = [
-  "python_script",
-  "shell_command"
+  "refund_intake",
+  "technical_support"
 ];
 
 export function selectStructuredSchemasFromState(
@@ -109,19 +114,32 @@ export async function generateStructuredObject<TObject>(
 export async function runExample(): Promise<{
   availableSchemaNames: StructuredSchemaName[];
   requestBuilt: boolean;
-  object: { code: string } | null;
+  object: {
+    kind: "refund";
+    customerId: string;
+    orderId: string;
+    reason: string;
+  } | null;
 }> {
   const engine = createEngine();
-  engine.step("use python_script");
-  engine.step("prohibit shell_command");
+  engine.step("use refund_intake");
+  engine.step("prohibit technical_support");
 
   const availableSchemas = selectStructuredSchemasFromState(engine.state);
-  const generated = await generateStructuredObject<{ code: string }>(
+  const generated = await generateStructuredObject<{
+    kind: "refund";
+    customerId: string;
+    orderId: string;
+    reason: string;
+  }>(
     engine.state,
-    "Write a short Python script that prints hello.",
+    "Customer customer-123 says: I need a refund for order A-100.",
     async (request) => ({
       object: {
-        code: `# schema=${request.schemaName}\nprint("hello")`
+        kind: "refund",
+        customerId: "customer-123",
+        orderId: "A-100",
+        reason: `Selected schema: ${request.schemaName}`
       }
     })
   );