@astrale-os/cli 1.0.0-beta.32 → 1.0.0-beta.43

package/studio/server/domain.test.ts

@@ -31,13 +31,19 @@ function fixture(nested = false): string {
       ? "import application from './domain/application.js'\nexport default { application }\n"
       : 'export default {}\n',
   )
-  writeFileSync(join(owner, 'application.ts'), 'export default {}\n')
   writeFileSync(join(owner, 'schema/index.ts'), 'export const schema = {}\n')
+  writeFileSync(
+    join(owner, 'application.ts'),
+    `import { defineApplication } from '@astrale-os/sdk/application'
+import { schema } from './schema/index.js'
+export default defineApplication({ schema, runtime: {} as never })
+`,
+  )
   return root
 }
 
 describe('SDK V1 project discovery', () => {
-  test('discovers conventional root Application and Schema entries', () => {
+  test('discovers the Schema selected by the conventional root Application', () => {
     const root = fixture()
     expect(isDomainDir(root)).toBe(true)
     expect(basename(resolveApplicationEntry(root)!)).toBe('application.ts')
@@ -48,13 +54,87 @@ describe('SDK V1 project discovery', () => {
     expect(handle.schemaDirName).toBe('schema')
   })
 
-  test('follows a config-imported nested Application and adjacent Schema', () => {
+  test('follows a config-imported nested Application and its Schema binding', () => {
     const root = fixture(true)
     const application = resolveApplicationEntry(root)!
     expect(application).toBe(join(root, 'domain/application.ts'))
     expect(resolveSchemaEntry(root, application)).toBe(join(root, 'domain/schema/index.ts'))
   })
 
+  test('uses Application.schema instead of guessing a conventional Schema path', () => {
+    const root = mkdtempSync(join(tmpdir(), 'studio-application-source-of-truth-'))
+    roots.push(root)
+    mkdirSync(join(root, 'model'), { recursive: true })
+    mkdirSync(join(root, 'schema'), { recursive: true })
+    writeFileSync(join(root, 'astrale.config.ts'), 'export default {}\n')
+    writeFileSync(join(root, 'schema/index.ts'), 'export const decoy = {}\n')
+    writeFileSync(join(root, 'model/domain-definition.ts'), 'export const selected = {}\n')
+    writeFileSync(
+      join(root, 'application.ts'),
+      `import { defineApplication as compose } from '@astrale-os/sdk/application'
+import * as definitions from './model/domain-definition.js'
+export default compose({ schema: definitions.selected, runtime: {} as never })
+`,
+    )
+
+    const application = resolveApplicationEntry(root)!
+    expect(resolveSchemaEntry(root, application)).toBe(join(root, 'model/domain-definition.ts'))
+    const handle = registerDomain(root)!
+    domainIds.push(handle.id)
+    expect(handle.schemaDirName).toBe('model')
+  })
+
+  test('resolves an extensionless Schema directory import to its authored index', () => {
+    const root = mkdtempSync(join(tmpdir(), 'studio-extensionless-schema-'))
+    roots.push(root)
+    mkdirSync(join(root, 'definition'))
+    writeFileSync(join(root, 'astrale.config.ts'), 'export default {}\n')
+    writeFileSync(join(root, 'definition/index.ts'), 'export default {}\n')
+    writeFileSync(
+      join(root, 'application.ts'),
+      `import { defineApplication } from '@astrale-os/sdk/application'
+import schema from './definition'
+export default defineApplication({ schema, runtime: {} as never })
+`,
+    )
+
+    expect(resolveSchemaEntry(root, join(root, 'application.ts'))).toBe(
+      join(root, 'definition/index.ts'),
+    )
+  })
+
+  test('rejects a conventional Schema that is not selected by Application', () => {
+    const root = mkdtempSync(join(tmpdir(), 'studio-unbound-schema-'))
+    roots.push(root)
+    mkdirSync(join(root, 'schema'))
+    writeFileSync(join(root, 'astrale.config.ts'), 'export default {}\n')
+    writeFileSync(join(root, 'application.ts'), 'export default {}\n')
+    writeFileSync(join(root, 'schema/index.ts'), 'export const schema = {}\n')
+    expect(isDomainDir(root)).toBe(false)
+  })
+
+  test('preserves a stable handle and replaces it when Application selects another Schema', () => {
+    const root = fixture()
+    const first = registerDomain(root)!
+    domainIds.push(first.id)
+    expect(registerDomain(root)).toBe(first)
+
+    mkdirSync(join(root, 'model'))
+    writeFileSync(join(root, 'model/replacement.ts'), 'export const replacement = {}\n')
+    writeFileSync(
+      join(root, 'application.ts'),
+      `import { defineApplication } from '@astrale-os/sdk/application'
+import { replacement } from './model/replacement.js'
+export default defineApplication({ schema: replacement, runtime: {} as never })
+`,
+    )
+
+    const moved = registerDomain(root)!
+    expect(moved).not.toBe(first)
+    expect(moved.schemaIndex).toBe(join(root, 'model/replacement.ts'))
+    expect(moved.schemaDirName).toBe('model')
+  })
+
   test('requires the semantic SDK dependency, not Kernel implementation packages', () => {
     const root = fixture()
     expect(depsInstalled(root)).toBe(false)

package/studio/server/domain.ts

@@ -1,6 +1,14 @@
 /** SDK V1 project discovery and the in-process Studio registry. */
-import { existsSync, readFileSync } from 'node:fs'
-import { basename, dirname, extname, join, relative, resolve } from 'node:path'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from 'node:path'
+import {
+  Node,
+  Project,
+  SyntaxKind,
+  type CallExpression,
+  type ObjectLiteralExpression,
+  type SourceFile,
+} from 'ts-morph'
 
 export interface DomainHandle {
   readonly id: string
@@ -46,35 +54,43 @@ export function resolveApplicationEntry(root: string): string | null {
   return null
 }
 
-/** Resolve schema.ts or schema/index.ts beside the Application, then at project root. */
-export function resolveSchemaEntry(
-  root: string,
-  applicationFile: string,
-  schemaDirName = 'schema',
-): string | null {
+/**
+ * Resolve the authored Schema module selected by `defineApplication({ schema })`.
+ *
+ * Application is the composition source of truth, but importing it would also load
+ * Runtime, Frontend, integrations, and any authored top-level effects. Studio follows
+ * the Schema binding statically instead, then imports only that module in its isolated
+ * extractor subprocess.
+ */
+export function resolveSchemaEntry(root: string, applicationFile: string): string | null {
   const project = resolve(root)
-  const applicationDir = dirname(applicationFile)
-  const candidates = [
-    join(applicationDir, 'schema.ts'),
-    join(applicationDir, schemaDirName, 'index.ts'),
-    join(project, 'schema.ts'),
-    join(project, schemaDirName, 'index.ts'),
-  ]
-  return [...new Set(candidates)].find(existsSync) ?? null
+  const source = addSourceFile(applicationFile)
+  if (source === null) return null
+
+  for (const call of source.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    if (!isDefineApplicationCall(call, source)) continue
+    const input = resolveLocalValue(call.getArguments()[0], source)
+    if (!input || !Node.isObjectLiteralExpression(input)) continue
+    const schema = objectPropertyValue(input, 'schema')
+    if (!schema) continue
+    const selected = schemaModuleOf(schema, source, project)
+    if (selected !== null) return selected
+  }
+  return null
 }
 
-export function isDomainDir(root: string, schemaDirName = 'schema'): boolean {
+export function isDomainDir(root: string): boolean {
   const project = resolve(root)
   if (!existsSync(join(project, 'astrale.config.ts'))) return false
   const application = resolveApplicationEntry(project)
-  return application !== null && resolveSchemaEntry(project, application, schemaDirName) !== null
+  return application !== null && resolveSchemaEntry(project, application) !== null
 }
 
-export function registerDomain(root: string, schemaDirName = 'schema'): DomainHandle | null {
+export function registerDomain(root: string): DomainHandle | null {
   const project = resolve(root)
   const applicationFile = resolveApplicationEntry(project)
   if (applicationFile === null || !existsSync(join(project, 'astrale.config.ts'))) return null
-  const schemaIndex = resolveSchemaEntry(project, applicationFile, schemaDirName)
+  const schemaIndex = resolveSchemaEntry(project, applicationFile)
   if (schemaIndex === null) return null
   const schemaDir = dirname(schemaIndex)
   const handle: DomainHandle = {
@@ -86,6 +102,15 @@ export function registerDomain(root: string, schemaDirName = 'schema'): DomainHa
     schemaDir,
     schemaIndex,
   }
+  const current = registry.get(handle.id)
+  if (
+    current?.root === handle.root &&
+    current.configFile === handle.configFile &&
+    current.applicationFile === handle.applicationFile &&
+    current.schemaIndex === handle.schemaIndex
+  ) {
+    return current
+  }
   registry.set(handle.id, handle)
   return handle
 }
@@ -114,11 +139,164 @@ export function depsInstalled(root: string): boolean {
 }
 
 function resolveSourceFile(root: string, specifier: string): string | null {
-  const absolute = resolve(root, specifier)
-  const extension = extname(absolute)
-  const candidates =
-    extension === ''
-      ? [`${absolute}.ts`, join(absolute, 'index.ts')]
-      : [absolute, `${absolute.slice(0, -extension.length)}.ts`]
-  return candidates.find(existsSync) ?? null
+  return sourceCandidates(resolve(root, specifier)).find(isFile) ?? null
+}
+
+function addSourceFile(file: string): SourceFile | null {
+  try {
+    const project = new Project({
+      useInMemoryFileSystem: false,
+      skipAddingFilesFromTsConfig: true,
+      skipFileDependencyResolution: true,
+      skipLoadingLibFiles: true,
+      compilerOptions: { allowJs: true, allowImportingTsExtensions: true },
+    })
+    return project.addSourceFileAtPath(file)
+  } catch {
+    return null
+  }
+}
+
+function unwrap(node: Node): Node {
+  let current = node
+  while (
+    Node.isAsExpression(current) ||
+    Node.isSatisfiesExpression(current) ||
+    Node.isParenthesizedExpression(current) ||
+    Node.isTypeAssertion(current) ||
+    Node.isNonNullExpression(current)
+  ) {
+    current = current.getExpression()
+  }
+  return current
+}
+
+function resolveLocalValue(
+  node: Node | undefined,
+  source: SourceFile,
+  seen = new Set<string>(),
+): Node | null {
+  if (!node) return null
+  const value = unwrap(node)
+  if (!Node.isIdentifier(value)) return value
+  const key = `${source.getFilePath()}:${value.getText()}`
+  if (seen.has(key)) return value
+  seen.add(key)
+  const initializer = source.getVariableDeclaration(value.getText())?.getInitializer()
+  return initializer ? resolveLocalValue(initializer, source, seen) : value
+}
+
+function isDefineApplicationCall(call: CallExpression, source: SourceFile): boolean {
+  const expression = call.getExpression()
+  if (Node.isIdentifier(expression)) {
+    const localName = expression.getText()
+    return source
+      .getImportDeclarations()
+      .some(
+        (declaration) =>
+          declaration.getModuleSpecifierValue() === '@astrale-os/sdk/application' &&
+          declaration
+            .getNamedImports()
+            .some(
+              (named) =>
+                named.getName() === 'defineApplication' &&
+                (named.getAliasNode()?.getText() ?? named.getName()) === localName,
+            ),
+      )
+  }
+  if (
+    !Node.isPropertyAccessExpression(expression) ||
+    expression.getName() !== 'defineApplication'
+  ) {
+    return false
+  }
+  const namespace = expression.getExpression()
+  if (!Node.isIdentifier(namespace)) return false
+  return source
+    .getImportDeclarations()
+    .some(
+      (declaration) =>
+        declaration.getModuleSpecifierValue() === '@astrale-os/sdk/application' &&
+        declaration.getNamespaceImport()?.getText() === namespace.getText(),
+    )
+}
+
+function objectPropertyValue(object: ObjectLiteralExpression, name: string) {
+  const property = object.getProperty(name)
+  if (property && Node.isPropertyAssignment(property)) return property.getInitializer()
+  if (property && Node.isShorthandPropertyAssignment(property)) return property.getNameNode()
+  return undefined
+}
+
+function schemaModuleOf(node: Node, source: SourceFile, root: string): string | null {
+  const value = unwrap(node)
+  if (Node.isIdentifier(value)) {
+    const initializer = source.getVariableDeclaration(value.getText())?.getInitializer()
+    if (initializer) return schemaModuleOf(initializer, source, root)
+    for (const declaration of source.getImportDeclarations()) {
+      const imported = declaration
+        .getNamedImports()
+        .some((named) => (named.getAliasNode()?.getText() ?? named.getName()) === value.getText())
+      const defaultImported = declaration.getDefaultImport()?.getText() === value.getText()
+      if (imported || defaultImported) {
+        return resolveAuthoredModule(root, source, declaration.getModuleSpecifierValue())
+      }
+    }
+    return null
+  }
+  if (Node.isPropertyAccessExpression(value) && Node.isIdentifier(value.getExpression())) {
+    const namespace = value.getExpression().getText()
+    for (const declaration of source.getImportDeclarations()) {
+      if (declaration.getNamespaceImport()?.getText() === namespace) {
+        return resolveAuthoredModule(root, source, declaration.getModuleSpecifierValue())
+      }
+    }
+  }
+  return null
+}
+
+function resolveAuthoredModule(root: string, from: SourceFile, specifier: string): string | null {
+  let candidates: string[] = []
+  if (specifier.startsWith('.')) {
+    candidates = sourceCandidates(resolve(dirname(from.getFilePath()), specifier))
+  } else if (specifier.startsWith('#')) {
+    try {
+      candidates = sourceCandidates(Bun.resolveSync(specifier, dirname(from.getFilePath())))
+    } catch {
+      return null
+    }
+  } else {
+    return null
+  }
+  for (const candidate of candidates) {
+    if (!isFile(candidate)) continue
+    const rel = relative(root, candidate)
+    if (rel === '..' || rel.startsWith('../') || rel.startsWith('..\\') || isAbsolute(rel)) {
+      continue
+    }
+    return candidate
+  }
+  return null
+}
+
+function sourceCandidates(file: string): string[] {
+  const extension = extname(file)
+  const sourceBase = /\.[cm]?jsx?$/u.test(extension) ? file.slice(0, -extension.length) : file
+  return [
+    file,
+    `${sourceBase}.ts`,
+    `${sourceBase}.tsx`,
+    `${sourceBase}.mts`,
+    `${sourceBase}.cts`,
+    join(file, 'index.ts'),
+    join(file, 'index.tsx'),
+  ]
+}
+
+function isFile(file: string): boolean {
+  try {
+    return statSync(file).isFile()
+  } catch {
+    return false
+  }
 }

package/studio/server/handoff/service.ts

@@ -16,7 +16,7 @@ import { detectGit, gitDiff } from '../workspace/git'
 /** Current changes vs the review baseline (schema IR diff + anatomy file diff). */
 export async function changeSet(handle: DomainHandle): Promise<ChangeSet> {
   const bundle = await getBundle(handle.id)
-  const files = hashAnatomyFiles(handle.root, handle.schemaDirName)
+  const files = hashAnatomyFiles(handle.root, handle.schemaDirName, handle.applicationFile)
   const { hasGit } = detectGit(handle.root)
   const diffText = hasGit ? gitDiff(handle.root, handle.schemaDirName) : null
   return computeChanges(handle.root, bundle?.ir ?? null, files, {

package/studio/server/index.ts

@@ -2,7 +2,7 @@
 /**
  * index.ts — the Domain Studio server entrypoint.
  *
- *   bun server/index.ts [path | --workspace dir] [--port n] [--schema-dir schema] [--open]
+ *   bun server/index.ts [path | --workspace dir] [--port n] [--open]
  *
  * `path` may be an astrale.config.ts, a domain dir, or a workspace to scan.
  * Boots a Bun HTTP server: serves the built SPA, the JSON API, and the SSE
@@ -23,14 +23,12 @@ import { watchWorkspace } from './workspace-watch'
 const argv = process.argv.slice(2)
 let target = ''
 let port = Number(process.env.PORT) || 4319
-let schemaDir = 'schema'
 // Default OFF — printing the URL is enough; popping a browser is invasive. The CLI
 // owns browser-opening (its own --open), and always passes --no-open here.
 let open = false
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i]
   if (a === '--port') port = Number(argv[++i])
-  else if (a === '--schema-dir') schemaDir = argv[++i]
   else if (a === '--open') open = true
   else if (a === '--no-open') open = false
   else if (a === '--workspace') target = argv[++i]
@@ -38,11 +36,11 @@ for (let i = 0; i < argv.length; i++) {
 }
 if (!target) target = process.cwd()
 
-const domains = resolveTarget(target, schemaDir)
+const domains = resolveTarget(target)
 if (!domains.length) {
   console.error(`\n  ✗ No Astrale domains found at ${target}`)
   console.error(
-    `    (looking for: astrale.config.ts + application.ts + schema.ts or ${schemaDir}/index.ts)\n`,
+    '    (looking for: astrale.config.ts + an Application whose schema binding resolves to authored source)\n',
   )
   process.exit(1)
 }
@@ -56,9 +54,8 @@ for (const h of domains) {
 
 // keep the registry in sync with the workspace — pick up domains added/removed at runtime
 const watchRoot = target.endsWith('astrale.config.ts') ? dirname(resolve(target)) : resolve(target)
-initWorkspaceState(watchRoot, schemaDir) // where `create new` scaffolds + the create endpoint reads
-if (existsSync(watchRoot) && statSync(watchRoot).isDirectory())
-  watchWorkspace(watchRoot, schemaDir, stoppers)
+initWorkspaceState(watchRoot) // where `create new` scaffolds + the create endpoint reads
+if (existsSync(watchRoot) && statSync(watchRoot).isDirectory()) watchWorkspace(watchRoot, stoppers)
 
 const DIST = process.env.DOMAIN_STUDIO_DIST || join(import.meta.dir, '..', 'client', 'dist')
 const DEV = process.env.DOMAIN_STUDIO_DEV === '1'

package/studio/server/introspect/extractor.ts

@@ -1,4 +1,11 @@
 /** Bun subprocess that imports only the authored Schema entry and its installed SDK. */
+import { existsSync } from 'node:fs'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
 import type { SchemaSdk } from './canonical-schema'
 
 import { extractCanonicalSchemaFromSdk, findCanonicalDomainSchemaExport } from './canonical-schema'
@@ -6,26 +13,113 @@ import { extractCanonicalSchemaFromSdk, findCanonicalDomainSchemaExport } from '
 const schemaPath = process.argv[2]
 const projectRoot = process.argv[3] ?? process.cwd()
 
+async function installedSdkSchema(root: string): Promise<string> {
+  let directory = root
+  for (;;) {
+    const packageRoot = join(directory, 'node_modules', '@astrale-os', 'sdk')
+    const manifestPath = join(packageRoot, 'package.json')
+    if (existsSync(manifestPath)) {
+      const manifest = JSON.parse(await readFile(manifestPath, 'utf8')) as {
+        exports?: Record<string, string | { import?: string; default?: string; types?: string }>
+      }
+      const exported = manifest.exports?.['./schema']
+      const target =
+        typeof exported === 'string'
+          ? exported
+          : (exported?.import ?? exported?.default ?? exported?.types)
+      if (target) return join(packageRoot, target)
+      throw new Error(`${manifestPath} does not export @astrale-os/sdk/schema`)
+    }
+    const parent = dirname(directory)
+    if (parent === directory) break
+    directory = parent
+  }
+  throw new Error(`Cannot find @astrale-os/sdk from ${root}`)
+}
+
+function buildFailure(cause: unknown): Error {
+  if (cause && typeof cause === 'object') {
+    const errors = (cause as { errors?: unknown[] }).errors
+    if (Array.isArray(errors) && errors.length > 0) {
+      const details = errors
+        .map((entry) => (entry instanceof Error ? entry.message : String(entry)))
+        .join('\n')
+      return new Error(details, { cause })
+    }
+  }
+  return cause instanceof Error ? cause : new Error(String(cause))
+}
+
 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.')
+  const temporary = await mkdtemp(join(tmpdir(), 'astrale-studio-extractor-'))
+  try {
+    // A compiled Bun executable cannot resolve package imports from a dynamic,
+    // external TypeScript entrypoint. Build one short-lived island rooted at the
+    // Domain instead: Bun resolves and bundles the authored Schema plus that
+    // Domain's exact SDK, then the standalone extractor imports the result.
+    const sdkPath = await installedSdkSchema(projectRoot)
+    const wrapper = join(temporary, 'entry.ts')
+    await writeFile(
+      wrapper,
+      `import * as authored from ${JSON.stringify(schemaPath)};\n` +
+        `import * as sdk from ${JSON.stringify(sdkPath)};\n` +
+        `export { authored, sdk };\n`,
+    )
+    const built = await Bun.build({
+      entrypoints: [wrapper],
+      outdir: temporary,
+      target: 'bun',
+      format: 'cjs',
+      packages: 'bundle',
+    }).catch((cause: unknown) => {
+      throw buildFailure(cause)
+    })
+    if (!built.success) {
+      const details = built.logs
+        .map((log) => {
+          const position = log.position
+          const location = position ? `${position.file}:${position.line}:${position.column}: ` : ''
+          return `${location}${log.message}`
+        })
+        .join('\n')
+      throw new Error(details || 'schema bundle failed')
+    }
+    const output = built.outputs.find((candidate) => candidate.kind === 'entry-point')
+    if (!output) throw new Error('schema bundle produced no entrypoint')
+    const source = await output.text()
+    const module = { exports: {} as Record<string, unknown> }
+    const require = createRequire(pathToFileURL(join(projectRoot, 'package.json')))
+    const factory = new Function(`return (\n${source}\n);`)() as (
+      exports: Record<string, unknown>,
+      require: NodeRequire,
+      module: { exports: Record<string, unknown> },
+      filename: string,
+      directory: string,
+    ) => void
+    factory(module.exports, require, module, output.path, dirname(output.path))
+    const island = module.exports as {
+      authored: Record<string, unknown>
+      sdk: SchemaSdk
+    }
+    if (!island?.authored || !island?.sdk) {
+      throw new Error(`schema bundle exports are invalid (${Object.keys(island ?? {}).join(', ')})`)
+    }
+    const candidate = findCanonicalDomainSchemaExport(island.authored)
+    if (candidate === null) throw new Error('Schema entry exports no canonical V1 DomainSchema.')
+    const extraction = extractCanonicalSchemaFromSdk(island.sdk, candidate)
+    process.stdout.write(
+      JSON.stringify({
+        ok: true,
+        ir: extraction.ir,
+        root: extraction.root,
+        schemaMode: extraction.status === 'admitted' ? 'canonical-admitted' : 'canonical-preview',
+        revision: extraction.revision,
+      }),
+    )
+  } finally {
+    await rm(temporary, { recursive: true, force: true })
   }
-  const sdk = (await import(
-    Bun.resolveSync('@astrale-os/sdk/schema', projectRoot)
-  )) as unknown as SchemaSdk
-  const extraction = extractCanonicalSchemaFromSdk(sdk, candidate)
-  process.stdout.write(
-    JSON.stringify({
-      ok: true,
-      ir: extraction.ir,
-      root: extraction.root,
-      schemaMode: extraction.status === 'admitted' ? 'canonical-admitted' : 'canonical-preview',
-      revision: extraction.revision,
-    }),
-  )
 }
 
 main().catch((cause: unknown) => {

package/studio/server/introspect/overlay-tsmorph.test.ts

@@ -104,8 +104,8 @@ describe('source overlay', () => {
   test('indexes Class, Property, Method, Edge endpoint, and Function declarations', () => {
     const root = mkdtempSync(join(tmpdir(), 'studio-schema-spans-'))
     roots.push(root)
-    const schemaDir = join(root, 'schema')
-    mkdirSync(schemaDir)
+    const schemaDir = join(root, 'domain/model')
+    mkdirSync(schemaDir, { recursive: true })
     writeFileSync(
       join(schemaDir, 'members.ts'),
       `
@@ -131,12 +131,12 @@ describe('source overlay', () => {
         })
       `,
     )
-    const spans = buildSourceSpans({ ir, schemaDir })
-    expect(spans['class.Issue.property.title']?.file).toBe('schema/members.ts')
-    expect(spans['class.Issue.method.rename']?.file).toBe('schema/members.ts')
-    expect(spans['edge.assigned_to.endpoint.issue']?.file).toBe('schema/members.ts')
-    expect(spans['edge.assigned_to.endpoint.owner']?.file).toBe('schema/members.ts')
-    expect(spans['edge.assigned_to.property.note']?.file).toBe('schema/members.ts')
-    expect(spans['function.createIssue']?.file).toBe('schema/members.ts')
+    const spans = buildSourceSpans({ ir, domainRoot: root, schemaDir })
+    expect(spans['class.Issue.property.title']?.file).toBe('domain/model/members.ts')
+    expect(spans['class.Issue.method.rename']?.file).toBe('domain/model/members.ts')
+    expect(spans['edge.assigned_to.endpoint.issue']?.file).toBe('domain/model/members.ts')
+    expect(spans['edge.assigned_to.endpoint.owner']?.file).toBe('domain/model/members.ts')
+    expect(spans['edge.assigned_to.property.note']?.file).toBe('domain/model/members.ts')
+    expect(spans['function.createIssue']?.file).toBe('domain/model/members.ts')
   })
 })

package/studio/server/introspect/overlay.ts

@@ -14,6 +14,6 @@ export interface OverlayArgs {
 export function buildOverlay({ ir, domainRoot, schemaDir }: OverlayArgs): SchemaOverlay {
   return {
     handlerLinks: buildHandlerLinks({ ir, domainRoot }),
-    sourceSpans: buildSourceSpans({ ir, schemaDir }),
+    sourceSpans: buildSourceSpans({ ir, domainRoot, schemaDir }),
   }
 }

package/studio/server/introspect/runtime.ts

@@ -8,6 +8,7 @@
 import type { SchemaIR, SchemaRevision, StudioSchemaBundle } from '../../shared/types'
 
 import { isSchemaRevision } from '../../shared/types'
+import { studioCliCommand } from '../cli'
 
 const EXTRACTOR = new URL('./extractor.ts', import.meta.url).pathname
 
@@ -28,7 +29,14 @@ export async function runtimeExtract(
   timeoutMs = 20000,
 ): Promise<RuntimeExtractResult> {
   try {
-    const proc = Bun.spawn(['bun', 'run', EXTRACTOR, schemaIndexPath, domainDir], {
+    let command: string[]
+    try {
+      command = studioCliCommand(['__studio-extractor', schemaIndexPath, domainDir])
+    } catch {
+      // Direct Studio development remains supported outside `astrale studio`.
+      command = [process.execPath, EXTRACTOR, schemaIndexPath, domainDir]
+    }
+    const proc = Bun.spawn(command, {
       cwd: domainDir,
       stdout: 'pipe',
       stderr: 'pipe',

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

@@ -2,7 +2,6 @@
  * Source coordinates and leading documentation for authored schema members.
  */
 import { existsSync } from 'node:fs'
-import { dirname } from 'node:path'
 import { Node, SyntaxKind, type CallExpression, type SourceFile } from 'ts-morph'
 
 import type { SchemaIR, SourceSpan } from '../../../shared/types'
@@ -170,14 +169,12 @@ function resolveMemberKind(
 
 export function buildSourceSpans(args: {
   ir: SchemaIR | null
+  domainRoot: string
   schemaDir: string
 }): Record<string, SourceSpan> {
-  const { ir, schemaDir } = args
+  const { ir, domainRoot, schemaDir } = args
   if (!schemaDir || !existsSync(schemaDir)) return {}
 
-  // The domain root is the parent of the schema dir (spans are relative to it).
-  const domainRoot = dirname(schemaDir.replace(/\/$/, ''))
-
   const project = newProject()
   let files: string[] = []
   try {