@astrale-os/cli 1.0.0-beta.27 → 1.0.0-beta.28

package/studio/server/introspect/extractor.ts

@@ -1,9 +1,7 @@
 /** Bun subprocess that imports only the authored Schema entry and its installed SDK. */
-import {
-  admitCanonicalSchemaFromSdk,
-  findCanonicalDomainSchemaExport,
-  projectCanonicalSchema,
-} from './canonical-schema'
+import type { SchemaSdk } from './canonical-schema'
+
+import { extractCanonicalSchemaFromSdk, findCanonicalDomainSchemaExport } from './canonical-schema'
 
 const schemaPath = process.argv[2]
 const projectRoot = process.argv[3] ?? process.cwd()
@@ -15,19 +13,17 @@ async function main(): Promise<void> {
   if (candidate === null) {
     throw new Error('Schema entry exports no canonical V1 DomainSchema.')
   }
-  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)
+  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: projected.ir,
-      root: admission.root,
-      schemaMode: admission.status === 'admitted' ? 'canonical-admitted' : 'canonical-preview',
-      revision: admission.revision,
+      ir: extraction.ir,
+      root: extraction.root,
+      schemaMode: extraction.status === 'admitted' ? 'canonical-admitted' : 'canonical-preview',
+      revision: extraction.revision,
     }),
   )
 }

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

@@ -5,7 +5,7 @@ import { join } from 'node:path'
 
 import type { SchemaIR } from '../../shared/types'
 
-import { buildHandlerLinks, buildSchemaAnnotations, buildSourceSpans } from './overlay-tsmorph'
+import { buildHandlerLinks, buildSourceSpans } from './overlay-tsmorph'
 
 const roots: string[] = []
 afterEach(() => {
@@ -139,8 +139,4 @@ describe('source overlay', () => {
     expect(spans['edge.assigned_to.property.note']?.file).toBe('schema/members.ts')
     expect(spans['function.createIssue']?.file).toBe('schema/members.ts')
   })
-
-  test('does not invent warnings for admitted enum values', () => {
-    expect(buildSchemaAnnotations({ ir })).toEqual([])
-  })
 })

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

@@ -4,6 +4,5 @@
  * Keep this path stable for the overlay composer and focused tests. The
  * implementation lives under source-overlay, split by responsibility.
  */
-export { buildSchemaAnnotations } from './source-overlay/annotations'
 export { buildHandlerLinks } from './source-overlay/handlers'
 export { buildSourceSpans } from './source-overlay/spans'

package/studio/server/introspect/overlay.ts

@@ -1,12 +1,9 @@
 /**
- * overlay.ts — the Studio overlay over the DSL IR. Computes what the IR cannot
- * carry. The import split and dependency list are computed here; handlerLinks,
- * static parse). handlerLinks, sourceSpans (+JSDoc) and annotations are filled
- * by a ts-morph pass over current Schema, Runtime, Action, and Workflow files.
+ * Source-only metadata that the admitted DSL Schema cannot carry.
  */
-import type { CrossDomainImport, SchemaIR, SchemaOverlay } from '../../shared/types'
+import type { SchemaIR, SchemaOverlay } from '../../shared/types'
 
