@astrale-os/cli 1.0.0-beta.1 → 1.0.0-beta.11

package/studio/server/introspect/diff.ts

@@ -1,17 +1,13 @@
 /**
- * diff.ts — structural diff of two Schema IRs + breaking/additive classification.
- * Shared by change tracking (baseline) and data versioning. Pure.
+ * diff.ts — indicative structural diff of two Studio render IRs. Pure.
  *
  * Canonical V1 keeps optionality in the owning `required` arrays and nullability
- * in each value schema. Legacy nullable projections remain supported. Contract
- * changes are classified conservatively: removals, tightened value schemas,
- * callable/auth/policy changes, topology changes, dependency revisions and Core
- * changes are breaking; pure additions and descriptions are additive.
+ * in each value schema. This inventory makes no installation or data-migration claim;
+ * only the Kernel Runtime can assess those transitions against installed data.
  */
 import type {
   IrClass,
   IrFunction,
-  IrInterface,
   IrMethod,
   JsonSchema,
   SchemaChange,
@@ -34,28 +30,11 @@ export function baseType(s: JsonSchema | undefined): string {
   return s.enum ? `enum(${s.enum.join(',')})` : 'unknown'
 }
 
-function requiredParams(m: IrMethod | IrFunction): string[] {
-  return (
-    m.requiredParams ??
-    Object.entries(m.params ?? {}).flatMap(([name, schema]) => (isOptional(schema) ? [] : [name]))
-  )
-}
-
 function callableContract(m: IrMethod | IrFunction): unknown {
-  const required = requiredParams(m)
   return {
-    input:
-      m.input ??
-      ({
-        type: 'object',
-        properties: m.params ?? {},
-        required,
-        additionalProperties: false,
-      } satisfies JsonSchema),
-    required,
-    output: m.output ?? { mode: 'value', schema: m.returns },
-    static: m.static,
-    inheritance: m.inheritance,
+    input: m.input,
+    output: m.output,
+    ...('static' in m ? { static: m.static, inheritance: m.inheritance } : {}),
     auth: m.auth,
     policy: m.policy,
   }
@@ -75,24 +54,17 @@ export function diffSchemas(prev: SchemaIR | null, next: SchemaIR | null): Schem
       },
     )
   ) {
-    changes.push({ kind: 'schema-metadata-changed', target: next.domain, breaking: true })
+    changes.push({ kind: 'schema-metadata-changed', target: next.domain })
   }
 
-  diffValueRecord(prev.types ?? {}, next.types ?? {}, 'type', changes)
-  diffValueRecord(
-    prev.importsByKey ?? prev.imports ?? {},
-    next.importsByKey ?? next.imports ?? {},
-    'import',
-    changes,
-  )
-  diffMembers(prev.interfaces ?? {}, next.interfaces ?? {}, 'interface', changes)
-  diffMembers(prev.classes ?? {}, next.classes ?? {}, 'class', changes)
+  diffValueRecord(prev.importsByKey, next.importsByKey, 'import', changes)
+  diffMembers(prev.classes, next.classes, changes)
   diffFunctions(prev.functions ?? {}, next.functions ?? {}, changes)
   diffViews(prev.views ?? {}, next.views ?? {}, changes)
   diffValueRecord(prev.policies ?? {}, next.policies ?? {}, 'policy', changes)
   diffDependencies(prev.dependencies ?? [], next.dependencies ?? [], changes)
   if (!same(prev.core, next.core) && (prev.core !== undefined || next.core !== undefined)) {
-    changes.push({ kind: 'core-changed', target: next.domain, breaking: prev.core !== undefined })
+    changes.push({ kind: 'core-changed', target: next.domain })
   }
   return changes
 }
