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

package/studio/server/cache.test.ts

@@ -0,0 +1,122 @@
+import { expect, test } from 'bun:test'
+
+import { decodeBundleCacheEntry } from './cache'
+
+function entry(): Record<string, unknown> {
+  return {
+    version: 5,
+    key: 'cache-key',
+    futureEntryField: { version: 5 },
+    bundle: {
+      domainId: 'notes',
+      renderFingerprint: 'render-hash',
+      schemaMode: 'canonical-preview',
+      extractedBy: 'runtime-bun',
+      depsInstalled: true,
+      ir: {
+        format: 'astrale.dsl',
+        version: 'v1',
+        domain: 'notes.example.dev',
+        classes: {},
+        importsByKey: {},
+        importedClassesByKey: {},
+        functions: {},
+        views: {},
+        policies: {},
+        dependencies: [],
+        core: {},
+      },
+      overlay: {
+        origin: 'notes.example.dev',
+        requires: [],
+        crossDomainImports: [],
+        mixins: [],
+        handlerLinks: [],
+        sourceSpans: {},
+        annotations: [],
+      },
+      schemaRoot: {
+        format: 'astrale.dsl',
+        version: 'v1',
+        origin: 'notes.example.dev',
+      },
+      error: null,
+      extractedAt: '2026-08-20T00:00:00.000Z',
+      futureBundleField: true,
+    },
+  }
+}
+
+test('bundle cache admits known structure while ignoring future fields', () => {
+  const decoded = decodeBundleCacheEntry(entry())
+
+  expect(decoded).toMatchObject({
+    version: 5,
+    key: 'cache-key',
+    bundle: { domainId: 'notes', schemaMode: 'canonical-preview' },
+  })
+  expect(decoded && 'futureEntryField' in decoded).toBe(false)
+  expect(decoded && 'futureBundleField' in decoded.bundle).toBe(false)
+})
+
+function canonicalEntry(): Record<string, unknown> {
+  const value = entry()
+  const bundle = value.bundle as Record<string, unknown>
+  bundle.schemaMode = 'canonical-admitted'
+  bundle.schemaRevision = `sha256:${'a'.repeat(64)}`
+  bundle.ir = {
+    format: 'astrale.dsl',
+    version: 'v1',
+    domain: 'notes.example.dev',
+    classes: {},
+    importsByKey: {},
+    importedClassesByKey: {},
+    functions: {},
+    views: {},
+    policies: {},
+    dependencies: [],
+    core: {},
+  }
+  bundle.schemaRoot = {
+    format: 'astrale.dsl',
+    version: 'v1',
+    origin: 'notes.example.dev',
+  }
+  return value
+}
+
+test('canonical-admitted cache entries require their root and a valid revision', () => {
+  expect(decodeBundleCacheEntry(canonicalEntry())).toBeDefined()
+
+  const missingRoot = canonicalEntry()
+  delete (missingRoot.bundle as Record<string, unknown>).schemaRoot
+  expect(decodeBundleCacheEntry(missingRoot)).toBeUndefined()
+
+  const invalidRoot = canonicalEntry()
+  const invalidRootBundle = invalidRoot.bundle as Record<string, unknown>
+  invalidRootBundle.schemaRoot = { canonical: true }
+  expect(decodeBundleCacheEntry(invalidRoot)).toBeUndefined()
+
+  const missingRevision = canonicalEntry()
+  delete (missingRevision.bundle as Record<string, unknown>).schemaRevision
+  expect(decodeBundleCacheEntry(missingRevision)).toBeUndefined()
+
+  const invalidRevision = canonicalEntry()
+  const invalidRevisionBundle = invalidRevision.bundle as Record<string, unknown>
+  invalidRevisionBundle.schemaRevision = 'sha256:not-a-revision'
+  expect(decodeBundleCacheEntry(invalidRevision)).toBeUndefined()
+})
+
+test('bundle cache rejects corrupt nested business shapes', () => {
+  const corruptIr = entry()
+  const bundle = corruptIr.bundle as Record<string, unknown>
+  const ir = bundle.ir as Record<string, unknown>
+  ir.classes = { Broken: null }
+  expect(decodeBundleCacheEntry(corruptIr)).toBeUndefined()
+
+  const corruptOverlay = entry()
+  const secondBundle = corruptOverlay.bundle as Record<string, unknown>
+  const overlay = secondBundle.overlay as Record<string, unknown>
+  overlay.handlerLinks = [{ owner: 'Thing' }]
+  expect(decodeBundleCacheEntry(corruptOverlay)).toBeUndefined()
+})

package/studio/server/cache.ts

@@ -7,13 +7,17 @@ import { createHash } from 'node:crypto'
 import { existsSync, readFileSync } from 'node:fs'
 import { join, relative } from 'node:path'
 