-import { buildHandlerLinks, buildSchemaAnnotations, buildSourceSpans } from './overlay-tsmorph'
+import { buildHandlerLinks, buildSourceSpans } from './overlay-tsmorph'
 
 export interface OverlayArgs {
   ir: SchemaIR | null
@@ -15,26 +12,8 @@ export interface OverlayArgs {
 }
 
 export function buildOverlay({ ir, domainRoot, schemaDir }: OverlayArgs): SchemaOverlay {
-  const origin = ir?.domain ?? ''
-  const mixins: CrossDomainImport[] = []
-  const crossDomainImports: CrossDomainImport[] = []
-  for (const descriptor of Object.values(ir?.importsByKey ?? {})) {
-    const entry: CrossDomainImport = {
-      name: descriptor.ref.name,
-      origin: descriptor.origin,
-      ref: descriptor.ref,
-    }
-    if (descriptor.origin === 'kernel.astrale.ai') mixins.push(entry)
-    else crossDomainImports.push(entry)
-  }
-
   return {
-    origin,
-    requires: (ir?.dependencies ?? []).map(({ origin }) => origin),
-    crossDomainImports,
-    mixins,
     handlerLinks: buildHandlerLinks({ ir, domainRoot }),
     sourceSpans: buildSourceSpans({ ir, schemaDir }),
-    annotations: buildSchemaAnnotations({ ir }),
   }
 }

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

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

package/studio/server/introspect/revision.ts

@@ -1,28 +1,23 @@
 import type { SchemaRevision } from '../../shared/types'
+import type { SchemaAdmissionSdk } from './canonical-schema'
 
 import { isSchemaRevision } from '../../shared/types'
 
-type AnyRecord = Record<string, unknown>
-
 /**
  * Cross the installed-bundle JSON boundary through the Domain's installed SDK, 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>,
+  sdk: SchemaAdmissionSdk,
   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
+    const accepted = sdk.bundle.accept(input)
+    const domain = sdk.schema.resolve(accepted.root)
+    return domain.source === accepted.root && isSchemaRevision(domain.revision)
+      ? domain.revision
+      : null
   } catch {
     return null
   }
@@ -33,17 +28,11 @@ export async function admittedBundleRevision(
   input: unknown,
 ): Promise<SchemaRevision | null> {
   try {
-    const sdkModule: Record<string, unknown> = await import(
+    const sdk = (await import(
       Bun.resolveSync('@astrale-os/sdk/schema', domainRoot)
-    )
-    return admittedBundleRevisionFromSdk(sdkModule, input)
+    )) as unknown as SchemaAdmissionSdk
+    return admittedBundleRevisionFromSdk(sdk, 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,9 +6,10 @@ import { join } from 'node:path'
 import type { DomainHandle } from '../domain'
 
 import { buildBundle } from './bundle'
+import { buildCore } from './core'
 import { renderFingerprintOf } from './hash'
 import { admittedBundleRevision } from './revision'
-import { coreExtract, runtimeExtract } from './runtime'
+import { runtimeExtract } from './runtime'
 
 const roots: string[] = []
 afterEach(() => {
@@ -128,19 +129,18 @@ describe('SDK V1 schema extractor', () => {
 
   test('extracts Core through the pure Schema entry without importing Application', async () => {
     const handle = currentFixture()
-    expect(await coreExtract(handle.schemaIndex, handle.root)).toEqual({
-      ok: true,
-      core: {
-        domain: 'documents.runtime.test',
-        nodes: [
-          {
-            path: '/:documents.runtime.test:core.welcome',
-            className: 'Document',
-            data: {},
-          },
-        ],
-        edges: [],
-      },
+    const bundle = await buildBundle(handle)
+    expect(buildCore(handle, bundle)).toMatchObject({
+      domain: 'documents.runtime.test',
+      nodes: [
+        {
+          path: '/:documents.runtime.test:core.welcome',
+          className: 'Document',
+          data: {},
+        },
+      ],
+      edges: [],
+      error: null,
     })
   })
 })

package/studio/server/introspect/runtime.ts

@@ -5,12 +5,11 @@
  * render IR plus the raw canonical root (when present), or an error render-state
  * — never throws.
  */
-import type { SchemaIR, SchemaRevision, StudioCore, StudioSchemaBundle } from '../../shared/types'
+import type { SchemaIR, SchemaRevision, 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
 
 export interface RuntimeExtractResult {
   ok: boolean
@@ -94,47 +93,3 @@ export async function runtimeExtract(
     }
   }
 }
-
-export interface CoreExtractResult {
-  ok: boolean
-  /** the resolved core graph, or null when the domain defines no core */
-  core: Pick<StudioCore, 'domain' | 'nodes' | 'edges'> | null
-  error?: { message: string }
-}
-
-/**
- * Spawn the Core extractor over the pure Schema entry. Returns the projected
- * graph or an error and never imports Application or Runtime modules.
- */
-export async function coreExtract(
-  schemaIndexPath: string,
-  domainDir: string,
-  timeoutMs = 20000,
-): Promise<CoreExtractResult> {
-  try {
-    const proc = Bun.spawn(['bun', 'run', CORE_EXTRACTOR, schemaIndexPath, domainDir], {
-      cwd: domainDir,
-      stdout: 'pipe',
-      stderr: 'pipe',
-    })
-    const timer = setTimeout(() => proc.kill(9), timeoutMs)
-    const out = await new Response(proc.stdout).text()
-    await proc.exited
-    clearTimeout(timer)
-
-    if (!out.trim()) {
-      const err = await new Response(proc.stderr).text()
-      return {
-        ok: false,
-        core: null,
-        error: { message: err.trim() || 'core extractor produced no output' },
-      }
-    }
-    const parsed = JSON.parse(out)
-    if (!parsed.ok)
-      return { ok: false, core: null, error: parsed.error ?? { message: 'core extraction failed' } }
-    return { ok: true, core: (parsed.core ?? null) as CoreExtractResult['core'] }
-  } catch (e: any) {
-    return { ok: false, core: null, error: { message: String(e?.message ?? e) } }
-  }
-}

package/studio/server/lifecycle.ts

@@ -9,6 +9,7 @@ import type { DomainHandle } from './domain'
  */
 import { getBundle } from './cache'
 import { captureBaseline, hashAnatomyFiles, loadBaseline } from './state/baseline'
+import { migrateDocuments } from './state/documents'
 import { initDotDir } from './state/store'
 import { watchDomain } from './watch'
 
@@ -22,6 +23,8 @@ export interface BootedDomain {
 /** Initialize + start watching one domain. Returns its origin + a stop handle. */
 export async function bootDomain(handle: DomainHandle): Promise<BootedDomain> {
   initDotDir(handle.root)
+  // one-shot: uuid-named documents become readable file names under context/docs
+  migrateDocuments(handle.root)
   const bundle = await getBundle(handle.id)
   if (!loadBaseline(handle.root))
     captureBaseline(
@@ -35,7 +38,7 @@ export async function bootDomain(handle: DomainHandle): Promise<BootedDomain> {
     )
   const stop = watchDomain(handle)
   return {
-    origin: bundle?.overlay.origin ?? handle.id,
+    origin: bundle?.ir?.domain ?? handle.origin ?? handle.id,
     depsInstalled: !!bundle?.depsInstalled,
     stop,
   }

package/studio/server/state/documents.test.ts

@@ -0,0 +1,69 @@
+import { afterEach, expect, test } from 'bun:test'
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { addDocument, listDocuments, migrateDocuments, readDocument } from './documents'
+import { statePath, writeJson, writeStateBuffer } from './store'
+
+const roots: string[] = []
+
+function root(): string {
+  const created = mkdtempSync(join(tmpdir(), 'studio-documents-'))
+  roots.push(created)
+  return created
+}
+
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+const bytes = (text: string) => new TextEncoder().encode(text)
+
+test('a document is stored under a readable name, not its id', () => {
+  const domain = root()
+  const meta = addDocument(domain, 'Pricing Decisions.MD', 'text/markdown', bytes('# pricing'))
+
+  expect(meta.stored).toBe('context/docs/pricing-decisions.md')
+  expect(readFileSync(statePath(domain, meta.stored), 'utf8')).toBe('# pricing')
+  expect(readDocument(domain, meta.id)?.meta.name).toBe('Pricing Decisions.MD')
+})
+
+test('same-named documents never overwrite each other', () => {
+  const domain = root()
+  const first = addDocument(domain, 'notes.md', 'text/markdown', bytes('first'))
+  const second = addDocument(domain, 'notes.md', 'text/markdown', bytes('second'))
+
+  expect([first.stored, second.stored]).toEqual([
+    'context/docs/notes.md',
+    'context/docs/notes-2.md',
+  ])
+  expect(readFileSync(statePath(domain, first.stored), 'utf8')).toBe('first')
+})
+
+test('uuid-named documents are migrated in place, once', () => {
+  const domain = root()
+  const legacy = 'context/documents/2b0d9d7e-1f2a-4a10-9f0c-1a2b3c4d5e6f.md'
+  writeStateBuffer(domain, legacy, bytes('legacy body'))
+  writeJson(domain, 'context/documents/index.json', [
+    {
+      id: '2b0d9d7e-1f2a-4a10-9f0c-1a2b3c4d5e6f',
+      name: 'Meeting notes.md',
+      type: 'text/markdown',
+      size: 11,
+      addedAt: new Date(0).toISOString(),
+      stored: legacy,
+    },
+  ])
+
+  migrateDocuments(domain)
+  const [migrated] = listDocuments(domain)
+
+  expect(migrated?.stored).toBe('context/docs/meeting-notes.md')
+  expect(readFileSync(statePath(domain, migrated!.stored), 'utf8')).toBe('legacy body')
+  expect(existsSync(statePath(domain, legacy))).toBe(false)
+
+  // idempotent: a second boot leaves the already-migrated store alone
+  migrateDocuments(domain)
+  expect(listDocuments(domain)[0]?.stored).toBe('context/docs/meeting-notes.md')
+})

package/studio/server/state/documents.ts

@@ -1,10 +1,11 @@
 /**
- * documents.ts — context DOCUMENTS the user drops in for the AI agent. Files are
- * stored under `.domain-studio/context/documents/` (allow-listed) and tracked in
- * an index. They travel with the domain and are part of the agent handoff context.
+ * documents.ts — context DOCUMENTS the user drops in for the AI agent. Files live
+ * under `.domain-studio/context/docs/`, named after the document (not its id), so
+ * the folder is readable by a human and by the agent that is handed its path.
+ * They travel with the domain and are part of the agent handoff context.
  */
 import { randomUUID } from 'node:crypto'
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { extname } from 'node:path'
 
 import type { DocMeta } from '../../shared/types'
@@ -13,7 +14,54 @@ import { asFiniteNumber, asJsonRecord, asString } from '../json'
 import { readJson, removeState, statePath, writeJson, writeStateBuffer } from './store'
 
 const INDEX = 'context/documents/index.json'
-const storedPath = (id: string, name: string) => `context/documents/${id}${extname(name)}`
+const DIR = 'context/docs'
+/** Where documents lived before they were named: `context/documents/<uuid>.<ext>`. */
+const LEGACY_DIR = 'context/documents'
+
+/** `Pricing decisions.md` → `pricing-decisions` — a file name you can read. */
+function slugify(name: string): string {
+  const base = name.replace(/\.[^.]+$/, '')
+  const slug = base
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60)
+  return slug || 'document'
+}
+
+/** A stored path no other document (and no file on disk) already claims. */
+function uniqueStoredPath(root: string, docs: DocMeta[], name: string): string {
+  const extension = extname(name).toLowerCase()
+  const slug = slugify(name)
+  const taken = new Set(docs.map((doc) => doc.stored))
+  for (let attempt = 0; ; attempt++) {
+    const candidate = `${DIR}/${slug}${attempt === 0 ? '' : `-${attempt + 1}`}${extension}`
+    if (!taken.has(candidate) && !existsSync(statePath(root, candidate))) return candidate
+  }
+}
+
+/**
+ * Move documents written under the old uuid-named layout into `context/docs/`.
+ * Idempotent and only ever renames inside the studio's own state directory.
+ */
+export function migrateDocuments(root: string): void {
+  const docs = listDocuments(root)
+  if (!docs.some((doc) => doc.stored.startsWith(`${LEGACY_DIR}/`))) return
+  let moved = false
+  for (const doc of docs) {
+    if (!doc.stored.startsWith(`${LEGACY_DIR}/`)) continue
+    const from = statePath(root, doc.stored)
+    if (!existsSync(from)) continue
+    const next = uniqueStoredPath(root, docs, doc.name)
+    writeStateBuffer(root, next, readFileSync(from))
+    removeState(root, doc.stored)
+    doc.stored = next
+    moved = true
+  }
+  if (moved) writeJson(root, INDEX, docs)
+}
 
 function decodeDocument(value: unknown): DocMeta | undefined {
   const record = asJsonRecord(value)
@@ -30,7 +78,7 @@ function decodeDocument(value: unknown): DocMeta | undefined {
     size === undefined ||
     size < 0 ||
     !addedAt ||
-    !stored?.startsWith('context/documents/') ||
+    !(stored?.startsWith(`${DIR}/`) || stored?.startsWith(`${LEGACY_DIR}/`)) ||
     stored.split('/').includes('..')
   ) {
     return undefined
@@ -60,18 +108,17 @@ export function listDocuments(root: string): DocMeta[] {
 }
 
 export function addDocument(root: string, name: string, type: string, data: Uint8Array): DocMeta {
-  const id = randomUUID()
-  const stored = storedPath(id, name)
+  const docs = listDocuments(root)
+  const stored = uniqueStoredPath(root, docs, name || 'untitled')
   writeStateBuffer(root, stored, data)
   const meta: DocMeta = {
-    id,
+    id: randomUUID(),
     name: name || 'untitled',
     type: type || 'application/octet-stream',
     size: data.byteLength,
     addedAt: new Date().toISOString(),
     stored,
   }
-  const docs = listDocuments(root)
   docs.unshift(meta)
   writeJson(root, INDEX, docs)
   return meta

package/studio/shared/contracts/schema.ts

@@ -18,11 +18,17 @@ export interface JsonSchema {
   maximum?: number
   format?: string
   description?: string
-  $nodeRef?: unknown
-  $dataRef?: unknown
+  $ref?: string
   [k: string]: unknown
 }
 
+const NODE_PATH_SCHEMA_ID = 'https://schemas.astrale.ai/graph/1/node-path'
+
+/** Structural form emitted by the V1 DSL for a graph Node path. */
+export function isNodePathSchema(schema: JsonSchema): boolean {
+  return schema.$ref === NODE_PATH_SCHEMA_ID && Object.hasOwn(schema, 'x-astrale-path')
+}
+
 export type MethodInheritance = 'default' | 'abstract' | 'sealed'
 
 /** Portable form of the DSL-owned canonical schema revision. */
@@ -37,7 +43,7 @@ export function isSchemaRevision(value: unknown): value is SchemaRevision {
  * Version of Studio's lossy canonical-schema -> render-IR projection. Persisted
  * baselines must match this value before their IR can be compared.
  */
-export const STUDIO_SCHEMA_PROJECTION_VERSION = 2
+export const STUDIO_SCHEMA_PROJECTION_VERSION = 3
 
 export type IrCallableAuth = 'anonymous' | 'authenticated' | 'authorized'
 
@@ -151,32 +157,10 @@ export interface SourceSpan {
   doc?: string
 }
 
-export interface SchemaAnnotation {
-  /** anchor ref key, e.g. 'class.Monitor.property.status' */
-  target: string
-  severity: 'warn' | 'info'
-  code: 'COMPILE_ERROR' | 'EDGE_PROP_TYPE_MISSING'
-  message: string
-}
-
-export interface CrossDomainImport {
-  name: string
-  origin: string
-  ref: IrClassRef
-}
-
 export interface SchemaOverlay {
-  origin: string
-  /** Exact declared Domain dependencies. */
-  requires: string[]
-  /** Non-Kernel imported Classes. */
-  crossDomainImports: CrossDomainImport[]
-  /** Kernel base Classes rendered as inherited platform facts. */
-  mixins: CrossDomainImport[]
   handlerLinks: HandlerLink[]
   /** Keyed by Class, Property, Method, Function, Policy, View, or Core anchor. */
   sourceSpans: Record<string, SourceSpan>
-  annotations: SchemaAnnotation[]
 }
 
 export interface BundleError {
@@ -388,4 +372,4 @@ export type TypeDescriptor =
       required: string[]
       optional: boolean
     }
-  | { kind: 'ref'; target: string; refKind: 'node' | 'data'; optional: boolean }
+  | { kind: 'ref'; target: 'node'; optional: boolean }

package/studio/shared/contracts/surface.test.ts

@@ -33,9 +33,9 @@ const TARGET_BARREL_EXPORTS = [
   'ContextStore',
   'ConversationInfo',
   'CopyPayload',
-  'CrossDomainImport',
   'DeployRecord',
   'DeployResult',
+  'DOCUMENTS_DIR',
   'DocMeta',
   'DomainAnatomy',
   'DomainCatalogEntry',
@@ -82,7 +82,6 @@ const TARGET_BARREL_EXPORTS = [
   'MethodInheritance',
   'NodePosition',
   'RememberedViewTarget',
-  'SchemaAnnotation',
   'SchemaChange',
   'SchemaChangeKind',
   'SchemaIR',
@@ -115,6 +114,7 @@ const TARGET_BARREL_HELPERS = [
   'classRefKey',
   'isIrClassRef',
   'isIrSchemaRef',
+  'isNodePathSchema',
   'isSchemaRevision',
   'parseClassRefKey',
   'parseSchemaRefKey',

package/studio/shared/contracts/workspace.ts

@@ -202,6 +202,9 @@ export interface DocMeta {
   stored: string
 }
 
+/** Where context documents live inside a domain — shown in the UI, read by the agent. */
+export const DOCUMENTS_DIR = '.domain-studio/context/docs'
+
 export interface Integration {
   id: string
   name: string

package/studio/shared/schema/identity.ts

@@ -4,7 +4,6 @@
  * These helpers validate and encode only the structural wire coordinate. SDK
  * admission remains the authority for whether a reference is semantically valid.
  */
-
 export const IR_SCHEMA_REF_KINDS = ['class', 'function', 'policy', 'view', 'core'] as const
 
 export type IrSchemaRefKind = (typeof IR_SCHEMA_REF_KINDS)[number]