@@ -100,19 +72,19 @@ export function diffSchemas(prev: SchemaIR | null, next: SchemaIR | null): Schem
 function diffValueRecord(
   prev: Record<string, unknown>,
   next: Record<string, unknown>,
-  scope: 'type' | 'import' | 'policy',
+  scope: 'import' | 'policy',
   out: SchemaChange[],
 ): void {
   for (const name of sortedKeys(next)) {
     if (!(name in prev)) {
-      out.push({ kind: `${scope}-added`, target: name, breaking: false })
+      out.push({ kind: `${scope}-added`, target: name })
     }
   }
   for (const name of sortedKeys(prev)) {
     if (!(name in next)) {
-      out.push({ kind: `${scope}-removed`, target: name, breaking: true })
+      out.push({ kind: `${scope}-removed`, target: name })
     } else if (!same(prev[name], next[name])) {
-      out.push({ kind: `${scope}-changed`, target: name, breaking: true })
+      out.push({ kind: `${scope}-changed`, target: name })
     }
   }
 }
@@ -123,18 +95,18 @@ function diffFunctions(
   out: SchemaChange[],
 ): void {
   for (const name of sortedKeys(next)) {
-    if (!prev[name]) out.push({ kind: 'function-added', target: name, breaking: false })
+    if (!prev[name]) out.push({ kind: 'function-added', target: name })
   }
   for (const name of sortedKeys(prev)) {
     if (!next[name]) {
-      out.push({ kind: 'function-removed', target: name, breaking: true })
+      out.push({ kind: 'function-removed', target: name })
       continue
     }
     if (!same(callableContract(prev[name]), callableContract(next[name]))) {
-      out.push({ kind: 'function-signature-changed', target: name, breaking: true })
+      out.push({ kind: 'function-signature-changed', target: name })
     }
     if (prev[name].description !== next[name].description) {
-      out.push({ kind: 'function-metadata-changed', target: name, breaking: false })
+      out.push({ kind: 'function-metadata-changed', target: name })
     }
   }
 }
@@ -145,11 +117,11 @@ function diffViews(
   out: SchemaChange[],
 ): void {
   for (const name of sortedKeys(next)) {
-    if (!(name in prev)) out.push({ kind: 'view-added', target: name, breaking: false })
+    if (!(name in prev)) out.push({ kind: 'view-added', target: name })
   }
   for (const name of sortedKeys(prev)) {
     if (!(name in next)) {
-      out.push({ kind: 'view-removed', target: name, breaking: true })
+      out.push({ kind: 'view-removed', target: name })
       continue
     }
     if (
@@ -161,10 +133,10 @@ function diffViews(
         },
       )
     ) {
-      out.push({ kind: 'view-changed', target: name, breaking: true })
+      out.push({ kind: 'view-changed', target: name })
     }
     if (prev[name].description !== next[name].description) {
-      out.push({ kind: 'view-metadata-changed', target: name, breaking: false })
+      out.push({ kind: 'view-metadata-changed', target: name })
     }
   }
 }
@@ -182,56 +154,48 @@ function diffDependencies(
   )
   for (const origin of sortedKeys(after)) {
     if (!(origin in before)) {
-      out.push({ kind: 'dependency-added', target: origin, breaking: true })
+      out.push({ kind: 'dependency-added', target: origin })
     }
   }
   for (const origin of sortedKeys(before)) {
     if (!(origin in after)) {
-      out.push({ kind: 'dependency-removed', target: origin, breaking: true })
+      out.push({ kind: 'dependency-removed', target: origin })
     } else if (before[origin] !== after[origin]) {
       out.push({
         kind: 'dependency-changed',
         target: origin,
         detail: `${before[origin]} → ${after[origin]}`,
-        breaking: true,
       })
     }
   }
 }
 
