@astrale-os/cli 1.0.0-beta.0 → 1.0.0-beta.10

package/studio/server/views/session.ts

@@ -0,0 +1,166 @@
+import type {
+  StudioSchemaBundle,
+  ViewInfo,
+  ViewSessionResult,
+  ViewTargetCandidate,
+} from '../../shared/types'
+import type { StudioCliDecoder } from '../cli'
+
+import { decodeJsonObject, runStudioCliJson } from '../cli'
+import { activeInstanceName } from '../instances/active'
+import { rememberTarget } from './selection-repository'
+import { listViewTargets, viewDefinitionBindings } from './target'
+
+export { conciseCliFailure } from '../cli'
+
+interface AstraleResult<T> {
+  ok: boolean
+  data: T | null
+  detail: string
+}
+
+let viewSessionCommandTail: Promise<void> = Promise.resolve()
+
+export function viewSessionArgs(
+  origin: string,
+  slug: string,
+  instance: string,
+  targetRef?: string,
+): string[] {
+  const args = ['view', `/:${assertOrigin(origin)}:view.${assertViewSlug(slug)}`]
+  if (targetRef) args.push('--target', targetRef)
+  args.push('--no-open', '--json', '-i', instance)
+  return args
+}
+
+interface OpenedViewPayload {
+  session?: {
+    id?: string
+    pageUrl?: string
+    view?: { route?: { href?: string } }
+  }
+}
+
+function decodeOpenedViewPayload(value: unknown): OpenedViewPayload | null {
+  const payload = decodeJsonObject(value)
+  if (!payload) return null
+  const session = decodeJsonObject(payload.session)
+  if (!session) return null
+  const view = decodeJsonObject(session.view)
+  const route = decodeJsonObject(view?.route)
+  if (
+    typeof session.id !== 'string' ||
+    typeof session.pageUrl !== 'string' ||
+    typeof route?.href !== 'string'
+  ) {
+    return null
+  }
+  return {
+    session: {
+      id: session.id,
+      pageUrl: session.pageUrl,
+      view: { route: { href: route.href } },
+    },
+  }
+}
+
+export function readyViewSession(
+  opened: OpenedViewPayload | null,
+  target: ViewTargetCandidate | null,
+): Extract<ViewSessionResult, { status: 'ready' }> | null {
+  const session = opened?.session
+  const viewUrl = session?.view?.route?.href
+  if (!session?.id || !session.pageUrl || !viewUrl) return null
+  return {
+    status: 'ready',
+    sessionId: session.id,
+    pageUrl: session.pageUrl,
+    viewUrl,
+    target,
+  }
+}
+
+export async function launchViewSession(
+  root: string,
+  origin: string,
+  view: ViewInfo,
+  bundle: StudioSchemaBundle | null,
+  request: { targetId?: unknown },
+  timeoutMs: number,
+): Promise<ViewSessionResult> {
+  const instance = await activeInstanceName()
+  if (!instance) return { status: 'unavailable', reason: 'No active Astrale instance.' }
+
+  let target: ViewTargetCandidate | null = null
+  if (viewDefinitionBindings(origin, view, bundle).length > 0) {
+    const targetId = typeof request.targetId === 'string' ? request.targetId.trim() : ''
+    if (!targetId) return { status: 'unavailable', reason: 'Select a target before opening.' }
+    const targets = await listViewTargets(root, origin, view, bundle, instance, timeoutMs)
+    if (targets.status !== 'available') {
+      return { status: 'unavailable', reason: targets.reason ?? 'Targets could not be queried.' }
+    }
+    target = targets.items.find((item) => item.id === targetId) ?? null
+    if (!target) {
+      return {
+        status: 'unavailable',
+        reason: 'That target no longer exists or is no longer visible. Choose another target.',
+      }
+    }
+  }
+
+  const opened = await runViewSessionCommand<OpenedViewPayload>(
+    viewSessionArgs(origin, view.slug, instance, target?.ref),
+    Math.max(20_000, timeoutMs + 12_000),
+    decodeOpenedViewPayload,
+  )
+  const session = opened.ok ? readyViewSession(opened.data, target) : null
+  if (!session) {
+    return {
+      status: 'unavailable',
+      reason: opened.detail || '`astrale view` could not start the preview session.',
+    }
+  }
+
+  if (target) rememberTarget(root, instance, view.slug, target)
+  return session
+}
+
+export async function closeViewSession(sessionId: string): Promise<{ ok: true }> {
+  if (!/^v-[0-9a-f]+$/.test(sessionId)) return { ok: true }
+  await runViewSessionCommand(['view', '--close', sessionId, '--json'], 6000, decodeJsonObject)
+  return { ok: true }
+}
+
+function assertOrigin(value: string): string {
+  if (!/^[a-z0-9][a-z0-9.-]*$/i.test(value)) throw new Error(`Invalid domain origin: ${value}`)
+  return value
+}
+
+function assertViewSlug(value: string): string {
+  if (!/^[a-z][a-z0-9-]*$/.test(value)) throw new Error(`Invalid view slug: ${value}`)
+  return value
+}
+
+function runViewSessionCommand<T>(
+  args: string[],
+  timeoutMs: number,
+  decoder: StudioCliDecoder<T>,
+): Promise<AstraleResult<T>> {
+  const command = viewSessionCommandTail.then(
+    () => runAstraleJson(args, timeoutMs, decoder),
+    () => runAstraleJson(args, timeoutMs, decoder),
+  )
+  viewSessionCommandTail = command.then(
+    () => undefined,
+    () => undefined,
+  )
+  return command
+}
+
+async function runAstraleJson<T>(
+  args: string[],
+  timeoutMs: number,
+  decoder: StudioCliDecoder<T>,
+): Promise<AstraleResult<T>> {
+  return runStudioCliJson(args, decoder, { timeoutMs })
+}

