Enhance the Schema type to handle refs to $defs/Root or other $defs (#1919)

* Support `default` as sibling to `$ref` in JSON schemas

## Summary

Implements full support for the `default` keyword as a sibling to `$ref` in
JSON schemas, per JSON Schema 2020-12 specification. This allows schema
definitions to be reused via `$ref` while overriding default values at the
reference site.

## Motivation

JSON Schema 2020-12 permits siblings next to `$ref` (a change from earlier
specs), with the ref site properties taking precedence. Previously, our
codebase only partially supported `asCell` and `asStream` as siblings to
`$ref`. This commit extends that support to `default` and fixes gaps in the
existing sibling handling.

## Changes

### Core Schema Resolution (schema.ts)

**`resolveSchema()` [lines 47-140]**
- Captures ref site siblings (`default`, `asCell`, `asStream`) before
  resolving the `$ref`
- Applies ref site siblings to resolved schema (ref site overrides target)
- Handles boolean schema targets by converting `true` to object when
  siblings present
- Properly handles `false` schema (cannot be augmented)

### Schema Path Walking (cfc.ts)

**`schemaAtPath()` [lines 469-516]**
- Mirrors `resolveSchema()` sibling preservation pattern
- Captures and applies ref site `default`, `asCell`, `asStream`
- Fixes existing gap: previously only preserved `ifc` tags
- Now correctly handles all sibling types when walking schema paths

### Test Coverage (schema-ref-default.test.ts)

Added 19 comprehensive test cases covering:
- Basic precedence (ref site default overrides target default)
- Chained refs with defaults at multiple levels
- Boolean schema targets (`true`/`false`) with defaults
- Interaction with `asCell` and `asStream`
- `anyOf`/`oneOf` with refs having defaults
- Various default value types (primitives, objects, arrays, null)
- Edge cases with `filterAsCell` flag

## Precedence Rules

1. **Ref site default ALWAYS wins over target default**
   ```json
   { "$ref": "#/target", "default": "WINS" }
   // target: { "type": "string", "default": "loses" }
   // result: { "type": "string", "default": "WINS" }
   ```

2. **In chained refs, outermost ref site default applies**
   ```json
   { "$ref": "#/A", "default": "outer" }
   // A: { "$ref": "#/B", "default": "middle" }
   // B: { "type": "string", "default": "inner" }
   // result: { "type": "string", "default": "outer" }
   ```

3. **`default` is NOT filtered** (unlike `asCell`/`asStream` with
   `filterAsCell=true`)

4. **Target default preserved when no ref site default exists**

## Implementation Notes

**Why phases 2, 4, 5 from the plan weren't needed:**

- `processDefaultValue()` uses `resolvedSchema.default`, which now includes
  merged ref site default
- `validateAndTransform()` default checks automatically get correct
  precedence
- `anyOf`/`oneOf` handling calls `resolveSchema()` on each option, which
  handles precedence

**Existing functionality preserved:**

- All 73 existing runner tests pass (975 test steps)
- `asCell`/`asStream` filtering behavior unchanged
- IFC tag collection still works correctly
- Boolean schema handling improved

## Testing

✅ 19 new tests pass (comprehensive `default` sibling support)
✅ 73 existing runner tests pass (975 steps, no regressions)
✅ Type checking passes
✅ Code formatted with `deno fmt`

## Examples

**Basic usage:**
```typescript
const schema = {
  $defs: {
    Email: { type: "string", format: "email" }
  },
  properties: {
    userEmail: {
      $ref: "#/$defs/Email",
      default: "user@example.com"  // ← Overrides target default
    }
  }
};
```

**With asCell:**
```typescript
const schema = {
  $defs: {
    Counter: { type: "number" }
  },
  properties: {
    count: {
      $ref: "#/$defs/Counter",
      default: 0,
      asCell: true  // ← Both siblings preserved
    }
  }
};
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Add type-level $ref resolution with JSON Pointer support to Schema<> types

## Summary

Implements full type-level support for JSON Schema $ref resolution, including
JSON Pointer paths like `#/$defs/Address` and `#/properties/name`. This brings
the TypeScript type system in parity with the runtime schema resolution while
preserving proper handling of `default` values and ref site sibling merging.

## Motivation

Previously, `Schema<>` and `SchemaWithoutCell<>` only handled `$ref: "#"` (self-
reference). Any other `$ref` returned `any`, losing type information. With JSON
Pointer support, TypeScript can now resolve refs to definitions in `$defs`,
properties, and other schema locations at compile time.

## Changes

### Type System Utilities (api/index.ts)

**Path Parsing & Navigation (lines 608-670):**
- `SplitPath<>`: Parse JSON Pointer strings into path segments
- `SplitPathSegments<>`: Recursively split path on `/` delimiters
- `NavigatePath<>`: Walk schema tree following a path array
- `ResolveRef<>`: Resolve `$ref` string to target schema

**Schema Merging (lines 672-720):**
- `MergeSchemas<>`: Merge ref site siblings with target schema
- `MergeRefSiteWithTarget<>`: Merge then process with `Schema<>`
- `MergeRefSiteWithTargetWithoutCell<>`: Same for `SchemaWithoutCell<>`

Implements JSON Schema 2020-12 spec: ref site siblings (like `default`, `asCell`,
`asStream`) override corresponding properties in the target schema.

### Schema<> Type Updates

**$ref Resolution (lines 749-756):**
```typescript
// OLD: Only handled "#" refs
: T extends { $ref: "#" } ? Schema<Omit<Root, "asCell" | "asStream">, ...>
: T extends { $ref: string } ? any  // Everything else returned any

// NEW: Full JSON Pointer support
: T extends { $ref: infer RefStr extends string }
  ? MergeRefSiteWithTarget<T, ResolveRef<RefStr, ...>, ...>
```

**Benefits:**
- `#/$defs/Address` resolves to actual type
- `#/properties/name` creates type alias
- Ref site `default` overrides target `default` (JSON Schema 2020-12 spec)
- Chained refs resolve correctly (A→B→C)
- Works with `asCell`/`asStream` siblings

### Test Coverage (schema-to-ts.test.ts)

Added 11 comprehensive test cases in new describe block:
- Basic `$ref` to `$defs` resolution
- Default value precedence (ref site overrides target)
- Nested refs through multiple levels
- Chained refs (A→B→C resolves to C's type)
- Refs in array items
- Refs in `anyOf` branches
- Refs with `asCell` wrapper
- Complex nested structures with refs
- Multiple refs to same definition
- Refs to properties paths

## Type System Capabilities

**Supported:**
- `#` (self-reference to root)
- `#/$defs/Name` (definition references)
- `#/properties/field` (property references)
- Any JSON Pointer path within the document
- Default precedence (ref site wins per JSON Schema spec)
- Sibling merging (asCell, asStream, default, etc.)

**Limitations:**
- JSON Pointer escaping (~0, ~1) not supported at type level
- External refs (http://...) return `any`
- Depth limited to 9 levels for recursion safety
- Properties with `default` remain optional (correct per JSON Schema spec)

## Precedence Rules (Matches Runtime)

1. **Ref site siblings override target**: `{ $ref: "#/foo", default: "bar" }`
2. **Chained refs use outermost**: Only the original ref site siblings apply
3. **Properties with default are optional**: Type system matches JSON Schema spec
4. **Runtime fills in defaults**: Properties have fallback values at runtime

## Testing

✅ All 73 runner tests pass (987 steps, 0 failed)
✅ All 24 schema-to-ts tests pass (11 new + 13 existing)
✅ All 19 schema-ref-default tests pass (runtime $ref with default)
✅ Type checking: 3 pre-existing errors unchanged (in schema.test.ts)
✅ No new type errors introduced
✅ No breaking changes to existing code

## Examples

**Basic ref to definition:**
```typescript
type MySchema = Schema<{
  $defs: {
    Email: { type: "string"; format: "email" };
  };
  properties: {
    contact: { $ref: "#/$defs/Email" };
  };
}>;
// Result: { contact?: string }
```

**Ref with default override:**
```typescript
type MySchema = Schema<{
  $defs: {
    Counter: { type: "number"; default: 0 };
  };
  properties: {
    score: { $ref: "#/$defs/Counter"; default: 100 };
  };
}>;
// Result: { score?: number }
// At runtime, score defaults to 100 (ref site wins), not 0
```

**Chained refs:**
```typescript
type MySchema = Schema<{
  $defs: {
    C: { type: "string" };
    B: { $ref: "#/$defs/C" };
    A: { $ref: "#/$defs/B" };
  };
  properties: {
    value: { $ref: "#/$defs/A" };
  };
}>;
// Result: { value?: string } - fully resolved through chain
```

**Ref with asCell:**
```typescript
type MySchema = Schema<{
  $defs: {
    Config: { type: "object"; properties: { theme: { type: "string" } } };
  };
  properties: {
    settings: { $ref: "#/$defs/Config"; asCell: true };
  };
}>;
// Result: { settings?: Cell<{ theme?: string }> }
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Fix self-referential $ref type resolution in Schema<> types

## Problem

The previous implementation of JSON Pointer-based $ref resolution broke
type inference for self-referential schemas using `$ref: "#"`. This
caused 3 type errors in schema.test.ts:

1. Line 706: Property 'id' missing on nested Cell with `$ref: "#"`
2. Lines 978-979: Properties possibly undefined on recursive LinkedNode

## Root Cause

The generic $ref handler was processing `$ref: "#"` through
MergeRefSiteWithTarget, which created a new merged object type. This
broke the recursive type structure that TypeScript needs for proper
inference of self-referential schemas.

## Solution

1. **Special-case `$ref: "#"` before general `$ref` handler**: Added
   explicit checks for self-references in both Schema<> and
   SchemaWithoutCell<> types to preserve the original recursive type
   resolution behavior.

2. **Add non-null assertions to LinkedNode test**: Updated test
   expectations to reflect that `next` is correctly typed as optional
   per the schema definition. The old implementation typed non-"#" refs
   as `any`, hiding this issue.

## Changes

- packages/api/index.ts:
  - Schema<>: Check for `$ref: "#"` before generic `$ref` handler
  - SchemaWithoutCell<>: Same pattern for non-Cell variant

- packages/runner/test/schema.test.ts:
  - Add `!` assertions when accessing optional `next` property

## Testing

- ✅ `deno task check` passes (0 type errors)
- ✅ All runtime tests pass (73 passed, 0 failed)
- ✅ All schema-to-ts tests pass (24 steps)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Enhance the Schema type to handle refs to $defs/Root

* Updated SchemaWithoutCell utility
Properly rebuilt api types

* Move this file to the right place

* Fixed import path
Resolved schemas should have $defs still, so we can use these without a root.
Added test for a default that's one step from the top
Altered tests, since resolved schema should not have a top level $ref
A false schema should be converted into an object with `"not": true`, since we may need to preserve other schema properties.

* Remove the "cannot add default" note for the false schema test

---------

Co-authored-by: Bernhard Seefeld <berni@common.tools>
Co-authored-by: Claude <noreply@anthropic.com>

Author: 3 people

packages/api/index.ts

@@ -630,6 +630,144 @@ export type StripCell<T> = T extends Cell<infer U> ? StripCell<U>
 
 export type WishKey = `/${string}` | `#${string}`;
 
+// ===== JSON Pointer Path Resolution Utilities =====
+
+/**
+ * Split a JSON Pointer reference into path segments.
+ *
+ * Examples:
+ * - "#" -> []
+ * - "#/$defs/Address" -> ["$defs", "Address"]
+ * - "#/properties/name" -> ["properties", "name"]
+ *
+ * Note: Does not handle JSON Pointer escaping (~0, ~1) at type level.
+ * Refs with ~ in keys will not work correctly in TypeScript types.
+ */
+type SplitPath<S extends string> = S extends "#" ? []
+  : S extends `#/${infer Rest}` ? SplitPathSegments<Rest>
+  : never;
+
+type SplitPathSegments<S extends string> = S extends
+  `${infer First}/${infer Rest}` ? [First, ...SplitPathSegments<Rest>]
+  : [S];
+
+/**
+ * Navigate through a schema following a path of keys.
+ * Returns never if the path doesn't exist.
+ */
+type NavigatePath<
+  Schema extends JSONSchema,
+  Path extends readonly string[],
+  Depth extends DepthLevel = 9,
+> = Depth extends 0 ? unknown
+  : Path extends readonly [
+    infer First extends string,
+    ...infer Rest extends string[],
+  ]
+    ? Schema extends Record<string, any>
+      ? First extends keyof Schema
+        ? NavigatePath<Schema[First], Rest, DecrementDepth<Depth>>
+      : never
+    : never
+  : Schema;
+
+/**
+ * Resolve a $ref string to the target schema.
+ *
+ * Supports:
+ * - "#" (self-reference to root)
+ * - "#/path/to/def" (JSON Pointer within document)
+ *
+ * External refs (URLs) return any.
+ */
+type ResolveRef<
+  RefString extends string,
+  Root extends JSONSchema,
+  Depth extends DepthLevel,
+> = RefString extends "#" ? Root
+  : RefString extends `#/${string}`
+    ? SplitPath<RefString> extends infer Path extends readonly string[]
+      ? NavigatePath<Root, Path, Depth>
+    : never
+  : any; // External ref
+
+/**
+ * Merge two schemas, with left side taking precedence.
+ * Used to apply ref site siblings to resolved target schema.
+ */
+type MergeSchemas<
+  Left extends JSONSchema,
+  Right extends JSONSchema,
+> = Left extends boolean ? Left
+  : Right extends boolean ? Right extends true ? Left
+    : false
+  : {
+    [K in keyof Left | keyof Right]: K extends keyof Left ? Left[K]
+      : K extends keyof Right ? Right[K]
+      : never;
+  };
+
+/**
+ * Merge ref site schema with resolved target, then process with Schema<>.
+ * Implements JSON Schema spec: ref site siblings override target.
+ */
+type MergeRefSiteWithTarget<
+  RefSite extends JSONSchema,
+  Target extends JSONSchema,
+  Root extends JSONSchema,
+  Depth extends DepthLevel,
+> = RefSite extends { $ref: string }
+  ? MergeSchemas<Omit<RefSite, "$ref">, Target> extends
+    infer Merged extends JSONSchema ? Schema<Merged, Root, Depth>
+  : never
+  : never;
+
+/**
+ * Merge ref site schema with resolved target, then process with SchemaWithoutCell<>.
+ * Same as MergeRefSiteWithTarget but doesn't wrap in Cell/Stream.
+ */
+type MergeRefSiteWithTargetWithoutCell<
+  RefSite extends JSONSchema,
+  Target extends JSONSchema,
+  Root extends JSONSchema,
+  Depth extends DepthLevel,
+> = RefSite extends { $ref: string }
+  ? MergeSchemas<Omit<RefSite, "$ref">, Target> extends
+    infer Merged extends JSONSchema ? SchemaWithoutCell<Merged, Root, Depth>
+  : never
+  : never;
+
+/**
+ * Convert a JSON Schema to its TypeScript type equivalent.
+ *
+ * Supports:
+ * - Primitive types (string, number, boolean, null)
+ * - Objects with properties (required/optional)
+ * - Arrays with items
+ * - anyOf unions
+ * - $ref resolution (including JSON Pointers)
+ * - asCell/asStream reactive wrappers
+ * - default values (makes properties required)
+ *
+ * $ref Support:
+ * - "#" (self-reference to root schema)
+ * - "#/$defs/Name" (JSON Pointer to definition)
+ * - "#/properties/field" (JSON Pointer to any schema location)
+ * - External refs (http://...) return type `any`
+ *
+ * Default Precedence:
+ * When both ref site and target have `default`, ref site takes precedence
+ * per JSON Schema 2020-12 specification.
+ *
+ * Limitations:
+ * - JSON Pointer escaping (~0, ~1) not supported at type level
+ * - Depth limited to 9 levels to prevent infinite recursion
+ * - Complex allOf/oneOf logic may not match runtime exactly
+ *
+ * @template T - The JSON Schema to convert
+ * @template Root - Root schema for $ref resolution
+ * @template Depth - Recursion depth limit (0-9)
+ */
 export type Schema<
   T extends JSONSchema,
   Root extends JSONSchema = T,
@@ -642,14 +780,16 @@ export type Schema<
     // Handle asStream attribute - wrap the result in Stream<T>
     : T extends { asStream: true }
       ? Stream<Schema<Omit<T, "asStream">, Root, Depth>>
-    // Handle $ref to root
-    : T extends { $ref: "#" } ? Schema<
-        Omit<Root, "asCell" | "asStream">,
+    // Handle $ref: "#" (self-reference) specially to preserve recursion
+    : T extends { $ref: "#" }
+      ? Schema<Omit<Root, "asCell" | "asStream">, Root, DecrementDepth<Depth>>
+    // Handle $ref - resolve and merge with ref site schema
+    : T extends { $ref: infer RefStr extends string } ? MergeRefSiteWithTarget<
+        T,
+        ResolveRef<RefStr, Root, DecrementDepth<Depth>>,
         Root,
         DecrementDepth<Depth>
       >
-    // Handle other $ref (placeholder - would need a schema registry for other refs)
-    : T extends { $ref: string } ? any
     // Handle enum values
     : T extends { enum: infer E extends readonly any[] } ? E[number]
     // Handle oneOf (not yet supported in schema.ts, so commenting out)
@@ -774,8 +914,8 @@ type Decrement = {
 // Helper function to safely get decremented depth
 type DecrementDepth<D extends DepthLevel> = Decrement[D] & DepthLevel;
 
-// Same as above, but ignoreing asCell, so we never get cells. This is used for
-// calles of lifted functions and handlers, since they can pass either cells or
+// Same as above, but ignoring asCell, so we never get cells. This is used for
+// calls of lifted functions and handlers, since they can pass either cells or
 // values.
 
 export type SchemaWithoutCell<
@@ -791,14 +931,20 @@ export type SchemaWithoutCell<
     // Handle asStream attribute - but DON'T wrap in Stream, just use the inner type
     : T extends { asStream: true }
       ? SchemaWithoutCell<Omit<T, "asStream">, Root, Depth>
-    // Handle $ref to root
+    // Handle $ref: "#" (self-reference) specially to preserve recursion
     : T extends { $ref: "#" } ? SchemaWithoutCell<
         Omit<Root, "asCell" | "asStream">,
         Root,
         DecrementDepth<Depth>
       >
-    // Handle other $ref (placeholder - would need a schema registry for other refs)
-    : T extends { $ref: string } ? any
+    // Handle $ref - resolve and merge with ref site schema
+    : T extends { $ref: infer RefStr extends string }
+      ? MergeRefSiteWithTargetWithoutCell<
+        T,
+        ResolveRef<RefStr, Root, DecrementDepth<Depth>>,
+        Root,
+        DecrementDepth<Depth>
+      >
     // Handle enum values
     : T extends { enum: infer E extends readonly any[] } ? E[number]
     // Handle oneOf (not yet supported in schema.ts, so commenting out)

packages/runner/test/schema-ref-default.test.ts

@@ -70,6 +70,20 @@ describe("$ref with default support", () => {
       expect(resolved).toHaveProperty("default", "outermost");
     });
 
+    it("should handle chained refs with defaults at each level (outermost wins)", () => {
+      const schema: JSONSchema = {
+        $defs: {
+          Level3: { type: "string", default: "level3" },
+          Level2: { $ref: "#/$defs/Level3", default: "level2" },
+          Level1: { $ref: "#/$defs/Level2", default: "level1" },
+        },
+        $ref: "#/$defs/Level1",
+      };
+
+      const resolved = resolveSchema(schema, schema, false);
+      expect(resolved).toHaveProperty("default", "level1");
+    });
+
     it("should preserve default even when filterAsCell is true", () => {
       const schema: JSONSchema = {
         $defs: {
@@ -116,10 +130,11 @@ describe("$ref with default support", () => {
       };
 
       const resolved = resolveSchema(schema, schema, false);
+      // false schema means nothing validates, but we can still have properties
       expect(resolved).toEqual({
         $defs: schema.$defs,
+        "not": true,
         default: "foo",
-        not: true,
       });
     });
   });
@@ -315,30 +330,4 @@ describe("$ref with default support", () => {
       });
     });
   });
-
-  it("should return undefined when circular $ref is detected with filterAsCell=true", () => {
-    const rootSchema: JSONSchema = {
-      $defs: {
-        Circular: { $ref: "#/$defs/Circular", asCell: true },
-      },
-      $ref: "#/$defs/Circular",
-      asCell: true,
-    };
-
-    const resolved = resolveSchema(rootSchema, rootSchema, true);
-    expect(resolved).not.toBeDefined();
-  });
-
-  it("should return undefined when circular $ref is detected with filterAsCell=false", () => {
-    const rootSchema: JSONSchema = {
-      $defs: {
-        Circular: { $ref: "#/$defs/Circular", asCell: true },
-      },
-      $ref: "#/$defs/Circular",
-      asCell: true,
-    };
-
-    const resolved = resolveSchema(rootSchema, rootSchema, false);
-    expect(resolved).not.toBeDefined();
-  });
 });