-function memberKind(m: IrClass | IrInterface): 'class' | 'edge' | 'interface' {
-  if ((m as IrInterface).type === 'interface') return 'interface'
-  return (m as IrClass).type === 'edge' ? 'edge' : 'class'
+function memberKind(member: IrClass): 'class' | 'edge' {
+  return member.type === 'edge' ? 'edge' : 'class'
 }
 
 function diffMembers(
-  prev: Record<string, IrClass | IrInterface>,
-  next: Record<string, IrClass | IrInterface>,
-  _scope: 'class' | 'interface',
+  prev: Record<string, IrClass>,
+  next: Record<string, IrClass>,
   out: SchemaChange[],
 ): void {
   for (const name of sortedKeys(next)) {
     if (!prev[name]) {
       const k = memberKind(next[name])
-      out.push({ kind: `${k}-added` as SchemaChange['kind'], target: name, breaking: false })
+      out.push({ kind: `${k}-added` as SchemaChange['kind'], target: name })
     }
   }
   for (const name of sortedKeys(prev)) {
     if (!next[name]) {
       const k = memberKind(prev[name])
-      out.push({ kind: `${k}-removed` as SchemaChange['kind'], target: name, breaking: true })
+      out.push({ kind: `${k}-removed` as SchemaChange['kind'], target: name })
       continue
     }
     diffMemberBody(name, prev[name], next[name], out)
   }
 }
 
-function diffMemberBody(
-  name: string,
-  a: IrClass | IrInterface,
-  b: IrClass | IrInterface,
-  out: SchemaChange[],
-): void {
+function diffMemberBody(name: string, a: IrClass, b: IrClass, out: SchemaChange[]): void {
   const pa = a.properties ?? {}
   const pb = b.properties ?? {}
   for (const p of sortedKeys(pb)) {
@@ -241,13 +205,12 @@ function diffMemberBody(
         kind: 'prop-added',
         target: `${name}.${p}`,
         detail: required ? 'required' : 'optional',
-        breaking: required,
       })
     }
   }
   for (const p of sortedKeys(pa)) {
     if (!pb[p]) {
-      out.push({ kind: 'prop-removed', target: `${name}.${p}`, breaking: true })
+      out.push({ kind: 'prop-removed', target: `${name}.${p}` })
       continue
     }
     if (!same(pa[p], pb[p])) {
@@ -258,7 +221,6 @@ function diffMemberBody(
         detail: baseChanged
           ? `${baseType(pa[p])} → ${baseType(pb[p])}`
           : 'value constraints changed',
-        breaking: true,
       })
     }
     const wasOpt = !propertyRequired(a, p)
@@ -268,7 +230,6 @@ function diffMemberBody(
         kind: 'prop-required-changed',
         target: `${name}.${p}`,
         detail: wasOpt ? 'optional → required' : 'required → optional',
-        breaking: wasOpt && !nowOpt, // optional→required is breaking
       })
     }
   }
@@ -280,20 +241,19 @@ function diffMemberBody(
       out.push({
         kind: 'method-added',
         target: `${name}.${m}`,
-        breaking: b.type === 'interface' && mb[m].inheritance === 'abstract',
       })
     }
   }
   for (const m of sortedKeys(ma)) {
     if (!mb[m]) {
-      out.push({ kind: 'method-removed', target: `${name}.${m}`, breaking: true })
+      out.push({ kind: 'method-removed', target: `${name}.${m}` })
       continue
     }
     if (!same(callableContract(ma[m]), callableContract(mb[m]))) {
-      out.push({ kind: 'method-signature-changed', target: `${name}.${m}`, breaking: true })
+      out.push({ kind: 'method-signature-changed', target: `${name}.${m}` })
     }
     if (ma[m].description !== mb[m].description) {
-      out.push({ kind: 'method-metadata-changed', target: `${name}.${m}`, breaking: false })
+      out.push({ kind: 'method-metadata-changed', target: `${name}.${m}` })
     }
   }
 
@@ -302,39 +262,34 @@ function diffMemberBody(
     out.push({
       kind: `${kind}-contract-changed`,
       target: name,
-      breaking: true,
     })
   }
   if (!same(memberMetadata(a), memberMetadata(b))) {
-    out.push({ kind: 'definition-metadata-changed', target: name, breaking: false })
+    out.push({ kind: 'definition-metadata-changed', target: name })
   }
 }
 