package/studio/server/views/target.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from 'bun:test'
+
+import type { StudioSchemaBundle, ViewInfo } from '../../shared/types'
+
+import { targetDefinition, viewDefinitionBindings } from './target'
+
+describe('View target definitions', () => {
+  test('preserves every exact canonical Class target and ignores short-name metadata', () => {
+    const view = {
+      slug: 'named',
+      kind: 'unknown',
+      viewFor: 'WrongFallback',
+    } satisfies ViewInfo
+    const bundle = {
+      ir: {
+        views: {
+          named: {
+            name: 'named',
+            auth: 'required',
+            target: {
+              kind: 'definition',
+              definitions: [
+                { origin: 'directory.example.dev', kind: 'class', name: 'Named' },
+                { origin: 'people.example.dev', kind: 'class', name: 'Named' },
+              ],
+            },
+          },
+        },
+      },
+    } as unknown as StudioSchemaBundle
+    expect(viewDefinitionBindings('shell.astrale.ai', view, bundle)).toEqual([
+      { className: 'Named', classOrigin: 'directory.example.dev', kind: 'class' },
+      { className: 'Named', classOrigin: 'people.example.dev', kind: 'class' },
+    ])
+  })
+
+  test('treats a canonical Domain target as authoritative', () => {
+    const view = { slug: 'home', kind: 'unknown', viewFor: 'User' } satisfies ViewInfo
+    const bundle = {
+      ir: { views: { home: { name: 'home', auth: 'required', target: { kind: 'domain' } } } },
+    } as unknown as StudioSchemaBundle
+    expect(viewDefinitionBindings('shell.astrale.ai', view, bundle)).toEqual([])
+  })
+
+  test('resolves fallback targets through local and exact imported Classes', () => {
+    const view = { slug: 'named', kind: 'unknown', viewFor: 'Named' } satisfies ViewInfo
+    const bundle = {
+      ir: {
+        domain: 'shell.astrale.ai',
+        views: {},
+        classes: {
+          Named: {
+            type: 'node',
+            name: 'Named',
+            origin: 'shell.astrale.ai',
+            properties: {},
+            methods: {},
+          },
+        },
+        importsByKey: {
+          'catalog.example.dev:class.Named': {
+            origin: 'catalog.example.dev',
+            ref: { origin: 'catalog.example.dev', kind: 'class', name: 'Named' },
+            key: 'catalog.example.dev:class.Named',
+          },
+        },
+      },
+    } as unknown as StudioSchemaBundle
+    expect(viewDefinitionBindings('shell.astrale.ai', view, bundle)).toEqual([
+      { className: 'Named', classOrigin: 'shell.astrale.ai', kind: 'class' },
+      { className: 'Named', classOrigin: 'catalog.example.dev', kind: 'class' },
+    ])
+  })
+
+  test('addresses exact Class instances through a canonical Definition source', () => {
+    expect(targetDefinition('Issue', 'issues.astrale.ai')).toBe('/:issues.astrale.ai:class.Issue')
+  })
+})

