@astrale-os/cli 1.0.0-beta.0 → 1.0.0-beta.10

package/studio/server/introspect/canonical-schema.ts

@@ -1,21 +1,18 @@
 /**
- * Pure projection of the canonical, portable DomainSchema V1 document into the
- * Studio's backward-compatible render IR. This module deliberately imports no
- * Kernel or SDK package: extractor islands must interpret the schema emitted by
- * the domain's own SDK cohort, not a second copy installed beside Studio.
+ * Pure projection from an SDK-admitted portable DomainSchema into Studio's
+ * intentionally lossy render model. The extractor calls the authored Domain's
+ * own installed SDK for admission before this module interprets the document.
  */
 import type {
   IrCallableAuth,
   IrCallableOutput,
   IrClass,
-  IrDefinitionKey,
-  IrDefinitionRef,
+  IrClassKey,
+  IrClassRef,
   IrEndpoint,
   IrFunction,
   IrImportDescriptor,
-  IrInterface,
   IrMethod,
-  IrSchemaKey,
   IrSchemaRef,
   IrView,
   JsonSchema,
@@ -23,6 +20,9 @@ import type {
   StudioCore,
 } from '../../shared/types'
 
+import { classRefKey, isIrClassRef, schemaRefKey } from '../../shared/schema/identity'
+import { isSchemaRevision } from '../../shared/types'
+
 type AnyRecord = Record<string, unknown>
 
 export type CanonicalDomainSchemaV1 = AnyRecord & {
@@ -32,10 +32,23 @@ export type CanonicalDomainSchemaV1 = AnyRecord & {
 }
 
 export interface CanonicalSchemaProjection {
-  ir: SchemaIR
-  importedInterfaces: Record<string, IrInterface>
+  readonly ir: SchemaIR
 }
 
+export type CanonicalSchemaAdmission =
+  | {
+      readonly status: 'admitted'
+      readonly root: CanonicalDomainSchemaV1
+      readonly closure: CanonicalDomainSchemaV1[]
+      readonly revision: `sha256:${string}`
+    }
+  | {
+      readonly status: 'preview'
+      readonly root: CanonicalDomainSchemaV1
+      readonly closure: CanonicalDomainSchemaV1[]
+      readonly revision: null
+    }
+
 export function isCanonicalDomainSchemaV1(value: unknown): value is CanonicalDomainSchemaV1 {
   const candidate = asRecord(value)
   return (
@@ -52,89 +65,78 @@ export function findCanonicalDomainSchemaExport(
 ): CanonicalDomainSchemaV1 | null {
   if (isCanonicalDomainSchemaV1(moduleExports.schema)) return moduleExports.schema
   if (isCanonicalDomainSchemaV1(moduleExports.default)) return moduleExports.default
-
-  const candidates = Object.entries(moduleExports)
-    .filter((entry): entry is [string, CanonicalDomainSchemaV1] =>
-      isCanonicalDomainSchemaV1(entry[1]),
-    )
-    .sort(([left], [right]) => left.localeCompare(right))
-  return candidates[0]?.[1] ?? null
+  return (
+    Object.entries(moduleExports)
+      .filter((entry): entry is [string, CanonicalDomainSchemaV1] =>
+        isCanonicalDomainSchemaV1(entry[1]),
+      )
+      .sort(([left], [right]) => left.localeCompare(right))[0]?.[1] ?? null
+  )
 }
 
-/**
- * Read the exact retained dependency closure through the domain's own SDK.
- * Calls are optional and fail closed: an unrecognised/substituted result is
- * discarded rather than trusted as imported-schema evidence.
- */
+/** Read the exact retained dependency closure through the authored SDK. */
 export function closureFromSdk(
   sdkModule: Record<string, unknown>,
   root: CanonicalDomainSchemaV1,
 ): CanonicalDomainSchemaV1[] {
-  const bundleApi = asRecord(sdkModule.bundle)
-  const create = bundleApi?.create
-  if (typeof create === 'function') {
-    try {
-      const candidate = Reflect.apply(create, bundleApi, [root])
-      const bundle = asRecord(candidate)
-      if (bundle?.root === root) {
-        const closure = admitClosure(bundle.closure, root)
-        if (closure) return closure
-      }
-    } catch {
-      // A structurally V1-looking export may lack retained SDK admission context.
-    }
+  const create = asRecord(sdkModule.bundle)?.create
+  if (typeof create !== 'function') return []
+  try {
+    const candidate = asRecord(Reflect.apply(create, undefined, [root]))
+    if (candidate?.root !== root) return []
+    return admitClosure(candidate.closure, root) ?? []
+  } catch {
+    return []
   }
+}
 
+/** Re-admit one portable root and prove its revision through the authored SDK. */
+export function admitCanonicalSchemaFromSdk(
+  sdkModule: Record<string, unknown>,
+  candidate: CanonicalDomainSchemaV1,
+): CanonicalSchemaAdmission {
+  const retainedClosure = closureFromSdk(sdkModule, candidate)
   const schemaApi = asRecord(sdkModule.schema)
+  const accept = schemaApi?.accept
+  const revision = schemaApi?.revision
   const resolve = schemaApi?.resolve
-  if (typeof resolve === 'function') {
-    try {
-      const candidate = asRecord(Reflect.apply(resolve, schemaApi, [root]))
-      const resolution = asRecord(candidate?.$)
-      if (resolution?.schema === root) {
-        const closure = admitClosure(resolution.closure, root)
-        if (closure) return closure
-      }
-    } catch {
-      // Missing retained context is a valid degradation: local schema still renders.
-    }
+  if (
+    typeof accept !== 'function' ||
+    typeof revision !== 'function' ||
+    typeof resolve !== 'function'
+  ) {
+    return { status: 'preview', root: candidate, closure: retainedClosure, revision: null }
   }
 
-  return []
-}
-
-/** Add fields required by the current shared contract to a legacy serializer IR. */
-export function normalizeLegacySchemaIR(value: unknown): SchemaIR {
-  const ir = asRecord(value)
-  if (!ir) throw new TypeError('legacy schema IR must be an object')
-
-  const functions: Record<string, IrFunction> = {}
-  for (const [name, raw] of entriesOf(ir.functions)) {
-    const declaration = asRecord(raw) ?? {}
-    const params = schemaRecord(declaration.params)
-    const returns = studioSchema(declaration.returns)
-    const requiredParams =
-      declaration.input === undefined
-        ? legacyRequiredParams(params)
-        : requiredNames(declaration.input)
-    functions[name] = {
-      name,
-      input: studioSchema(declaration.input ?? objectInputFromParams(params, requiredParams)),
-      params,
-      requiredParams,
-      output: callableOutput(declaration.output, returns),
-      returns,
-      static: true,
-      inheritance: 'default',
-      ...(callableAuth(declaration.auth) ? { auth: callableAuth(declaration.auth) } : {}),
-      ...(typeof declaration.description === 'string'
-        ? { description: declaration.description }
-        : {}),
-      ...(declaration.policy === undefined ? {} : { policy: jsonCopy(declaration.policy) }),
+  try {
+    const revisions = new Map<string, string>()
+    for (const dependency of retainedClosure) {
+      const value = Reflect.apply(revision, schemaApi, [dependency])
+      if (!isSchemaRevision(value)) throw new TypeError('SDK returned an invalid revision.')
+      revisions.set(dependency.origin, value)
+    }
+    const lookup = {
+      get(origin: string, expected: string): CanonicalDomainSchemaV1 | undefined {
+        const dependency = retainedClosure.find((entry) => entry.origin === origin)
+        return dependency && revisions.get(origin) === expected ? dependency : undefined
+      },
+    }
+    const accepted = Reflect.apply(accept, schemaApi, [candidate, lookup])
+    if (!isCanonicalDomainSchemaV1(accepted) || accepted.origin !== candidate.origin) {
+      throw new TypeError('SDK admission returned another root.')
     }
+    const acceptedRevision = Reflect.apply(revision, schemaApi, [accepted])
+    if (!isSchemaRevision(acceptedRevision))
+      throw new TypeError('SDK returned an invalid revision.')
+    const domain = asRecord(Reflect.apply(resolve, schemaApi, [accepted]))
+    if (domain?.source !== accepted || domain.origin !== accepted.origin) {
+      throw new TypeError('SDK resolution did not retain the admitted root.')
+    }
+    const closure = closureFromSdk(sdkModule, accepted)
+    return { status: 'admitted', root: accepted, closure, revision: acceptedRevision }
+  } catch {
+    return { status: 'preview', root: candidate, closure: retainedClosure, revision: null }
   }
-
-  return { ...(ir as unknown as SchemaIR), functions }
 }
 
 export function projectCanonicalSchema(
@@ -142,12 +144,6 @@ export function projectCanonicalSchema(
   closure: readonly CanonicalDomainSchemaV1[] = [],
 ): CanonicalSchemaProjection {
   const origin = root.origin
-  const interfaces = Object.fromEntries(
-    entriesOf(root.interfaces).map(([name, declaration]) => [
-      name,
-      projectInterface(origin, name, declaration),
-    ]),
-  )
   const classes = Object.fromEntries(
     entriesOf(root.classes).map(([name, declaration]) => [
       name,
@@ -163,193 +159,138 @@ export function projectCanonicalSchema(
   const views = Object.fromEntries(
     entriesOf(root.views).map(([name, declaration]) => [name, projectView(name, declaration)]),
   )
-
-  const importsByKey: Record<IrDefinitionKey, IrImportDescriptor> = {}
-  const importedInterfacesByKey: Record<IrDefinitionKey, IrInterface> = {}
   const schemas = new Map(
-    closure.filter(isCanonicalDomainSchemaV1).map((schema) => [schema.origin, schema]),
+    closure.filter(isCanonicalDomainSchemaV1).map((value) => [value.origin, value]),
   )
-  const pending = collectDefinitionRefs(root)
+  const importsByKey = {} as Record<IrClassKey, IrImportDescriptor>
+  const importedClassesByKey = {} as Record<IrClassKey, IrClass>
+  const pending = collectClassRefs(root)
   const visited = new Set<string>()
 
-  for (let index = 0; index < pending.length; index++) {
+  for (let index = 0; index < pending.length; index += 1) {
     const ref = pending[index]
-    if (!isDefinitionRef(ref) || ref.origin === origin) continue
-    const key = definitionKey(ref)
+    if (ref.origin === origin) continue
+    const key = classRefKey(ref)
     if (visited.has(key)) continue
     visited.add(key)
-
-    importsByKey[key] = {
-      origin: ref.origin,
-      definition: ref.kind,
-      ref,
-      key,
-    }
-    if (ref.kind !== 'interface' || key in importedInterfacesByKey) continue
-
+    importsByKey[key] = { origin: ref.origin, ref, key }
     const owner = schemas.get(ref.origin)
-    const declaration = asRecord(asRecord(owner?.interfaces)?.[ref.name])
-    if (!owner || !declaration) continue
-    const projected = projectInterface(owner.origin, ref.name, declaration)
-    importedInterfacesByKey[key] = projected
-    pending.push(...collectDefinitionRefsFromDeclaration(declaration))
+    const declaration = asRecord(asRecord(owner?.classes)?.[ref.name])
+    if (owner === undefined || declaration === null) continue
+    importedClassesByKey[key] = projectClass(owner.origin, ref.name, declaration)
+    pending.push(...collectClassRefsFromClass(declaration))
   }
 
-  // Bare member names are retained solely as an unambiguous compatibility
-  // lookup. The canonical Key maps above remain complete when origins or kinds
-  // reuse a name, and prevent a traversal-order-dependent "first one wins".
-  const nameCounts = new Map<string, number>()
-  for (const descriptor of Object.values(importsByKey)) {
-    const name = descriptor.ref?.name
-    if (name) nameCounts.set(name, (nameCounts.get(name) ?? 0) + 1)
-  }
-  const localNames = new Set([...Object.keys(interfaces), ...Object.keys(classes)])
-  const isUnambiguous = (name: string): boolean =>
-    nameCounts.get(name) === 1 && !localNames.has(name)
-  const imports = Object.fromEntries(
-    Object.values(importsByKey).flatMap((descriptor) => {
-      const name = descriptor.ref?.name
-      return name && isUnambiguous(name) ? [[name, descriptor]] : []
-    }),
-  )
-  const importedInterfaces = Object.fromEntries(
-    Object.values(importedInterfacesByKey).flatMap((declaration) =>
-      isUnambiguous(declaration.name) ? [[declaration.name, declaration]] : [],
-    ),
-  )
-
-  const dependencies = arrayOf(root.dependencies)
-    .map(asRecord)
-    .filter((dependency): dependency is AnyRecord => dependency !== null)
-    .flatMap((dependency) =>
-      typeof dependency.origin === 'string' && typeof dependency.revision === 'string'
-        ? [{ origin: dependency.origin, revision: dependency.revision }]
-        : [],
-    )
+  const dependencies = arrayOf(root.dependencies).flatMap((value) => {
+    const dependency = asRecord(value)
+    return typeof dependency?.origin === 'string' && typeof dependency.revision === 'string'
+      ? [{ origin: dependency.origin, revision: dependency.revision }]
+      : []
+  })
 
   return {
     ir: {
       format: 'astrale.dsl',
       version: 'v1',
       domain: origin,
-      types: schemaRecord(root.types),
-      interfaces,
       classes,
-      imports,
       importsByKey,
-      importedInterfacesByKey,
+      importedClassesByKey,
       functions,
       views,
       policies: recordCopy(root.policies),
       dependencies,
       core: jsonCopy(root.core),
     },
-    importedInterfaces,
   }
 }
 
-/** Project canonical genesis data without importing the effectful Domain entry. */
+/** Project canonical Core data without importing Application or Runtime modules. */
 export function projectCanonicalCore(
   root: CanonicalDomainSchemaV1,
 ): Pick<StudioCore, 'domain' | 'nodes' | 'edges'> {
   const core = asRecord(root.core) ?? {}
   const nodes = entriesOf(core.nodes).map(([slug, raw]) => {
     const node = asRecord(raw) ?? {}
-    const classRef = schemaRef(node.class)
+    const selectedClass = classRef(node.class)
     return {
-      path: corePath({ origin: root.origin, kind: 'core', name: slug }),
-      className: classRef?.name ?? '?',
+      path: corePath({ origin: root.origin, name: slug }),
+      className: selectedClass?.name ?? '?',
       data: recordCopy(node.properties),
     }
   })
   const edges = arrayOf(core.edges).map((raw) => {
     const edge = asRecord(raw) ?? {}
-    const classRef = schemaRef(edge.class)
     return {
       from: coreEndpoint(edge.source, root.origin),
       to: coreEndpoint(edge.target, root.origin),
-      edgeName: classRef?.name ?? '?',
+      edgeName: classRef(edge.class)?.name ?? '?',
       ...(edge.properties === undefined ? {} : { data: recordCopy(edge.properties) }),
     }
   })
   return { domain: root.origin, nodes, edges }
 }
 
-function projectInterface(origin: string, name: string, value: unknown): IrInterface {
-  const declaration = asRecord(value) ?? {}
-  const family = definitionFamily(declaration.family, 'both')
-  const extendsRefs = refsOf(declaration.extends, 'interface')
-  return {
-    type: 'interface',
-    name,
-    origin,
-    family,
-    ref: { origin, kind: 'interface', name },
-    extends: extendsRefs.map((ref) => ref.name),
-    extendsRefs,
-    properties: propertySchemas(declaration),
-    required: requiredNames(declaration.properties),
-    methods: projectMethods(declaration.methods),
-    ...(family === 'edge' ? edgeFields(declaration) : {}),
-    ...(typeof declaration.description === 'string'
-      ? { description: declaration.description }
-      : {}),
-    ...(asRecord(declaration.propertyMetadata)
-      ? { propertyMetadata: recordCopy(declaration.propertyMetadata) }
-      : {}),
-    ...(dataDeclaration(declaration.data) ? { data: dataDeclaration(declaration.data) } : {}),
-  }
-}
-
 function projectClass(origin: string, name: string, value: unknown): IrClass {
   const declaration = asRecord(value) ?? {}
-  const family = definitionFamily(declaration.family, 'node') === 'edge' ? 'edge' : 'node'
-  const implementsRefs = refsOf(declaration.implements, 'interface')
+  const kind = declaration.kind === 'edge' ? 'edge' : 'node'
+  const extendsRefs = refsOf(declaration.extends)
+  const propertyEntries = entriesOf(declaration.properties)
+  const properties = Object.fromEntries(
+    propertyEntries.map(([propertyName, raw]) => [
+      propertyName,
+      studioSchema(asRecord(raw)?.schema),
+    ]),
+  )
+  const required = propertyEntries.flatMap(([propertyName, raw]) =>
+    asRecord(raw)?.required === true ? [propertyName] : [],
+  )
+  const propertyMetadata = Object.fromEntries(
+    propertyEntries.map(([propertyName, raw]) => {
+      const member = { ...(asRecord(raw) ?? {}) }
+      delete member.schema
+      return [propertyName, jsonCopy(member)]
+    }),
+  )
   const policies = Object.fromEntries(
     entriesOf(declaration.policies).flatMap(([policyName, raw]) => {
-      const ref = schemaRef(raw)
+      const ref = definitionRefOf(raw)
       return ref ? [[policyName, ref]] : []
     }),
   )
   return {
-    type: family,
+    type: kind,
     name,
     origin,
     ref: { origin, kind: 'class', name },
-    implements: implementsRefs.map((ref) => ref.name),
-    implementsRefs,
-    properties: propertySchemas(declaration),
-    required: requiredNames(declaration.properties),
+    extends: extendsRefs.map((ref) => ref.name),
+    extendsRefs,
+    properties,
+    required,
     methods: projectMethods(declaration.methods),
-    ...(family === 'edge' ? edgeFields(declaration) : {}),
-    ...(typeof declaration.icon === 'string' ? { icon: declaration.icon } : {}),
+    ...(kind === 'edge' ? edgeFields(declaration) : {}),
     ...(typeof declaration.description === 'string'
       ? { description: declaration.description }
       : {}),
-    ...(asRecord(declaration.propertyMetadata)
-      ? { propertyMetadata: recordCopy(declaration.propertyMetadata) }
-      : {}),
+    ...(Object.keys(propertyMetadata).length === 0 ? {} : { propertyMetadata }),
     ...(dataDeclaration(declaration.data) ? { data: dataDeclaration(declaration.data) } : {}),
-    ...(Object.keys(policies).length > 0 ? { policies } : {}),
+    ...(Object.keys(policies).length === 0 ? {} : { policies }),
   }
 }
 
 function projectMethods(value: unknown): Record<string, IrMethod> {
   return Object.fromEntries(
-    entriesOf(value).map(([name, declaration]) => {
-      const callable = projectCallable(name, declaration)
-      const raw = asRecord(declaration) ?? {}
+    entriesOf(value).map(([name, raw]) => {
+      const declaration = asRecord(raw) ?? {}
       const inheritance =
-        raw.inheritance === 'abstract' ||
-        raw.inheritance === 'sealed' ||
-        raw.inheritance === 'default'
-          ? raw.inheritance
+        declaration.inheritance === 'abstract' || declaration.inheritance === 'sealed'
+          ? declaration.inheritance
           : 'default'
       return [
         name,
         {
-          ...callable,
-          static: raw.static === true,
+          ...projectCallable(name, declaration),
+          static: declaration.static === true,
           inheritance,
         } satisfies IrMethod,
       ]
@@ -357,50 +298,40 @@ function projectMethods(value: unknown): Record<string, IrMethod> {
   )
 }
 
-function projectFunction(name: string, declaration: unknown): IrFunction {
-  return {
-    ...projectCallable(name, declaration),
-    static: true,
-    inheritance: 'default',
-  }
+function projectFunction(name: string, value: unknown): IrFunction {
+  return projectCallable(name, value)
 }
 
-function projectCallable(name: string, value: unknown): Omit<IrFunction, 'static' | 'inheritance'> {
+function projectCallable(name: string, value: unknown): IrFunction {
   const declaration = asRecord(value) ?? {}
   const input = studioSchema(declaration.input)
-  const output = callableOutput(declaration.output, {})
+  const output = callableOutput(declaration.output)
   const auth = callableAuth(declaration.auth)
   return {
     name,
     input,
-    params: callableParams(declaration.input),
-    requiredParams: requiredNames(declaration.input),
     output,
-    returns: outputValue(output),
     ...(typeof declaration.description === 'string'
       ? { description: declaration.description }
       : {}),
-    ...(auth ? { auth } : {}),
+    ...(auth === undefined ? {} : { auth }),
     ...(declaration.policy === undefined ? {} : { policy: jsonCopy(declaration.policy) }),
   }
 }
 
 function projectView(name: string, value: unknown): IrView {
   const declaration = asRecord(value) ?? {}
-  const rawTarget = asRecord(declaration.target)
-  const target =
-    rawTarget?.kind === 'definition'
-      ? ({
-          kind: 'definition',
-          definitions: refsOf(rawTarget.definitions, ['class', 'interface']),
-        } as const)
-      : ({ kind: 'domain' } as const)
-  const auth =
-    declaration.auth === 'optional' || declaration.auth === 'public' ? declaration.auth : 'required'
+  const target = asRecord(declaration.target)
   return {
     name,
-    target,
-    auth,
+    target:
+      target?.kind === 'definition'
+        ? { kind: 'definition', definitions: refsOf(target.definitions) }
+        : { kind: 'domain' },
+    auth:
+      declaration.auth === 'optional' || declaration.auth === 'public'
+        ? declaration.auth
+        : 'required',
     ...(typeof declaration.description === 'string'
       ? { description: declaration.description }
       : {}),
@@ -419,250 +350,186 @@ function edgeFields(
           projectEndpoint(endpoints?.source, 'outgoing'),
           projectEndpoint(endpoints?.target, 'incoming'),
         ]
-  const rawConstraints = asRecord(declaration.constraints)
-  const constraints = {
-    ...(rawConstraints?.noSelf === true ? { noSelf: true as const } : {}),
-    ...(rawConstraints?.acyclic === true ? { acyclic: true as const } : {}),
+  const constraints = asRecord(declaration.constraints)
+  return {
+    endpoints: projected,
+    orientation,
+    constraints: {
+      ...(constraints?.noSelf === true ? { noSelf: true } : {}),
+      ...(constraints?.acyclic === true ? { acyclic: true } : {}),
+    },
   }
-  return { endpoints: projected, orientation, constraints }
 }
 
 function projectEndpoint(
   value: unknown,
-  countKey: 'outgoing' | 'incoming' | 'incident',
+  cardinality: 'outgoing' | 'incoming' | 'incident',
 ): IrEndpoint {
   const endpoint = asRecord(value) ?? {}
-  const refs = refsOf(endpoint.accepts, ['class', 'interface'])
-  const cardinality = edgeCount(endpoint[countKey])
+  const refs = refsOf(endpoint.accepts)
+  const count = edgeCount(endpoint[cardinality])
   return {
     name: typeof endpoint.role === 'string' ? endpoint.role : '',
     types: refs.map((ref) => ref.name),
     refs,
-    ...(cardinality ? { cardinality } : {}),
+    ...(count === undefined ? {} : { cardinality: count }),
   }
 }
 
 function edgeCount(value: unknown): IrEndpoint['cardinality'] | undefined {
-  switch (value) {
-    case '0..*':
-      return { min: 0, max: null }
-    case '1..*':
-      return { min: 1, max: null }
-    case '0..1':
-      return { min: 0, max: 1 }
-    case '1':
-      return { min: 1, max: 1 }
-    default:
-      return undefined
-  }
-}
-
-function propertySchemas(declaration: AnyRecord): Record<string, JsonSchema> {
-  const object = asRecord(declaration.properties) ?? {}
-  return Object.fromEntries(
-    entriesOf(object.properties).map(([name, schema]) => [name, studioSchema(schema)]),
-  )
-}
-
-function callableParams(input: unknown): Record<string, JsonSchema> {
-  const object = asRecord(input)
-  if (!object) return {}
-  return Object.fromEntries(
-    entriesOf(object.properties).map(([name, schema]) => [name, studioSchema(schema)]),
-  )
+  if (value === '0..*') return { min: 0, max: null }
+  if (value === '1..*') return { min: 1, max: null }
+  if (value === '0..1') return { min: 0, max: 1 }
+  if (value === '1') return { min: 1, max: 1 }
+  return undefined
 }
 
-function callableOutput(value: unknown, fallback: JsonSchema): IrCallableOutput {
-  const output = asRecord(value)
-  if (output?.mode === 'stream') return { mode: 'stream', item: studioSchema(output.item) }
-  if (output?.mode === 'binary') return { mode: 'binary' }
-  if (output?.mode === 'value') return { mode: 'value', schema: studioSchema(output.schema) }
-  return { mode: 'value', schema: fallback }
-}
-
-function outputValue(output: IrCallableOutput): JsonSchema {
-  if (output.mode === 'value') return output.schema
-  if (output.mode === 'stream') return output.item
-  return {}
-}
-
-function callableAuth(value: unknown): IrCallableAuth | undefined {
-  return value === 'anonymous' || value === 'authenticated' || value === 'authorized'
-    ? value
-    : undefined
-}
-
-function definitionFamily(value: unknown, fallback: 'node' | 'both'): 'node' | 'edge' | 'both' {
-  return value === 'node' || value === 'edge' || value === 'both' ? value : fallback
-}
-
-function dataDeclaration(
-  value: unknown,
-): { mediaType: string; [key: string]: unknown } | undefined {
-  const data = asRecord(value)
-  return typeof data?.mediaType === 'string'
-    ? (jsonCopy(data) as { mediaType: string; [key: string]: unknown })
-    : undefined
-}
-
-function refsOf(
-  value: unknown,
-  kinds: IrSchemaRef['kind'] | readonly IrSchemaRef['kind'][],
-): IrSchemaRef[] {
-  const accepted = new Set(Array.isArray(kinds) ? kinds : [kinds])
-  return arrayOf(value)
-    .map(schemaRef)
-    .filter((ref): ref is IrSchemaRef => ref !== null && accepted.has(ref.kind))
-}
-
-function schemaRef(value: unknown): IrSchemaRef | null {
-  const ref = asRecord(value)
-  if (!ref || typeof ref.origin !== 'string' || typeof ref.name !== 'string') return null
-  switch (ref.kind) {
-    case 'type':
-    case 'interface':
-    case 'class':
-    case 'function':
-    case 'policy':
-    case 'view':
-    case 'core':
-      return { origin: ref.origin, kind: ref.kind, name: ref.name }
-    default:
-      return null
-  }
-}
-
-function collectDefinitionRefs(root: CanonicalDomainSchemaV1): IrSchemaRef[] {
-  const refs: IrSchemaRef[] = []
-  for (const [, declaration] of entriesOf(root.types)) {
-    collectPathSchemaRefs(declaration, refs)
-  }
-  for (const [, declaration] of entriesOf(root.interfaces)) {
-    refs.push(...collectDefinitionRefsFromDeclaration(declaration))
-  }
+function collectClassRefs(root: CanonicalDomainSchemaV1): IrClassRef[] {
+  const refs: IrClassRef[] = []
   for (const [, declaration] of entriesOf(root.classes)) {
-    refs.push(...collectDefinitionRefsFromDeclaration(declaration))
+    refs.push(...collectClassRefsFromClass(declaration))
   }
   for (const [, callable] of entriesOf(root.functions)) collectCallableRefs(callable, refs)
   for (const [, view] of entriesOf(root.views)) {
-    const target = asRecord(asRecord(view)?.target)
-    refs.push(...refsOf(target?.definitions, ['class', 'interface']))
+    refs.push(...refsOf(asRecord(asRecord(view)?.target)?.definitions))
   }
   const core = asRecord(root.core)
-  for (const [, node] of entriesOf(core?.nodes)) addRef(asRecord(node)?.class, refs)
+  for (const [, node] of entriesOf(core?.nodes)) addClassRef(asRecord(node)?.class, refs)
   for (const edge of arrayOf(core?.edges)) {
     const declaration = asRecord(edge)
-    addRef(declaration?.class, refs)
-    addRef(declaration?.source, refs)
-    addRef(declaration?.target, refs)
+    addClassRef(declaration?.class, refs)
   }
-  collectPolicyRefs(root.policies, refs)
-  return uniqueRefs(refs)
+  for (const [, policy] of entriesOf(root.policies)) collectPolicyRefs(policy, refs)
+  return uniqueClassRefs(refs)
 }
 
-function collectDefinitionRefsFromDeclaration(value: unknown): IrSchemaRef[] {
+function collectClassRefsFromClass(value: unknown): IrClassRef[] {
   const declaration = asRecord(value) ?? {}
-  const refs = [
-    ...refsOf(declaration.extends, 'interface'),
-    ...refsOf(declaration.implements, 'interface'),
-  ]
-  collectPathSchemaRefs(declaration.properties, refs)
+  const refs = [...refsOf(declaration.extends)]
   const endpoints = asRecord(declaration.endpoints)
   for (const endpoint of [
     endpoints?.source,
     endpoints?.target,
     ...arrayOf(declaration.endpoints),
   ]) {
-    refs.push(...refsOf(asRecord(endpoint)?.accepts, ['class', 'interface']))
+    refs.push(...refsOf(asRecord(endpoint)?.accepts))
+  }
+  for (const [, property] of entriesOf(declaration.properties)) {
+    collectPathSchemaRefs(asRecord(property)?.schema, refs)
   }
   for (const [, callable] of entriesOf(declaration.methods)) collectCallableRefs(callable, refs)
-  for (const [, policy] of entriesOf(declaration.policies)) addRef(policy, refs)
-  return uniqueRefs(refs)
+  for (const [, policy] of entriesOf(declaration.policies)) collectPolicyRefs(policy, refs)
+  return uniqueClassRefs(refs)
 }
 
-function collectCallableRefs(value: unknown, refs: IrSchemaRef[]): void {
+function collectCallableRefs(value: unknown, refs: IrClassRef[]): void {
   const callable = asRecord(value)
-  if (!callable) return
+  if (callable === null) return
   collectPathSchemaRefs(callable.input, refs)
   const output = asRecord(callable.output)
   collectPathSchemaRefs(output?.schema ?? output?.item, refs)
   collectPolicyRefs(callable.policy, refs)
 }
 
-/** Embedded value data is opaque; only the declared x-astrale-path vocabulary carries refs. */
-function collectPathSchemaRefs(value: unknown, refs: IrSchemaRef[]): void {
+function collectPathSchemaRefs(value: unknown, refs: IrClassRef[]): void {
   if (Array.isArray(value)) {
     for (const item of value) collectPathSchemaRefs(item, refs)
     return
   }
   const object = asRecord(value)
-  if (!object) return
+  if (object === null) return
   const annotation = asRecord(object['x-astrale-path'])
-  if (annotation) refs.push(...refsOf(annotation.accepts, ['class', 'interface']))
+  refs.push(...refsOf(annotation?.accepts))
   for (const [key, child] of Object.entries(object)) {
     if (key === 'const' || key === 'enum' || key === 'default' || key === 'examples') continue
     collectPathSchemaRefs(child, refs)
   }
 }
 
-function collectPolicyRefs(value: unknown, refs: IrSchemaRef[]): void {
+function collectPolicyRefs(value: unknown, refs: IrClassRef[]): void {
   if (Array.isArray(value)) {
     for (const item of value) collectPolicyRefs(item, refs)
     return
   }
   const object = asRecord(value)
-  if (!object) return
-  for (const key of ['check', 'class', 'ref']) addRef(object[key], refs)
-  for (const key of [
-    'allOf',
-    'anyOf',
-    'exists',
-    'where',
-    'match',
-    'nodes',
-    'source',
-    'target',
-    'object',
-  ]) {
-    collectPolicyRefs(object[key], refs)
-  }
+  if (object === null) return
+  addClassRef(object.class, refs)
+  for (const child of Object.values(object)) collectPolicyRefs(child, refs)
 }
 
-function addRef(value: unknown, refs: IrSchemaRef[]): void {
-  const ref = schemaRef(value)
-  if (ref) refs.push(ref)
+function addClassRef(value: unknown, refs: IrClassRef[]): void {
+  const ref = classRef(value)
+  if (ref !== null) refs.push(ref)
 }
 
-function uniqueRefs(refs: readonly IrSchemaRef[]): IrSchemaRef[] {
+function refsOf(value: unknown): IrClassRef[] {
+  return arrayOf(value)
+    .map(classRef)
+    .filter((ref): ref is IrClassRef => ref !== null)
+}
+
+function classRef(value: unknown): IrClassRef | null {
+  const ref = definitionRefOf(value)
+  return ref !== null && isIrClassRef(ref) ? ref : null
+}
+
+function definitionRefOf(value: unknown): IrSchemaRef | null {
+  const ref = asRecord(value)
+  if (typeof ref?.origin !== 'string' || typeof ref.name !== 'string') return null
+  if (
+    ref.kind !== 'class' &&
+    ref.kind !== 'function' &&
+    ref.kind !== 'policy' &&
+    ref.kind !== 'view' &&
+    ref.kind !== 'core'
+  ) {
+    return null
+  }
+  return { origin: ref.origin, kind: ref.kind, name: ref.name }
+}
+
+function uniqueClassRefs(refs: readonly IrClassRef[]): IrClassRef[] {
   const seen = new Set<string>()
   return refs.filter((ref) => {
-    const key = refKey(ref)
+    const key = classRefKey(ref)
     if (seen.has(key)) return false
     seen.add(key)
     return true
   })
 }
 
-function refKey(ref: IrSchemaRef): IrSchemaKey {
-  return `${ref.origin}:${ref.kind}.${ref.name}`
+function callableOutput(value: unknown): IrCallableOutput {
+  const output = asRecord(value)
+  if (output?.mode === 'stream') return { mode: 'stream', item: studioSchema(output.item) }
+  if (output?.mode === 'binary') return { mode: 'binary' }
+  return { mode: 'value', schema: studioSchema(output?.schema) }
 }
 
-function isDefinitionRef(ref: IrSchemaRef): ref is IrDefinitionRef {
-  return ref.kind === 'class' || ref.kind === 'interface'
+function callableAuth(value: unknown): IrCallableAuth | undefined {
+  return value === 'anonymous' || value === 'authenticated' || value === 'authorized'
+    ? value
+    : undefined
 }
 
-function definitionKey(ref: IrDefinitionRef): IrDefinitionKey {
-  return `${ref.origin}:${ref.kind}.${ref.name}`
+function dataDeclaration(
+  value: unknown,
+): { mediaType: string; [key: string]: unknown } | undefined {
+  const data = asRecord(value)
+  return typeof data?.mediaType === 'string'
+    ? (jsonCopy(data) as { mediaType: string; [key: string]: unknown })
+    : undefined
 }
 
 function coreEndpoint(value: unknown, rootOrigin: string): string {
   const endpoint = asRecord(value)
-  if (endpoint?.kind === 'domain') return `/:${rootOrigin}`
-  const ref = schemaRef(value)
+  if (endpoint?.kind === 'domain' && typeof endpoint.origin === 'string') {
+    return `/:${endpoint.origin}`
+  }
+  const ref = definitionRefOf(value)
   return ref?.kind === 'core' ? corePath(ref) : `/:${rootOrigin}`
 }
 
-function corePath(ref: Pick<IrSchemaRef, 'origin' | 'kind' | 'name'>): string {
+function corePath(ref: Pick<IrSchemaRef, 'origin' | 'name'>): string {
   return `/:${ref.origin}:core.${ref.name}`
 }
 
@@ -673,11 +540,11 @@ function admitClosure(
   if (!Array.isArray(value)) return null
   const closure: CanonicalDomainSchemaV1[] = []
   const origins = new Set<string>()
-  for (const schema of value) {
-    if (!isCanonicalDomainSchemaV1(schema) || schema.origin === root.origin) return null
-    if (origins.has(schema.origin)) return null
-    origins.add(schema.origin)
-    closure.push(schema)
+  for (const candidate of value) {
+    if (!isCanonicalDomainSchemaV1(candidate) || candidate.origin === root.origin) return null
+    if (origins.has(candidate.origin)) return null
+    origins.add(candidate.origin)
+    closure.push(candidate)
   }
   return closure
 }
@@ -688,52 +555,17 @@ function studioSchema(value: unknown): JsonSchema {
   return (jsonCopy(asRecord(value) ?? {}) ?? {}) as JsonSchema
 }
 
-function schemaRecord(value: unknown): Record<string, JsonSchema> {
-  return Object.fromEntries(entriesOf(value).map(([name, schema]) => [name, studioSchema(schema)]))
-}
-
-function requiredNames(value: unknown): string[] {
-  const object = asRecord(value)
-  return arrayOf(object?.required).filter((name): name is string => typeof name === 'string')
-}
-
-function legacyRequiredParams(params: Record<string, JsonSchema>): string[] {
-  return Object.entries(params).flatMap(([name, schema]) =>
-    schemaAllowsNull(schema) ? [] : [name],
-  )
-}
-
-function schemaAllowsNull(schema: JsonSchema): boolean {
-  if (schema.type === 'null') return true
-  if (Array.isArray(schema.type) && schema.type.includes('null')) return true
-  return [...arrayOf(schema.anyOf), ...arrayOf(schema.oneOf)].some(
-    (candidate) => asRecord(candidate)?.type === 'null',
-  )
-}
-
-function objectInputFromParams(
-  params: Record<string, JsonSchema>,
-  required: readonly string[],
-): JsonSchema {
-  return {
-    type: 'object',
-    properties: params,
-    required: [...required],
-    additionalProperties: false,
-  }
-}
-
-function recordCopy(value: unknown): Record<string, any> {
+function recordCopy(value: unknown): Record<string, unknown> {
   const record = asRecord(value)
-  return record ? (jsonCopy(record) as Record<string, any>) : {}
+  return record === null ? {} : (jsonCopy(record) as Record<string, unknown>)
 }
 
 function jsonCopy(value: unknown): any {
   if (Array.isArray(value)) return value.map(jsonCopy)
   const record = asRecord(value)
-  if (record)
-    return Object.fromEntries(Object.entries(record).map(([key, item]) => [key, jsonCopy(item)]))
-  return value
+  return record === null
+    ? value
+    : Object.fromEntries(Object.entries(record).map(([key, item]) => [key, jsonCopy(item)]))
 }
 
 function entriesOf(value: unknown): [string, unknown][] {