-function propertyRequired(member: IrClass | IrInterface, name: string): boolean {
+function propertyRequired(member: IrClass, name: string): boolean {
   return member.required ? member.required.includes(name) : !isOptional(member.properties?.[name])
 }
 
-function memberContract(member: IrClass | IrInterface): unknown {
-  const cls = member as IrClass
-  const iface = member as IrInterface
+function memberContract(member: IrClass): unknown {
   return {
     type: member.type,
     origin: member.origin,
     ref: member.ref,
-    family: iface.family,
-    extends: iface.extendsRefs ?? iface.extends,
-    implements: cls.implementsRefs ?? cls.implements,
+    extends: member.extendsRefs ?? member.extends,
     endpoints: member.endpoints,
     orientation: member.orientation,
     constraints: member.constraints,
     propertyMetadata: member.propertyMetadata,
     data: member.data,
-    policies: cls.policies,
+    policies: member.policies,
   }
 }
 
-function memberMetadata(member: IrClass | IrInterface): unknown {
-  return { description: member.description, icon: (member as IrClass).icon }
+function memberMetadata(member: IrClass): unknown {
+  return { description: member.description, icon: member.icon }
 }
 
 function sortedKeys(value: Record<string, unknown>): string[] {
@@ -356,7 +311,6 @@ function canonical(value: unknown): unknown {
   )
 }
 
-export function classify(changes: SchemaChange[]): 'none' | 'additive' | 'breaking' {
-  if (changes.length === 0) return 'none'
-  return changes.some((c) => c.breaking) ? 'breaking' : 'additive'
+export function structuralStatusOf(changes: SchemaChange[]): 'none' | 'changed' {
+  return changes.length === 0 ? 'none' : 'changed'
 }

package/studio/server/introspect/extractor.ts

@@ -1,134 +1,41 @@
-/**
- * extractor.ts — the Bun-executed island. Spawned as a short-lived subprocess by
- * runtime.ts. It imports ONLY the domain's pure `schema/index.ts` module graph
- * (never astrale.config.ts or the composition entry → integrations). Canonical
- * DomainSchema V1 roots are projected directly; legacy `D.$.ir` / serialize
- * domains retain their existing fallback.
- *
- *   bun extractor.ts <schemaIndexPath> <domainDir>
- *
- * A thrown error prints { ok:false } and exits 0 — the driver treats it as a
- * render state, never a crash.
- */
+/** Bun subprocess that imports only the authored Schema entry and its installed SDK. */
 import {
-  closureFromSdk,
+  admitCanonicalSchemaFromSdk,
   findCanonicalDomainSchemaExport,
-  normalizeLegacySchemaIR,
   projectCanonicalSchema,
 } from './canonical-schema'
 
 const schemaPath = process.argv[2]
-const domainDir = process.argv[3] ?? process.cwd()
-
-async function main() {
-  if (!schemaPath) throw new Error('extractor: missing <schemaIndexPath>')
-  const mod: Record<string, any> = await import(schemaPath)
-
-  // Resolve through the DOMAIN's dependency graph. This prevents Studio's own
-  // SDK version from accepting or resolving a root authored by another cohort.
-  let sdk: Record<string, any> | null = null
-  const loadSdkSchema = async (): Promise<Record<string, any>> => {
-    if (sdk) return sdk
-    const loaded: Record<string, any> = await import(
-      Bun.resolveSync('@astrale-os/sdk/schema', domainDir)
-    )
-    sdk = loaded
-    return loaded
-  }
-
-  const canonicalRoot = findCanonicalDomainSchemaExport(mod)
-  if (canonicalRoot) {
-    const domainSdk = await loadSdkSchema()
-    const projected = projectCanonicalSchema(
-      canonicalRoot,
-      closureFromSdk(domainSdk, canonicalRoot),
-    )
-    process.stdout.write(
-      JSON.stringify({
-        ok: true,
-        ir: projected.ir,
-        root: canonicalRoot,
-        importedInterfaces: projected.importedInterfaces,
-      }),
-    )
-    return
-  }
-
-  // Prefer the conventional `D` (compiled), but accept a compiled domain exported
-  // under ANY name — e.g. ai-gateway exports its `compileDomain(...)` result as
-  // `Gateway`, not `D`. A compiled domain is recognized by shape (`.$.ir`).
-  let ir: unknown = mod?.D?.$?.ir
-  if (!ir) {
-    for (const v of Object.values(mod)) {
-      const candidate = (v as any)?.$?.ir
-      if (candidate) {
-        ir = candidate
-        break
-      }
-    }
+const projectRoot = process.argv[3] ?? process.cwd()
+
+async function main(): Promise<void> {
+  if (!schemaPath) throw new Error('extractor: missing <schemaPath>')
+  const exports = (await import(schemaPath)) as Record<string, unknown>
+  const candidate = findCanonicalDomainSchemaExport(exports)
+  if (candidate === null) {
+    throw new Error('Schema entry exports no canonical V1 DomainSchema.')
   }
-  if (!ir) {
-    // Fallback: serialize a raw schema — the conventional `schema`, else any
-    // exported `defineSchema(...)` result (recognized by its `kind === 'schema'`).
-    const schema =
-      mod?.schema ??
-      Object.values(mod).find(
-        (v) =>
-          typeof (v as any)?.domain === 'string' && !!(v as any)?.classes && !!(v as any)?.imports,
-      )
-    if (!schema) {
-      throw new Error(
-        'schema entry exports no compiled domain (a `compileDomain(...)` value with `.$.ir`, e.g. `D`) nor a raw `schema`',
-      )
-    }
-    const d = await loadSdkSchema()
-    if (typeof d.serialize !== 'function') throw new Error('kernel-dsl.serialize unavailable')
-    ir = d.serialize(schema)
-  }
-
-  // Recover member bodies of IMPORTED interfaces (kernel mixins + cross-domain
-  // interfaces). `serialize()` emits them in `ir.imports` as name-only
-  // descriptors, so re-serialize each imported schema (KernelSchema, other
-  // domains) and collect its interface definitions. Best-effort: a single import
-  // failing to serialize must never break extraction of the primary IR.
-  const importedInterfaces: Record<string, unknown> = {}
-  const importSchemas: any[] = Array.isArray(mod?.schema?.imports) ? mod.schema.imports : []
-  if (importSchemas.length > 0) {
-    try {
-      const d = await loadSdkSchema()
-      if (typeof d.serialize === 'function') {
-        for (const imp of importSchemas) {
-          try {
-            const sub = d.serialize(imp)
-            for (const [name, def] of Object.entries(sub?.interfaces ?? {})) {
-              if (!(name in importedInterfaces)) importedInterfaces[name] = def
-            }
-          } catch {
-            /* skip this import — keep going */
-          }
-        }
-      }
-    } catch {
-      /* dsl unavailable — degrade gracefully (no imported-interface bodies) */
-    }
-  }
-
+  const sdk = (await import(Bun.resolveSync('@astrale-os/sdk/schema', projectRoot))) as Record<
+    string,
+    unknown
+  >
+  const admission = admitCanonicalSchemaFromSdk(sdk, candidate)
+  const projected = projectCanonicalSchema(admission.root, admission.closure)
   process.stdout.write(
     JSON.stringify({
       ok: true,
-      ir: normalizeLegacySchemaIR(ir),
-      root: null,
-      importedInterfaces,
+      ir: projected.ir,
+      root: admission.root,
+      schemaMode: admission.status === 'admitted' ? 'canonical-admitted' : 'canonical-preview',
+      revision: admission.revision,
     }),
   )
 }
 
-main().catch((err: any) => {
+main().catch((cause: unknown) => {
+  const error = cause instanceof Error ? cause : new Error(String(cause))
   process.stdout.write(
-    JSON.stringify({
-      ok: false,
-      error: { message: String(err?.message ?? err), stack: String(err?.stack ?? '') },
-    }),
+    JSON.stringify({ ok: false, error: { message: error.message, stack: error.stack ?? '' } }),
   )
   process.exit(0)
 })

package/studio/server/introspect/hash.ts

@@ -15,7 +15,10 @@ function sortKeys(v: any): any {
   return v
 }
 
-/** sha256 over canonical JSON, short-prefixed — the schemaHash (identifies a schema version). */
-export function schemaHashOf(value: unknown): string {
+/**
+ * Short, deterministic identity for Studio rendering/cache invalidation only.
+ * This is deliberately not the DSL-owned `schema.revision()`.
+ */
+export function renderFingerprintOf(value: unknown): string {
   return 'sha-' + createHash('sha256').update(canonicalJSON(value)).digest('hex').slice(0, 12)
 }