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

package/studio/server/introspect/revision.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from 'bun:test'
+
+import { admittedBundleRevisionFromSdk } from './revision'
+
+const REVISION = `sha256:${'a'.repeat(64)}` as const
+
+describe('installed Bundle revision', () => {
+  test('uses bundle admission before asking the cohort schema owner for its revision', () => {
+    const calls: string[] = []
+    const root = { format: 'astrale.dsl', version: 'v1', origin: 'notes.example.dev' }
+    const input = { wire: true }
+    const sdk = {
+      bundle: {
+        accept(value: unknown) {
+          calls.push('bundle.accept')
+          expect(value).toBe(input)
+          return { root, closure: [] }
+        },
+      },
+      schema: {
+        revision(value: unknown) {
+          calls.push('schema.revision')
+          expect(value).toBe(root)
+          return REVISION
+        },
+      },
+    }
+
+    expect(admittedBundleRevisionFromSdk(sdk, input)).toBe(REVISION)
+    expect(calls).toEqual(['bundle.accept', 'schema.revision'])
+  })
+
+  test('fails closed when bundle admission or the returned revision is invalid', () => {
+    expect(
+      admittedBundleRevisionFromSdk(
+        { bundle: { accept: () => ({ root: {} }) }, schema: { revision: () => 'sha-short' } },
+        {},
+      ),
+    ).toBeNull()
+    expect(
+      admittedBundleRevisionFromSdk(
+        {
+          bundle: {
+            accept: () => {
+              throw new Error('invalid bundle')
+            },
+          },
+          schema: { revision: () => REVISION },
+        },
+        {},
+      ),
+    ).toBeNull()
+  })
+})

package/studio/server/introspect/revision.ts

@@ -0,0 +1,49 @@
+import type { SchemaRevision } from '../../shared/types'
+
+import { isSchemaRevision } from '../../shared/types'
+
+type AnyRecord = Record<string, unknown>
+
+/**
+ * Cross the installed-bundle JSON boundary through one exact SDK cohort, then
+ * ask the DSL owner for the root revision. Invalid/unavailable bundles return
+ * null so Studio reports unknown drift instead of inventing an identity.
+ */
+export function admittedBundleRevisionFromSdk(
+  sdkModule: Record<string, unknown>,
+  input: unknown,
+): SchemaRevision | null {
+  const bundleApi = asRecord(sdkModule.bundle)
+  const schemaApi = asRecord(sdkModule.schema)
+  if (typeof bundleApi?.accept !== 'function' || typeof schemaApi?.revision !== 'function') {
+    return null
+  }
+  try {
+    const accepted = asRecord(Reflect.apply(bundleApi.accept, bundleApi, [input]))
+    if (!accepted || !Object.prototype.hasOwnProperty.call(accepted, 'root')) return null
+    const revision = Reflect.apply(schemaApi.revision, schemaApi, [accepted.root])
+    return isSchemaRevision(revision) ? revision : null
+  } catch {
+    return null
+  }
+}
+
+export async function admittedBundleRevision(
+  domainRoot: string,
+  input: unknown,
+): Promise<SchemaRevision | null> {
+  try {
+    const sdkModule: Record<string, unknown> = await import(
+      Bun.resolveSync('@astrale-os/sdk/schema', domainRoot)
+    )
+    return admittedBundleRevisionFromSdk(sdkModule, input)
+  } catch {
+    return null
+  }
+}
+
+function asRecord(value: unknown): AnyRecord | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as AnyRecord)
+    : null
+}

package/studio/server/introspect/runtime.test.ts

@@ -6,7 +6,8 @@ import { join } from 'node:path'
 import type { DomainHandle } from '../domain'
 
 import { buildBundle } from './bundle'
-import { schemaHashOf } from './hash'
+import { renderFingerprintOf } from './hash'
+import { admittedBundleRevision } from './revision'
 import { coreExtract, runtimeExtract } from './runtime'
 
 const roots: string[] = []