-import type { DomainAnatomy, StudioCore, StudioSchemaBundle } from '../shared/types'
+import type { DomainAnatomy, SchemaOverlay, StudioCore, StudioSchemaBundle } from '../shared/types'
 
+import { isSchemaRevision } from '../shared/types'
 import { invalidateClientPackage, resolveClientPackage } from './client-package'
 import { getDomain } from './domain'
 import { buildAnatomy } from './introspect/anatomy'
 import { buildBundle } from './introspect/bundle'
+import { isCanonicalDomainSchemaV1 } from './introspect/canonical-schema'
 import { buildCore } from './introspect/core'
+import { decodeSchemaIR } from './introspect/schema-ir-json'
+import { asBoolean, asFiniteNumber, asJsonRecord, asString, asStringArray } from './json'
 import { hashAnatomyFiles } from './state/baseline'
 import { readJson, writeJson } from './state/store'
 
@@ -22,7 +26,7 @@ const anatomies = new Map<string, Promise<DomainAnatomy>>()
 const cores = new Map<string, StudioCore>()
 
 const BUNDLE_CACHE_FILE = '.cache/schema-bundle.json'
-const BUNDLE_CACHE_VERSION = 3
+const BUNDLE_CACHE_VERSION = 5
 const LOCKFILES = ['bun.lock', 'pnpm-lock.yaml', 'package-lock.json', 'yarn.lock']
 const TOOL_INPUTS = [
   'cache.ts',
@@ -33,6 +37,11 @@ const TOOL_INPUTS = [
   'introspect/canonical-schema.ts',
   'introspect/overlay.ts',
   'introspect/overlay-tsmorph.ts',
+  'introspect/source-overlay/annotations.ts',
+  'introspect/source-overlay/handlers.ts',
+  'introspect/source-overlay/kernel-calls.ts',
+  'introspect/source-overlay/project.ts',
+  'introspect/source-overlay/spans.ts',
   'introspect/hash.ts',
   'state/baseline.ts',
   '../shared/types.ts',
@@ -44,6 +53,147 @@ interface BundleCacheEntry {
   bundle: StudioSchemaBundle
 }
 
+function isCrossDomainImport(value: unknown): boolean {
+  const record = asJsonRecord(value)
+  const ref = asJsonRecord(record?.ref)
+  return (
+    typeof record?.name === 'string' &&
+    typeof record.origin === 'string' &&
+    ref?.kind === 'class' &&
+    typeof ref.origin === 'string' &&
+    typeof ref.name === 'string'
+  )
+}
+
+function isHandlerLink(value: unknown): boolean {
+  const record = asJsonRecord(value)
+  return (
+    typeof record?.owner === 'string' &&
+    ['class', 'function'].includes(String(record.ownerKind)) &&
+    ['action', 'workflow'].includes(String(record.kind)) &&
+    typeof record.method === 'string' &&
+    typeof record.static === 'boolean' &&
+    typeof record.implemented === 'boolean'
+  )
+}
+
+function isSourceSpan(value: unknown): boolean {
+  const record = asJsonRecord(value)
+  return (
+    typeof record?.file === 'string' &&
+    asFiniteNumber(record.startLine) !== undefined &&
+    asFiniteNumber(record.endLine) !== undefined &&
+    (record.doc === undefined || typeof record.doc === 'string')
+  )
+}
+
+function isAnnotation(value: unknown): boolean {
+  const record = asJsonRecord(value)
+  return (
+    typeof record?.target === 'string' &&
+    (record.severity === 'warn' || record.severity === 'info') &&
+    (record.code === 'COMPILE_ERROR' || record.code === 'EDGE_PROP_TYPE_MISSING') &&
+    typeof record.message === 'string'
+  )
+}
+
+function decodeOverlay(value: unknown): SchemaOverlay | undefined {
+  const record = asJsonRecord(value)
+  const requires = asStringArray(record?.requires)
+  const crossDomainImports = record?.crossDomainImports
+  const mixins = record?.mixins
+  const handlerLinks = record?.handlerLinks
+  const sourceSpans = asJsonRecord(record?.sourceSpans)
+  const annotations = record?.annotations
+  if (
+    typeof record?.origin !== 'string' ||
+    !requires ||
+    !Array.isArray(crossDomainImports) ||
+    !crossDomainImports.every(isCrossDomainImport) ||
+    !Array.isArray(mixins) ||
+    !mixins.every(isCrossDomainImport) ||
+    !Array.isArray(handlerLinks) ||
+    !handlerLinks.every(isHandlerLink) ||
+    !sourceSpans ||
+    !Object.values(sourceSpans).every(isSourceSpan) ||
+    !Array.isArray(annotations) ||
+    !annotations.every(isAnnotation)
+  ) {
+    return undefined
+  }
+  return record as unknown as SchemaOverlay
+}
+
+function decodeBundle(value: unknown): StudioSchemaBundle | undefined {
+  const record = asJsonRecord(value)
+  if (!record) return undefined
+  const domainId = asString(record.domainId)
+  const renderFingerprint = asString(record.renderFingerprint)
+  const schemaMode = (['canonical-admitted', 'canonical-preview', 'unavailable'] as const).find(
+    (candidate) => candidate === record.schemaMode,
+  )
+  const extractedBy = record.extractedBy
+  const depsInstalled = asBoolean(record.depsInstalled)
+  const ir = record.ir === null ? null : decodeSchemaIR(record.ir)
+  const overlay = decodeOverlay(record.overlay)
+  const extractedAt = asString(record.extractedAt)
+  if (
+    !domainId ||
+    renderFingerprint === undefined ||
+    !schemaMode ||
+    (extractedBy !== 'runtime-bun' && extractedBy !== 'static-tsmorph-fallback') ||
+    depsInstalled === undefined ||
+    ir === undefined ||
+    !overlay ||
+    !extractedAt
+  ) {
+    return undefined
+  }
+  const schemaRevision = record.schemaRevision
+  if (schemaRevision !== undefined && !isSchemaRevision(schemaRevision)) return undefined
+  if (
+    schemaMode === 'canonical-admitted' &&
+    (!isSchemaRevision(schemaRevision) || !isCanonicalDomainSchemaV1(record.schemaRoot))
+  ) {
+    return undefined
+  }
+  const errorRecord = record.error === null ? null : asJsonRecord(record.error)
+  const errorMessage = asString(errorRecord?.message)
+  if (record.error !== undefined && record.error !== null && errorMessage === undefined) {
+    return undefined
+  }
+  return {
+    domainId,
+    renderFingerprint,
+    schemaMode,
+    ...(schemaRevision === undefined ? {} : { schemaRevision }),
+    extractedBy,
+    depsInstalled,
+    ir,
+    ...(record.schemaRoot === undefined ? {} : { schemaRoot: record.schemaRoot }),
+    overlay,
+    ...(record.error === undefined
+      ? {}
+      : record.error === null
+        ? { error: null }
+        : {
+            error: {
+              message: errorMessage!,
+              ...(typeof errorRecord!.file === 'string' ? { file: errorRecord!.file } : {}),
+            },
+          }),
+    extractedAt,
+  }
+}
+
+export function decodeBundleCacheEntry(value: unknown): BundleCacheEntry | undefined {
+  const record = asJsonRecord(value)
+  const version = asFiniteNumber(record?.version)
+  const key = asString(record?.key)
+  const bundle = decodeBundle(record?.bundle)
+  return version !== undefined && key !== undefined && bundle ? { version, key, bundle } : undefined
+}
+
 function hashFileIfPresent(hash: ReturnType<typeof createHash>, label: string, file: string): void {
   try {
     if (!existsSync(file)) return
@@ -77,7 +227,7 @@ function bundleCacheKey(root: string, schemaDirName: string): string {
 }
 
 function readCachedBundle(root: string, key: string): StudioSchemaBundle | null {
-  const entry = readJson<BundleCacheEntry | null>(root, BUNDLE_CACHE_FILE, null)
+  const entry = readJson(root, BUNDLE_CACHE_FILE, decodeBundleCacheEntry, null)
   if (!entry || entry.version !== BUNDLE_CACHE_VERSION || entry.key !== key || !entry.bundle)
     return null
   return entry.bundle
@@ -119,12 +269,14 @@ export async function getAnatomy(id: string, rebuild = false): Promise<DomainAna
   const h = getDomain(id)
   if (!h) return null
   if (!rebuild && anatomies.has(id)) return anatomies.get(id)!
-  const anatomy = resolveClientPackage(h.root, rebuild).then((client) =>
-    buildAnatomy({
-      root: h.root,
-      schemaDirName: h.schemaDirName,
-      clientDir: client.status === 'available' ? client.sourceDir : undefined,
-    }),
+  const anatomy = Promise.all([resolveClientPackage(h.root, rebuild), getBundle(id, rebuild)]).then(
+    ([client, bundle]) =>
+      buildAnatomy({
+        root: h.root,
+        schemaDirName: h.schemaDirName,
+        clientDir: client.status === 'available' ? client.sourceDir : undefined,
+        canonicalViews: bundle?.ir?.format === 'astrale.dsl' ? (bundle.ir.views ?? {}) : undefined,
+      }),
   )
   anatomies.set(id, anatomy)
   return anatomy
@@ -146,7 +298,6 @@ export function invalidate(id: string, what: 'schema' | 'anatomy' | 'all'): void
     const domain = getDomain(id)
     if (domain) invalidateClientPackage(domain.root)
   }
-  // Core is derived from the canonical schema (or the legacy composition entry),
-  // both of which belong to the anatomy invalidation set.
+  // Core is derived from the canonical Schema and belongs to the anatomy set.
   if (what !== 'schema') cores.delete(id)
 }