Support full transitive cross-schema resolution

[mindsocket]

• add a dedicated schema ref traversal module for transitive cross-file/internal `` resolution
• recursively flatten nested allOf compositions for schema introspection used by template-sync and schemas show
• keep schema.ts focused on registry/validator/metadata concerns
• add regression fixtures/tests covering multi-hop cross-schema resolution
• document transitive schema ref behavior in README and schemas docs

Testing

• bun run test
• bun run lint

Closes #33

[claude]

Bug: flattenAllOf has no cycle detection for mutually recursive allOf schemas — infinite loop / stack overflow

The stack passed here is designed to detect cycles in consecutive $ref chains (e.g. A $ref→ B $ref→ A), but it cannot detect cycles that cross allOf boundaries. The reason is that resolveRefWithContext calls stack.delete(target.refKey) before returning, so by the time flattenAllOf iterates over the resolved schema's allOf sub-entries (line 166–168), the stack is empty again and holds no memory of what schemas are currently being flattened.

Concrete example that causes infinite recursion:

// Schema A: { "$id": "A", "allOf": [{ "$ref": "B" }] }
// Schema B: { "$id": "B", "allOf": [{ "$ref": "A" }] }

Trace:

1. flattenAllOf(A) → resolveRefWithContext(A) returns immediately (no $ref). Stack: {}
2. Iterates A's allOf: [{$ref:"B"}] → calls flattenAllOf({$ref:"B"})
3. resolveRefWithContext({$ref:"B"}) → stack.add("B#"), resolves B (no $ref), stack.delete("B#"). Stack: {}
4. Iterates B's allOf: [{$ref:"A"}] → calls flattenAllOf({$ref:"A"})
5. resolveRefWithContext({$ref:"A"}) → stack.add("A#"), resolves A, stack.delete("A#"). Stack: {}
6. Iterates A's allOf: [{$ref:"B"}] → back to step 2 → infinite recursion

Suggested fix: Give flattenAllOf its own visited set that tracks which resolved schema IDs are currently being processed, separate from the $ref-chain stack. Before recursing into a resolved schema's allOf entries, check if that schema's ID is already in the visited set and skip it if so:

function flattenAllOf(
  def: AnySchemaObject | undefined,
  rootSchema: AnySchemaObject,
  registry: Map<string, AnySchemaObject>,
  stack: Set<string>,
  visited = new Set<string>(),   // ← new parameter
): ResolvedSchema[] {
  const resolved = resolveRefWithContext(def, rootSchema, registry, stack);
  if (!resolved) return [];

  const schemaId = typeof resolved.schema.$id === 'string' ? resolved.schema.$id : undefined;
  if (schemaId && visited.has(schemaId)) return [];  // ← cycle guard
  if (schemaId) visited.add(schemaId);               // ← mark as in-progress

  const parts: ResolvedSchema[] = [];
  const allOf = asArray<AnySchemaObject>(resolved.schema.allOf);
  for (const sub of allOf) {
    parts.push(...flattenAllOf(sub, resolved.rootSchema, registry, stack, visited));
  }
  // ...
}

Note that mergeVariantProperties (line 198) and callers would also need to pass visited through, or the default parameter handles it automatically for the top-level call.