package/studio/server/views/target.ts

@@ -0,0 +1,222 @@
+import type {
+  StudioSchemaBundle,
+  ViewInfo,
+  ViewTargetCandidate,
+  ViewTargetResult,
+} from '../../shared/types'
+import type { StudioCliDecoder } from '../cli'
+
+import { decodeJsonObject, runStudioCliJson } from '../cli'
+import { reconcileRememberedTarget, targetFromRow, type RawTargetRow } from './model'
+import { readRememberedTarget } from './selection-repository'
+
+const TARGET_LIMIT = 200
+
+interface AstraleResult<T> {
+  ok: boolean
+  data: T | null
+  detail: string
+}
+
+interface RawQueryResult {
+  graph?: { nodes?: RawTargetRow[] }
+}
+
+function decodeTargetRow(value: unknown): RawTargetRow | null {
+  const row = decodeJsonObject(value)
+  if (!row) return null
+  const props = decodeJsonObject(row.props)
+  return {
+    ...(typeof row.id === 'string' ? { id: row.id } : {}),
+    ...(props ? { props } : {}),
+  }
+}
+
+function decodeQueryResult(value: unknown): RawQueryResult | null {
+  const payload = decodeJsonObject(value)
+  const graph = decodeJsonObject(payload?.graph)
+  if (!graph || !Array.isArray(graph.nodes)) return null
+  const nodes = graph.nodes.map(decodeTargetRow).filter((row) => row !== null)
+  return { graph: { nodes } }
+}
+
+export async function listViewTargets(
+  root: string,
+  origin: string,
+  view: ViewInfo,
+  bundle: StudioSchemaBundle | null,
+  instance: string,
+  timeoutMs: number,
+): Promise<ViewTargetResult> {
+  const bindings = viewDefinitionBindings(origin, view, bundle)
+  if (bindings.length === 0) {
+    return {
+      status: 'available',
+      items: [],
+      selected: null,
+      stale: null,
+      truncated: false,
+    }
+  }
+
+  const queried = await Promise.all(
+    bindings.map(async (binding) => {
+      const definition = targetDefinition(binding.className, binding.classOrigin)
+      const result = await runAstraleJson<RawQueryResult>(
+        [
+          'query',
+          '--definition',
+          definition,
+          '--limit',
+          String(TARGET_LIMIT + 1),
+          '--json',
+          '-i',
+          instance,
+        ],
+        timeoutMs,
+        decodeQueryResult,
+      )
+      return { binding, result }
+    }),
+  )
+  const successes = queried.filter(
+    (item) => item.result.ok && Array.isArray(item.result.data?.graph?.nodes),
+  )
+  if (successes.length === 0) {
+    const reason = queried.map((item) => item.result.detail).find(Boolean)
+    return {
+      status: 'unavailable',
+      items: [],
+      selected: null,
+      stale: null,
+      truncated: false,
+      reason: reason || 'The active instance could not be queried for view targets.',
+    }
+  }
+
+  const byId = new Map<string, ViewTargetCandidate>()
+  let truncated = false
+  for (const { binding, result } of successes) {
+    const rows = result.data?.graph?.nodes ?? []
+    if (rows.length > TARGET_LIMIT) truncated = true
+    for (const row of rows.slice(0, TARGET_LIMIT)) {
+      const target = targetFromRow(row, binding.className, binding.classOrigin)
+      if (target) byId.set(target.id, target)
+    }
+  }
+  const items = [...byId.values()].sort(
+    (a, b) => a.label.localeCompare(b.label) || a.className.localeCompare(b.className),
+  )
+  const remembered = readRememberedTarget(root, instance, view.slug)
+  return {
+    status: 'available',
+    items,
+    ...reconcileRememberedTarget(remembered, items),
+    truncated,
+  }
+}
+
+export function targetDefinition(className: string, classOrigin: string): string {
+  return `/:${assertOrigin(classOrigin)}:class.${assertSchemaName(className)}`
+}
+
+export interface ViewDefinitionBinding {
+  className: string
+  classOrigin: string
+  kind: 'class'
+}
+
+/** Preserve exact canonical View target coordinates. */
+export function viewDefinitionBindings(
+  origin: string,
+  view: ViewInfo,
+  bundle: StudioSchemaBundle | null,
+): ViewDefinitionBinding[] {
+  const target = bundle?.ir?.views?.[view.slug]?.target
+  if (target) {
+    if (target.kind === 'domain') return []
+    return uniqueViewBindings(
+      target.definitions.flatMap((definition) =>
+        definition.kind === 'class'
+          ? [
+              {
+                className: definition.name,
+                classOrigin: definition.origin,
+                kind: 'class' as const,
+              },
+            ]
+          : [],
+      ),
+    )
+  }
+
+  const names = Array.isArray(view.viewFor) ? view.viewFor : view.viewFor ? [view.viewFor] : []
+  const ir = bundle?.ir
+  if (!ir) {
+    return uniqueViewBindings(
+      names.map((className) => ({ className, classOrigin: origin, kind: 'class' })),
+    )
+  }
+
+  return uniqueViewBindings(
+    names.flatMap((className) => {
+      const local: ViewDefinitionBinding[] = []
+      const localClass = ir.classes[className]
+      if (localClass) {
+        local.push({
+          className,
+          classOrigin: localClass.ref?.origin ?? localClass.origin ?? ir.domain ?? origin,
+          kind: 'class',
+        })
+      }
+      const imported = Object.keys(ir.importsByKey).flatMap((key) => {
+        const binding = viewBindingFromDefinitionKey(key)
+        return binding?.className === className ? [binding] : []
+      })
+      if (imported.length > 0) return [...local, ...imported]
+
+      return local.length > 0 ? local : [{ className, classOrigin: origin, kind: 'class' }]
+    }),
+  )
+}
+
+function viewBindingFromDefinitionKey(key: string): ViewDefinitionBinding | null {
+  const separator = key.lastIndexOf(':')
+  if (separator <= 0) return null
+  const classOrigin = key.slice(0, separator)
+  const ref = key.slice(separator + 1)
+  const match = /^class\.([A-Za-z_$][\w$]*)$/.exec(ref)
+  if (!match) return null
+  return {
+    className: match[1]!,
+    classOrigin,
+    kind: 'class',
+  }
+}
+
+function uniqueViewBindings(bindings: ViewDefinitionBinding[]): ViewDefinitionBinding[] {
+  const unique = new Map<string, ViewDefinitionBinding>()
+  for (const binding of bindings) {
+    const key = `${binding.classOrigin}:${binding.kind}.${binding.className}`
+    if (!unique.has(key)) unique.set(key, binding)
+  }
+  return [...unique.values()]
+}
+
+function assertOrigin(value: string): string {
+  if (!/^[a-z0-9][a-z0-9.-]*$/i.test(value)) throw new Error(`Invalid domain origin: ${value}`)
+  return value
+}
+
+function assertSchemaName(value: string): string {
+  if (!/^[A-Za-z_$][\w$]*$/.test(value)) throw new Error(`Invalid class name: ${value}`)
+  return value
+}
+
+async function runAstraleJson<T>(
+  args: string[],
+  timeoutMs: number,
+  decoder: StudioCliDecoder<T>,
+): Promise<AstraleResult<T>> {
+  return runStudioCliJson(args, decoder, { timeoutMs })
+}