@@ -40,7 +41,7 @@ function currentFixture(): DomainHandle {
     schemaIndex,
     `
 import {
-  defineSchema, domain, edge, edgeClass, fn, node, nodeClass,
+  bundle, defineSchema, domain, edge, edgeClass, fn, node, nodeClass,
   nodeInterface, output, property, view,
 } from '@astrale-os/sdk/schema'
 
@@ -84,6 +85,7 @@ export const schema = defineSchema('documents.runtime.test', {
     edges: [edge(welcome, owned_by, domain(), {})],
   },
 })
+export const installedBundle = bundle.create(schema)
 `,
   )
   // Canonical core extraction must not import the effectful composition entry.
@@ -105,6 +107,8 @@ describe('current SDK schema extractor', () => {
     const result = await runtimeExtract(handle.schemaIndex, handle.root)
 
     expect(result.ok).toBe(true)
+    expect(result.schemaMode).toBe('canonical-admitted')
+    expect(result.revision).toMatch(/^sha256:[0-9a-f]{64}$/)
     expect(result.root).toMatchObject({
       format: 'astrale.dsl',
       version: 'v1',
@@ -133,15 +137,48 @@ describe('current SDK schema extractor', () => {
     })
   })
 
-  test('hashes the raw canonical root instead of the render projection', async () => {
+  test('transports the DSL revision and fingerprints the root only for rendering', async () => {
     const handle = currentFixture()
     const extracted = await runtimeExtract(handle.schemaIndex, handle.root)
     expect(extracted.ok).toBe(true)
+    if (extracted.revision === null) throw new Error('expected an admitted schema revision')
 
     const bundle = await buildBundle(handle)
     expect(bundle.schemaRoot).toEqual(extracted.root)
-    expect(bundle.schemaHash).toBe(schemaHashOf(extracted.root))
-    expect(bundle.schemaHash).not.toBe(schemaHashOf(extracted.ir))
+    expect(bundle.schemaMode).toBe('canonical-admitted')
+    expect(bundle.schemaRevision).toBe(extracted.revision)
+    expect(bundle.renderFingerprint).toBe(renderFingerprintOf(extracted.root))
+    expect(bundle.renderFingerprint).not.toBe(renderFingerprintOf(extracted.ir))
+  })
+
+  test('re-admits installed Bundle JSON before comparing its DSL revision', async () => {
+    const handle = currentFixture()
+    const extracted = await runtimeExtract(handle.schemaIndex, handle.root)
+    if (extracted.revision === null) throw new Error('expected an admitted local schema revision')
+    const fixture = (await import(handle.schemaIndex)) as { installedBundle: unknown }
+    const installedWire = JSON.parse(JSON.stringify(fixture.installedBundle))
+
+    expect(await admittedBundleRevision(handle.root, installedWire)).toBe(extracted.revision)
+  })
+
+  test('renders a V1-shaped but unadmitted root only as a structural preview', async () => {
+    const root = fixtureRoot('canonical-preview')
+    linkCurrentSdk(root)
+    const schemaIndex = join(root, 'schema', 'index.ts')
+    writeFileSync(
+      schemaIndex,
+      `export const schema = {
+        format: 'astrale.dsl', version: 'v1', origin: 'not an origin',
+        dependencies: [], types: {}, interfaces: {}, classes: {}, functions: {},
+        policies: {}, views: {}, core: { nodes: {}, edges: [] },
+      }\n`,
+    )
+
+    const result = await runtimeExtract(schemaIndex, root)
+    expect(result.ok).toBe(true)
+    expect(result.schemaMode).toBe('canonical-preview')
+    expect(result.revision).toBeNull()
+    expect(result.root).toMatchObject({ format: 'astrale.dsl', version: 'v1' })
   })
 
   test('extracts canonical core without importing implementation.ts', async () => {
@@ -172,6 +209,27 @@ describe('current SDK schema extractor', () => {
   })
 })
 
+test('runtime extractor preserves the legacy compiled-IR envelope', async () => {
+  const root = fixtureRoot('legacy-runtime')
+  const schemaIndex = join(root, 'schema', 'index.ts')
+  writeFileSync(
+    schemaIndex,
+    `export const D = { $: { ir: {
+      version: 'legacy', domain: 'legacy.runtime.test', types: {}, interfaces: {},
+      classes: {}, imports: {}, functions: {},
+    } } }\n`,
+  )
+
+  const result = await runtimeExtract(schemaIndex, root)
+  expect(result).toMatchObject({
+    ok: true,
+    schemaMode: 'legacy',
+    revision: null,
+    root: null,
+    ir: { domain: 'legacy.runtime.test', functions: {} },
+  })
+})
+
 test('core extractor preserves the legacy defineCore fallback', async () => {
   const root = fixtureRoot('legacy-core')
   const schemaIndex = join(root, 'schema', 'index.ts')

package/studio/server/introspect/runtime.ts

@@ -5,7 +5,15 @@
  * render IR plus the raw canonical root (when present), or an error render-state
  * — never throws.
  */
-import type { IrInterface, SchemaIR, StudioCore } from '../../shared/types'
+import type {
+  IrInterface,
+  SchemaIR,
+  SchemaRevision,
+  StudioCore,
+  StudioSchemaBundle,
+} from '../../shared/types'
+
+import { isSchemaRevision } from '../../shared/types'
 
 const EXTRACTOR = new URL('./extractor.ts', import.meta.url).pathname
 const CORE_EXTRACTOR = new URL('./core-extractor.ts', import.meta.url).pathname
@@ -13,8 +21,11 @@ const CORE_EXTRACTOR = new URL('./core-extractor.ts', import.meta.url).pathname
 export interface RuntimeExtractResult {
   ok: boolean
   ir: SchemaIR | null
-  /** Exact canonical V1 root. Null for legacy `D.$.ir` domains and failures. */
+  /** Portable canonical V1 document. Null for legacy domains and failures. */
   root: unknown | null
+  schemaMode: StudioSchemaBundle['schemaMode']
+  /** Present only when the Domain cohort SDK admitted `root`. */
+  revision: SchemaRevision | null
   /** member bodies of imported (kernel + cross-domain) interfaces, by name */
   importedInterfaces?: Record<string, IrInterface>
   error?: { message: string }
@@ -42,6 +53,8 @@ export async function runtimeExtract(
         ok: false,
         ir: null,
         root: null,
+        schemaMode: 'unavailable',
+        revision: null,
         error: { message: err.trim() || 'extractor produced no output' },
       }
     }
@@ -51,16 +64,49 @@ export async function runtimeExtract(
         ok: false,
         ir: null,
         root: null,
+        schemaMode: 'unavailable',
+        revision: null,
         error: parsed.error ?? { message: 'extraction failed' },
       }
+    const schemaMode = parsed.schemaMode
+    const revision = parsed.revision
+    const validMode =
+      schemaMode === 'canonical-admitted' ||
+      schemaMode === 'canonical-preview' ||
+      schemaMode === 'legacy'
+    const validRevision =
+      schemaMode === 'canonical-admitted' ? isSchemaRevision(revision) : revision == null
+    const validRoot =
+      schemaMode === 'legacy'
+        ? parsed.root == null
+        : parsed.root !== null && parsed.root !== undefined
+    if (!validMode || !validRevision || !validRoot) {
+      return {
+        ok: false,
+        ir: null,
+        root: null,
+        schemaMode: 'unavailable',
+        revision: null,
+        error: { message: 'extractor produced an invalid schema admission envelope' },
+      }
+    }
     return {
       ok: true,
       ir: parsed.ir as SchemaIR,
       root: parsed.root ?? null,
+      schemaMode,
+      revision: revision ?? null,
       importedInterfaces: (parsed.importedInterfaces ?? {}) as Record<string, IrInterface>,
     }
   } catch (e: any) {
-    return { ok: false, ir: null, root: null, error: { message: String(e?.message ?? e) } }
+    return {
+      ok: false,
+      ir: null,
+      root: null,
+      schemaMode: 'unavailable',
+      revision: null,
+      error: { message: String(e?.message ?? e) },
+    }
   }
 }
 

package/studio/server/introspect/schema-ir-json.ts

@@ -0,0 +1,181 @@
+/** Structural admission for persisted Studio render IR. SDK admission is separate. */
+
+import type {
+  IrFunction,
+  IrInterface,
+  IrMethod,
+  IrSchemaRef,
+  JsonSchema,
+  SchemaIR,
+} from '../../shared/types'
+
+import { asJsonRecord, asStringArray } from '../json'
+
+function optional<T>(value: unknown, guard: (candidate: unknown) => candidate is T): boolean {
+  return value === undefined || guard(value)
+}
+
+function recordOf(value: unknown, guard: (candidate: unknown) => boolean): boolean {
+  const record = asJsonRecord(value)
+  return !!record && Object.values(record).every(guard)
+}
+
+function isJsonSchema(value: unknown): value is JsonSchema {
+  return !!asJsonRecord(value)
+}
+
+function isSchemaRef(value: unknown): value is IrSchemaRef {
+  const record = asJsonRecord(value)
+  return (
+    typeof record?.origin === 'string' &&
+    typeof record.name === 'string' &&
+    ['type', 'interface', 'class', 'function', 'policy', 'view', 'core'].includes(
+      String(record.kind),
+    )
+  )
+}
+
+function isSchemaRefArray(value: unknown): value is IrSchemaRef[] {
+  return Array.isArray(value) && value.every(isSchemaRef)
+}
+
+function isOutput(value: unknown): boolean {
+  const record = asJsonRecord(value)
+  if (!record) return false
+  if (record.mode === 'binary') return true
+  if (record.mode === 'value') return isJsonSchema(record.schema)
+  if (record.mode === 'stream') return isJsonSchema(record.item)
+  return false
+}
+
+function isMethod(value: unknown): value is IrMethod {
+  const record = asJsonRecord(value)
+  return (
+    typeof record?.name === 'string' &&
+    recordOf(record.params, isJsonSchema) &&
+    isJsonSchema(record.returns) &&
+    typeof record.static === 'boolean' &&
+    ['default', 'abstract', 'sealed'].includes(String(record.inheritance)) &&
+    optional(record.input, isJsonSchema) &&
+    (record.requiredParams === undefined || asStringArray(record.requiredParams) !== undefined) &&
+    (record.output === undefined || isOutput(record.output))
+  )
+}
+
+function isEndpoint(value: unknown): boolean {
+  const record = asJsonRecord(value)
+  if (!record || typeof record.name !== 'string' || !asStringArray(record.types)) return false
+  if (record.refs !== undefined && !isSchemaRefArray(record.refs)) return false
+  if (record.cardinality !== undefined) {
+    const cardinality = asJsonRecord(record.cardinality)
+    if (
+      !cardinality ||
+      typeof cardinality.min !== 'number' ||
+      !Number.isFinite(cardinality.min) ||
+      (cardinality.max !== null &&
+        (typeof cardinality.max !== 'number' || !Number.isFinite(cardinality.max)))
+    ) {
+      return false
+    }
+  }
+  return true
+}
+
+function isInterface(value: unknown): value is IrInterface {
+  const record = asJsonRecord(value)
+  return (
+    record?.type === 'interface' &&
+    typeof record.name === 'string' &&
+    recordOf(record.properties, isJsonSchema) &&
+    recordOf(record.methods, isMethod) &&
+    (record.required === undefined || asStringArray(record.required) !== undefined) &&
+    (record.extends === undefined || asStringArray(record.extends) !== undefined) &&
+    (record.extendsRefs === undefined || isSchemaRefArray(record.extendsRefs)) &&
+    (record.endpoints === undefined ||
+      (Array.isArray(record.endpoints) && record.endpoints.every(isEndpoint)))
+  )
+}
+
+function isClass(value: unknown): boolean {
+  const record = asJsonRecord(value)
+  return (
+    (record?.type === 'node' || record?.type === 'edge') &&
+    typeof record.name === 'string' &&
+    recordOf(record.properties, isJsonSchema) &&
+    recordOf(record.methods, isMethod) &&
+    (record.required === undefined || asStringArray(record.required) !== undefined) &&
+    (record.implements === undefined || asStringArray(record.implements) !== undefined) &&
+    (record.implementsRefs === undefined || isSchemaRefArray(record.implementsRefs)) &&
+    (record.endpoints === undefined ||
+      (Array.isArray(record.endpoints) && record.endpoints.every(isEndpoint)))
+  )
+}
+
+function isFunction(value: unknown): value is IrFunction {
+  const record = asJsonRecord(value)
+  return (
+    typeof record?.name === 'string' &&
+    isJsonSchema(record.input) &&
+    recordOf(record.params, isJsonSchema) &&
+    (record.requiredParams === undefined || asStringArray(record.requiredParams) !== undefined) &&
+    isOutput(record.output) &&
+    isJsonSchema(record.returns) &&
+    record.static === true &&
+    record.inheritance === 'default'
+  )
+}
+
+function isImport(value: unknown): boolean {
+  const record = asJsonRecord(value)
+  return (
+    typeof record?.origin === 'string' &&
+    (record.definition === 'class' || record.definition === 'interface') &&
+    optional(record.ref, isSchemaRef)
+  )
+}
+
+function isView(value: unknown): boolean {
+  const record = asJsonRecord(value)
+  const target = asJsonRecord(record?.target)
+  return (
+    typeof record?.name === 'string' &&
+    ['required', 'optional', 'public'].includes(String(record.auth)) &&
+    !!target &&
+    (target.kind === 'domain' ||
+      (target.kind === 'definition' && isSchemaRefArray(target.definitions)))
+  )
+}
+
+export function decodeSchemaIR(value: unknown): SchemaIR | undefined {
+  const record = asJsonRecord(value)
+  if (
+    !record ||
+    typeof record.version !== 'string' ||
+    typeof record.domain !== 'string' ||
+    !recordOf(record.types, isJsonSchema) ||
+    !recordOf(record.interfaces, isInterface) ||
+    !recordOf(record.classes, isClass) ||
+    !recordOf(record.imports, isImport) ||
+    !recordOf(record.functions, isFunction) ||
+    (record.importsByKey !== undefined && !recordOf(record.importsByKey, isImport)) ||
+    (record.importedInterfacesByKey !== undefined &&
+      !recordOf(record.importedInterfacesByKey, isInterface)) ||
+    (record.views !== undefined && !recordOf(record.views, isView)) ||
+    (record.policies !== undefined && !asJsonRecord(record.policies)) ||
+    (record.dependencies !== undefined &&
+      (!Array.isArray(record.dependencies) ||
+        !record.dependencies.every((dependency) => {
+          const item = asJsonRecord(dependency)
+          return typeof item?.origin === 'string' && typeof item.revision === 'string'
+        })))
+  ) {
+    return undefined
+  }
+  return record as unknown as SchemaIR
+}
+
+export function decodeIrInterfaceRecord(value: unknown): Record<string, IrInterface> | undefined {
+  const record = asJsonRecord(value)
+  if (!record || !Object.values(record).every(isInterface)) return undefined
+  return record as unknown as Record<string, IrInterface>
+}

package/studio/server/introspect/source-overlay/annotations.ts

@@ -0,0 +1,14 @@
+/**
+ * Compatibility owner for Studio schema annotations.
+ *
+ * The current Kernel admits enum updates against their exact Value Schema, so
+ * there are no source-derived annotations today. The serialized overlay field
+ * remains consumed by the client and shared contract.
+ */
+import type { SchemaAnnotation, SchemaIR } from '../../../shared/types'
+
+export function buildSchemaAnnotations(_args: { ir: SchemaIR | null }): SchemaAnnotation[] {
+  // The current Kernel admits updated values against their exact Value Schema;
+  // enum properties therefore need no Studio-specific compatibility warning.
+  return []
+}