package/studio/server/watch.test.ts

@@ -10,27 +10,27 @@ const handle: DomainHandle = {
   id: 'current',
   root: '/workspace/current',
   configFile: '/workspace/current/astrale.config.ts',
-  domainFile: '/workspace/current/implementation.ts',
+  applicationFile: '/workspace/current/application.ts',
   schemaDirName: 'schema',
   schemaDir: '/workspace/current/schema',
   schemaIndex: '/workspace/current/schema/index.ts',
 }
 
-test('watches current layout roots and reconciles either composition entry', () => {
-  expect(ANATOMY_PATHS).toContain('implementation.ts')
+test('watches current Application, Runtime, and vertical authoring roots', () => {
+  expect(ANATOMY_PATHS).toContain('application.ts')
+  expect(ANATOMY_PATHS).toContain('runtime.ts')
   expect(ANATOMY_PATHS).toContain('ui')
-  expect(ANATOMY_PATHS).toContain('handlers')
+  expect(ANATOMY_PATHS).toContain('providers')
   expect(ANATOMY_PATHS).toContain('queries')
   expect(ANATOMY_PATHS).toContain('workflows')
-  expect(DOMAIN_SET_TRIGGER_FILES.has('implementation.ts')).toBe(true)
-  expect(DOMAIN_SET_TRIGGER_FILES.has('domain.ts')).toBe(true)
+  expect(DOMAIN_SET_TRIGGER_FILES.has('application.ts')).toBe(true)
+  expect(DOMAIN_SET_TRIGGER_FILES.has('schema.ts')).toBe(true)
 })
 
-test('composition and handler source changes invalidate the schema bundle', () => {
-  expect(affectsBundle(handle, join(handle.root, 'implementation.ts'))).toBe(true)
-  expect(affectsBundle(handle, join(handle.root, 'domain.ts'))).toBe(true)
+test('Application, Runtime, Action, and Workflow changes invalidate the schema bundle', () => {
+  expect(affectsBundle(handle, join(handle.root, 'application.ts'))).toBe(true)
+  expect(affectsBundle(handle, join(handle.root, 'runtime.ts'))).toBe(true)
   expect(affectsBundle(handle, join(handle.root, 'actions', 'risk', 'create.ts'))).toBe(true)
-  expect(affectsBundle(handle, join(handle.root, 'functions', 'user', 'ensure.ts'))).toBe(true)
-  expect(affectsBundle(handle, join(handle.root, 'handlers', 'create.ts'))).toBe(true)
+  expect(affectsBundle(handle, join(handle.root, 'workflows', 'user', 'ensure.ts'))).toBe(true)
   expect(affectsBundle(handle, join(handle.root, 'views', 'routes.ts'))).toBe(false)
 })

package/studio/server/watch.ts

@@ -19,10 +19,9 @@ export const ANATOMY_PATHS = [...ANATOMY_GLOBS.files, ...ANATOMY_GLOBS.dirs]
 // part of the schema bundle cache even though they are outside schema/ itself.
 const BUNDLE_SOURCE_DIRS = new Set([
   'actions',
-  'capabilities',
-  'functions',
-  'handlers',
+  'integrations',
   'mutations',
+  'providers',
   'queries',
   'rules',
   'runtime',
@@ -42,7 +41,12 @@ function ignored(p: string): boolean {
 export function affectsBundle(handle: DomainHandle, path: string): boolean {
   const rel = relative(handle.root, path).split('\\').join('/')
   const topLevel = rel.split('/')[0]
-  return rel === 'implementation.ts' || rel === 'domain.ts' || BUNDLE_SOURCE_DIRS.has(topLevel)
+  return (
+    path === handle.applicationFile ||
+    rel === 'runtime.ts' ||
+    rel.endsWith('/runtime.ts') ||
+    BUNDLE_SOURCE_DIRS.has(topLevel)
+  )
 }
 
 export function watchDomain(handle: DomainHandle): () => void {
@@ -68,7 +72,7 @@ export function watchDomain(handle: DomainHandle): () => void {
       broadcast({
         type: 'schema-diff',
         domainId: handle.id,
-        schemaHash: b?.schemaHash ?? 'sha-none',
+        renderFingerprint: b?.renderFingerprint ?? 'sha-none',
       })
       broadcast({ type: 'anatomy-diff', domainId: handle.id })
     }, 150)

package/studio/server/workspace/catalog.test.ts

@@ -0,0 +1,17 @@
+import { expect, test } from 'bun:test'
+
+import { buildCatalog } from './catalog'
+
+test('workspace catalog contains only discovered domains and never simulated import authorities', () => {
+  const catalog = buildCatalog([
+    { origin: 'issues.example.dev', id: 'issues' },
+    { origin: 'billing.example.dev', id: 'billing-service' },
+  ])
+
+  expect(catalog.map(({ origin, kind }) => ({ origin, kind }))).toEqual([
+    { origin: 'kernel.astrale.ai', kind: 'kernel' },
+    { origin: 'issues.example.dev', kind: 'local' },
+    { origin: 'billing.example.dev', kind: 'local' },
+  ])
+  expect(catalog.some((entry) => entry.kind === 'external')).toBe(false)
+})

package/studio/server/workspace/catalog.ts

@@ -0,0 +1,43 @@
+/**
+ * Display metadata for domains Studio has actually discovered in its workspace.
+ * This is not an import registry or an authority for available domains. Until a
+ * real registry exists, it contains only the required Kernel and local workspace
+ * domains; Studio must not advertise simulated external services as importable.
+ */
+import type { DomainCatalogEntry } from '../../shared/types'
+
+const icon = (inner: string) =>
+  `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">${inner}</svg>`
+
+const HEXAGON = icon(
+  '<path d="M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z"/><path d="m7.5 4.27 9 5.15"/><path d="m3.3 7 8.7 5 8.7-5"/><path d="M12 22V12"/>',
+)
+const BOXES = icon(
+  '<path d="M2.97 12.92A2 2 0 0 0 2 14.63v3.24a2 2 0 0 0 .97 1.71l3 1.8a2 2 0 0 0 2.06 0L12 19v-5.5l-5-3-4.03 2.42Z"/><path d="m7 16.5-4.74-2.85"/><path d="m7 16.5 5-3"/><path d="M7 16.5v5.17"/><path d="M12 13.5V19l3.97 2.38a2 2 0 0 0 2.06 0l3-1.8a2 2 0 0 0 .97-1.71v-3.24a2 2 0 0 0-.97-1.71L17 10.5l-5 3Z"/><path d="m17 16.5-5-3"/><path d="m17 16.5 4.74-2.85"/><path d="M17 16.5v5.17"/><path d="M7.97 4.42A2 2 0 0 0 7 6.13v4.37l5 3 5-3V6.13a2 2 0 0 0-.97-1.71l-3-1.8a2 2 0 0 0-2.06 0l-3 1.8Z"/><path d="M12 8 7.26 5.15"/><path d="m12 8 4.74-2.85"/><path d="M12 13.5V8"/>',
+)
+const KERNEL: DomainCatalogEntry = {
+  origin: 'kernel.astrale.ai',
+  name: 'Kernel',
+  kind: 'kernel',
+  description: 'The typed graph every domain is built on.',
+  icon: HEXAGON,
+  required: true,
+}
+
+function humanize(slug: string): string {
+  return slug
+    .replace(/[-_]+/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase())
+    .trim()
+}
+
+export function buildCatalog(locals: { origin: string; id: string }[]): DomainCatalogEntry[] {
+  const localEntries: DomainCatalogEntry[] = locals.map((d) => ({
+    origin: d.origin,
+    name: humanize(d.id),
+    kind: 'local',
+    description: 'A domain in this workspace.',
+    icon: BOXES,
+  }))
+  return [KERNEL, ...localEntries]
+}

package/studio/server/{state → workspace}/create.test.ts

@@ -11,7 +11,7 @@ afterEach(() => {
   while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
 })
 
-test('annotates the schema definition behind a current barrel', () => {
+test('workspace creation annotates the schema definition behind a current barrel', () => {
   const root = mkdtempSync(join(tmpdir(), 'studio-create-origin-'))
   roots.push(root)
   mkdirSync(join(root, 'schema', 'application'), { recursive: true })

package/studio/server/{state → workspace}/create.ts

@@ -1,5 +1,5 @@
 /**
- * state/create.ts — scaffold a brand-new domain into the workspace and bring it
+ * Scaffold a brand-new domain into the workspace and bring it
  * online. This is the studio's ONE write that ADDS a domain (every other state
  * module operates on an existing one).
  *

package/studio/server/{state → workspace}/git.ts

@@ -1,5 +1,5 @@
 /**
- * git.ts — best-effort git enrichment for change tracking. The fixtures are not
+ * Best-effort workspace Git enrichment for change tracking. The fixtures are not
  * git repos, so EVERY function here degrades gracefully and NEVER throws. The
  * baseline (baseline.ts) is the primary tracker; git only enriches when present.
  */