@astrale-os/cli 1.0.0-beta.5 → 1.0.0-beta.7

package/src/connection/failure/classify.ts

@@ -0,0 +1,110 @@
+import { AuthValueError } from '@astrale-os/sdk/auth'
+import { ClientError, ProtocolError, ResponseError, TransportError } from '@astrale-os/sdk/client'
+import { NodeUnavailableError } from '@astrale-os/sdk/client'
+import { PathError } from '@astrale-os/sdk/graph/path'
+
+import type { FailureDiagnostic, TransportDiagnosticContext } from './model'
+
+import { AstraleError } from '../../errors'
+
+export function classifyFailure(error: unknown): FailureDiagnostic {
+  if (error instanceof AstraleError) return simple(error.code, error.message, error.hint)
+  if (error instanceof TransportError) {
+    const context = transportContext(error)
+    if (context === undefined) return simple('TRANSPORT_ERROR', error.message)
+    return {
+      kind: 'transport',
+      code: lifecycleCode(error.phase),
+      message: error.message,
+      phase: error.phase,
+      context,
+    }
+  }
+  if (error instanceof ResponseError) {
+    return {
+      kind: 'response',
+      code: error.code,
+      message: error.message,
+      ...(error.reason === undefined ? {} : { reason: error.reason }),
+    }
+  }
+  if (error instanceof ClientError) {
+    const failure = sessionFailure(error)
+    if (failure !== undefined) return simple(lifecycleCode(failure), error.message)
+  }
+  if (error instanceof ProtocolError) return simple('PROTOCOL_ERROR', error.message)
+  if (error instanceof NodeUnavailableError)
+    return simple(
+      'NODE_UNAVAILABLE',
+      error.message,
+      'If this is a callable Path, use `astrale call` or `astrale introspect`.',
+    )
+  if (error instanceof PathError) return simple('PATH_INVALID', error.message)
+  if (error instanceof AuthValueError) return simple('AUTH_VALUE_INVALID', error.message)
+  if (error instanceof ClientError) return simple('CLIENT_ERROR', error.message)
+  return simple('UNEXPECTED_ERROR', 'The CLI encountered an unexpected internal failure.')
+}
+
+type TransportCode = Extract<FailureDiagnostic, { kind: 'transport' }>['code']
+type SessionFailure = 'cancelled' | 'closed' | 'timeout'
+
+function lifecycleCode(value: TransportError['phase']): TransportCode
+function lifecycleCode(value: SessionFailure): string
+function lifecycleCode(value: TransportError['phase'] | SessionFailure): string {
+  if (value === 'connect') return 'CONNECTION_ERROR'
+  if (value === 'timeout') return 'TIMEOUT'
+  if (value === 'closed') return 'DISCONNECTED'
+  return value === 'cancelled' ? 'CANCELLED' : 'TRANSPORT_ERROR'
+}
+
+function transportContext(error: TransportError): TransportDiagnosticContext | undefined {
+  const evidence = error as TransportError & {
+    readonly context?: unknown
+    readonly delivery?: unknown
+    readonly invocation?: unknown
+  }
+  if (record(evidence.context)) {
+    if (
+      evidence.context.kind === 'acquisition' &&
+      (evidence.context.resource === 'publication' || evidence.context.resource === 'bundle')
+    ) {
+      return { kind: 'acquisition', resource: evidence.context.resource }
+    }
+    if (
+      evidence.context.kind === 'invocation' &&
+      (evidence.context.delivery === 'not-sent' || evidence.context.delivery === 'unknown')
+    ) {
+      return {
+        kind: 'invocation',
+        delivery: evidence.context.delivery,
+        ...(evidence.context.invocation === undefined
+          ? {}
+          : { invocation: evidence.context.invocation }),
+      }
+    }
+  }
+  if (evidence.delivery !== 'not-sent' && evidence.delivery !== 'unknown') return undefined
+  return {
+    kind: 'invocation',
+    delivery: evidence.delivery,
+    ...(evidence.invocation === undefined ? {} : { invocation: evidence.invocation }),
+  }
+}
+
+function sessionFailure(error: ClientError): SessionFailure | undefined {
+  const failure = (error as ClientError & { readonly failure?: unknown }).failure
+  return failure === 'cancelled' || failure === 'closed' || failure === 'timeout'
+    ? failure
+    : undefined
+}
+
+function record(input: unknown): input is Readonly<Record<string, unknown>> {
+  return input !== null && typeof input === 'object' && !Array.isArray(input)
+}
+
+const simple = (code: string, message: string, hint?: string): FailureDiagnostic => ({
+  kind: 'simple',
+  code,
+  message,
+  ...(hint === undefined ? {} : { hint }),
+})

package/src/connection/failure/debug.ts

@@ -0,0 +1,26 @@
+import chalk from 'chalk'
+
+const MAXIMUM_DEBUG_FAILURES = 32
+
+export function printFailureDebug(error: unknown, url: string): void {
+  process.stderr.write(`\n${chalk.dim('── debug ─────────────────')}\n`)
+  if (url) process.stderr.write(`${chalk.dim(`url:   ${url}`)}\n`)
+  const seen = new Set<unknown>()
+  const pending: Array<{ value: unknown; relation: string }> = [{ value: error, relation: 'error' }]
+  while (pending.length > 0 && seen.size < MAXIMUM_DEBUG_FAILURES) {
+    const { value, relation } = pending.shift()!
+    if (seen.has(value)) continue
+    seen.add(value)
+    if (!(value instanceof Error)) {
+      process.stderr.write(`${chalk.dim(`${relation}: ${String(value)}`)}\n`)
+      continue
+    }
+    process.stderr.write(
+      `${chalk.dim(`${relation}: ${value.constructor.name}: ${value.message}`)}\n`,
+    )
+    if (value.stack) process.stderr.write(`${chalk.dim(value.stack)}\n`)
+    if (value.cause !== undefined) pending.push({ value: value.cause, relation: 'caused by' })
+    if (value instanceof AggregateError)
+      for (const child of value.errors) pending.push({ value: child, relation: 'aggregate' })
+  }
+}

package/src/connection/failure/index.ts

@@ -0,0 +1,18 @@
+import type { OperationRecovery } from '../command'
+
+import { classifyFailure } from './classify'
+import { printFailureDebug } from './debug'
+import { renderFailure } from './render'
+
+export { functionInputIssues, schemaUpgradeHint } from '../reasons'
+
+export async function formatKernelError(
+  error: unknown,
+  machine: boolean,
+  urlArg = '',
+  debug = false,
+  options: { recovery?: OperationRecovery } = {},
+): Promise<void> {
+  renderFailure(classifyFailure(error), machine, urlArg, options.recovery)
+  if (debug) printFailureDebug(error, urlArg)
+}

package/src/connection/failure/model.ts

@@ -0,0 +1,28 @@
+export type TransportDiagnosticContext =
+  | { readonly kind: 'acquisition'; readonly resource: 'publication' | 'bundle' }
+  | {
+      readonly kind: 'invocation'
+      readonly delivery: 'not-sent' | 'unknown'
+      readonly invocation?: unknown
+    }
+
+export type FailureDiagnostic =
+  | {
+      readonly kind: 'simple'
+      readonly code: string
+      readonly message: string
+      readonly hint?: string
+    }
+  | {
+      readonly kind: 'response'
+      readonly code: number
+      readonly message: string
+      readonly reason?: unknown
+    }
+  | {
+      readonly kind: 'transport'
+      readonly code: 'CONNECTION_ERROR' | 'DISCONNECTED' | 'TIMEOUT' | 'TRANSPORT_ERROR'
+      readonly message: string
+      readonly phase: string
+      readonly context: TransportDiagnosticContext
+    }

package/src/connection/failure/render.ts

@@ -0,0 +1,116 @@
+import chalk from 'chalk'
+
+import type { OperationRecovery } from '../command'
+import type { FailureDiagnostic } from './model'
+
+import { log } from '../../lib/log'
+import {
+  functionInputIssues,
+  queryInputRepair,
+  reasonCode,
+  schemaDataRemovalHint,
+  schemaUpgradeDetails,
+  schemaUpgradeHint,
+} from '../reasons'
+
+export function renderFailure(
+  failure: FailureDiagnostic,
+  machine: boolean,
+  url: string,
+  recovery: OperationRecovery | undefined,
+): void {
+  if (failure.kind === 'transport') return renderTransport(failure, machine, url, recovery)
+  if (failure.kind === 'response') return renderResponse(failure, machine)
+  if (machine)
+    return writeRaw({ error: failure.code, message: failure.message, hint: failure.hint })
+  log.error(`${chalk.bold(failure.code)}: ${failure.message}`)
+  if (failure.hint) log.dim(`  ${failure.hint}`)
+}
+
+function renderTransport(
+  failure: Extract<FailureDiagnostic, { kind: 'transport' }>,
+  machine: boolean,
+  url: string,
+  recovery: OperationRecovery | undefined,
+): void {
+  const invocation = failure.context.kind === 'invocation' ? failure.context : undefined
+  if (machine) {
+    writeRaw({
+      error: failure.code,
+      message: failure.message,
+      phase: failure.phase,
+      transport: failure.context,
+      ...(url === '' ? {} : { url }),
+      ...(invocation?.delivery === 'unknown' && recovery !== undefined ? recovery : {}),
+    })
+    return
+  }
+  log.error(`${chalk.bold(failure.code)}: ${failure.message}`)
+  if (url) log.dim(`  target: ${url}`)
+  log.dim(`  phase: ${failure.phase}`)
+  if (failure.phase === 'connect') log.dim('  Check the target and run `astrale status`.')
+  else if (failure.phase === 'timeout') log.dim('  Try increasing `--timeout`.')
+  else if (invocation?.delivery === 'unknown') renderRecovery(recovery)
+}
+
+function renderResponse(
+  failure: Extract<FailureDiagnostic, { kind: 'response' }>,
+  machine: boolean,
+): void {
+  const code = reasonCode(failure.reason)
+  const issues = functionInputIssues(failure.reason)
+  const removalHint = schemaDataRemovalHint(failure.reason)
+  const addressNotPublic = code === 'SCHEMA_DOMAIN_ADDRESS_NOT_PUBLIC'
+  const upgrade = schemaUpgradeDetails(failure.reason)
+  const message = addressNotPublic
+    ? 'Expose the Domain through a public HTTPS URL or public tunnel, then retry.'
+    : removalHint && !machine
+      ? 'Existing business data still uses schema definitions being removed.'
+      : failure.message
+  const hint =
+    code === 'FUNCTION_INPUT_INVALID' && (machine || issues.length === 0)
+      ? 'Use `astrale introspect <path>` to see the callable input.'
+      : (removalHint ?? (upgrade ? schemaUpgradeHint(upgrade) : undefined))
+  if (machine) {
+    writeRaw({
+      error: 'RESPONSE_ERROR',
+      code: failure.code,
+      message,
+      ...(failure.reason === undefined ? {} : { reason: failure.reason }),
+      ...(hint === undefined ? {} : { hint }),
+    })
+    return
+  }
+  const label = addressNotPublic
+    ? 'SCHEMA_DOMAIN_ADDRESS_NOT_PUBLIC'
+    : removalHint
+      ? 'DATA_MIGRATION_REQUIRED'
+      : `RESPONSE_ERROR(${failure.code})`
+  log.error(`${chalk.bold(label)}: ${message}`)
+  if (code && !addressNotPublic && !removalHint) log.dim(`  reason: ${code}`)
+  for (const issue of issues)
+    console.log(
+      chalk.red(`  ${issue.path || '<input>'}: ${issue.message} (${chalk.dim(issue.code)})`),
+    )
+  const repair = queryInputRepair(failure.reason)
+  if (repair?.phase === 'plan') log.dim(`  ${repair.path ?? '/'}  ${repair.issue}`)
+  else if (repair?.phase === 'limit')
+    log.dim(`  ${repair.path ?? '/'}  ${repair.limit} limit ${repair.actual}/${repair.maximum}`)
+  else if (repair) log.dim(`  ${repair.path}  ${repair.phase} input`)
+  if (upgrade?.issue === 'issuer-changed') {
+    log.dim(`  installed issuer: ${upgrade.installedIssuer}`)
+    log.dim(`  replacement issuer: ${upgrade.replacementIssuer}`)
+  }
+  if (hint) log.dim(`  ${hint}`)
+}
+
+function renderRecovery(recovery: OperationRecovery | undefined): void {
+  if (!recovery)
+    return log.dim('  Delivery is unknown; do not automatically retry a mutating call.')
+  log.dim('  Delivery is unknown; retry with the same operation id:')
+  log.dim(`  operation: ${recovery.operation}`)
+  log.dim(`  ${recovery.retry}`)
+}
+
+const writeRaw = (payload: Record<string, unknown>): void =>
+  void process.stderr.write(`${JSON.stringify(payload)}\n`)

package/src/connection/reasons.ts

@@ -150,6 +150,22 @@ export function schemaUpgradeHint(details: SchemaUpgradeDetails): string {
   )
 }
 
+export function schemaDataRemovalHint(reason: unknown): string | undefined {
+  if (!reasonWithCode(reason, 'DATA_MIGRATION_REQUIRED')) return undefined
+  const requirements = reason.details.requirements
+  if (
+    !Array.isArray(requirements) ||
+    requirements.length === 0 ||
+    !requirements.every(
+      (item) =>
+        record(item) && item.operation === 'remove-facts' && item.reason === 'destructive-change',
+    )
+  ) {
+    return undefined
+  }
+  return 'Delete this data explicitly, then retry. No data was deleted.'
+}
+
 function reasonWithCode(
   input: unknown,
   code: string,

package/src/connection/self.ts

@@ -1,7 +1,9 @@
-import type { KernelCommandOpts } from './command'
+import { NodeUnavailableError } from '@astrale-os/sdk/client'
 
+import type { ConnectionContext } from './session'
+
+import { AstraleError } from '../errors'
 import { containsSelfRef, expandSelfReferences } from '../lib/self'
-import { withClientSession } from './session'
 
 /** Metadata attached to errors after an authenticated caller-authored @self expansion. */
 export interface SelfExpansionMeta {
@@ -12,7 +14,7 @@ export interface SelfExpansionMeta {
 }
 
 /**
- * Run `action`; if it throws a node NotFoundError, retain the authenticated
+ * Run `action`; if it throws NodeUnavailableError, retain the authenticated
  * expansion for precise diagnostics. The error is re-thrown either way.
  */
 export async function withSelfHint<T>(
@@ -23,7 +25,7 @@ export async function withSelfHint<T>(
   try {
     return await action()
   } catch (err) {
-    if (err instanceof Error && err.name === 'NotFoundError') {
+    if (err instanceof NodeUnavailableError) {
       ;(err as Error & { expandedFromSelf?: SelfExpansionMeta }).expandedFromSelf = meta
     }
     throw err
@@ -36,40 +38,39 @@ type AuthenticatedSelf = {
 }
 
 export type ResolveSelfIdDependencies = {
-  readonly whoami?: (opts: KernelCommandOpts) => Promise<AuthenticatedSelf>
+  readonly whoami?: (context: ConnectionContext) => Promise<AuthenticatedSelf>
 }
 
 /** Resolve @self only from the effective principal authenticated by the selected Kernel. */
 export async function resolveSelfIdAuthenticated(
-  opts: KernelCommandOpts,
+  context: ConnectionContext,
   dependencies: ResolveSelfIdDependencies = {},
 ): Promise<{ readonly id: string; readonly slug?: string }> {
-  const resolved = await (dependencies.whoami ?? whoamiSelfId)(opts)
+  const resolved = await (dependencies.whoami ?? whoamiSelfId)(context)
   if (typeof resolved.id !== 'string' || resolved.id.trim().length === 0) {
-    const error = new Error(
+    throw new AstraleError(
+      'SELF_RESOLUTION_FAILED',
       '`@self` could not be resolved: authenticated Identity.whoami returned no NodeId.',
     )
-    error.name = 'SelfResolutionError'
-    throw error
   }
   return resolved.slug === undefined
     ? { id: resolved.id }
     : { id: resolved.id, slug: resolved.slug }
 }
 
-async function whoamiSelfId(opts: KernelCommandOpts): Promise<AuthenticatedSelf> {
-  return withClientSession(opts, async ({ auth, target }) => ({
+async function whoamiSelfId({ auth, target }: ConnectionContext): Promise<AuthenticatedSelf> {
+  return {
     ...(await auth.whoami()),
     ...(target.slug === undefined ? {} : { slug: target.slug }),
-  }))
+  }
 }
 
 /** Expand @self in path-like commands and return metadata for NotFound diagnostics. */
 export async function expandSelfInPath(
   path: string,
-  options: KernelCommandOpts,
+  context: ConnectionContext,
 ): Promise<{ readonly path: string; readonly meta?: SelfExpansionMeta }> {
-  const expanded = await expandSelfValues(path, [], options)
+  const expanded = await expandSelfValues(path, [], context)
   return expanded.meta === undefined
     ? { path: expanded.path }
     : { path: expanded.path, meta: expanded.meta }
@@ -78,20 +79,37 @@ export async function expandSelfInPath(
 /** Expand @self once across one Call path and its CLI-authored string parameters. */
 export async function expandSelfInCall(
   path: string,
-  parameters: readonly string[],
-  options: KernelCommandOpts,
+  parameters: Readonly<Record<string, unknown>>,
+  context: ConnectionContext,
 ): Promise<{
   readonly path: string
-  readonly parameters: readonly string[]
+  readonly parameters: Readonly<Record<string, unknown>>
   readonly meta?: SelfExpansionMeta
 }> {
-  return expandSelfValues(path, parameters, options)
+  const values = Object.values(parameters).filter(
+    (value): value is string => typeof value === 'string',
+  )
+  const expanded = await expandSelfValues(path, values, context)
+  if (expanded.parameters === values) {
+    return expanded.meta === undefined
+      ? { path: expanded.path, parameters }
+      : { path: expanded.path, parameters, meta: expanded.meta }
+  }
+  let index = 0
+  const entries = Object.entries(parameters).map(([key, value]) => [
+    key,
+    typeof value === 'string' ? expanded.parameters[index++] : value,
+  ])
+  const resolved = Object.freeze(Object.fromEntries(entries))
+  return expanded.meta === undefined
+    ? { path: expanded.path, parameters: resolved }
+    : { path: expanded.path, parameters: resolved, meta: expanded.meta }
 }
 
 async function expandSelfValues(
   path: string,
   parameters: readonly string[],
-  options: KernelCommandOpts,
+  context: ConnectionContext,
 ): Promise<{
   readonly path: string
   readonly parameters: readonly string[]
@@ -100,7 +118,7 @@ async function expandSelfValues(
   if (!containsSelfRef(path) && !parameters.some(containsSelfRef)) {
     return { path, parameters }
   }
-  const self = await resolveSelfIdAuthenticated(options)
+  const self = await resolveSelfIdAuthenticated(context)
   const expandedPath = expandSelfReferences(path, self.id)
   const expandedParameters = parameters.map((parameter) => expandSelfReferences(parameter, self.id))
   const changed =

package/src/connection/session.ts

@@ -1,11 +1,11 @@
-import type { AuthApi } from '@astrale-os/kernel-client/auth'
-import type { GraphApi } from '@astrale-os/kernel-client/graph'
-import type { ClientSessionOptions, SessionAuth } from '@astrale-os/kernel-client/session'
-
-import { call } from '@astrale-os/kernel-client'
-import { createAuth } from '@astrale-os/kernel-client/auth'
-import { createGraph } from '@astrale-os/kernel-client/graph'
-import { ClientSession } from '@astrale-os/kernel-client/session'
+import type { AuthApi } from '@astrale-os/sdk/auth'
+import type { GraphApi } from '@astrale-os/sdk/client'
+import type { ClientSessionOptions, SessionAuth } from '@astrale-os/sdk/client/session'
+
+import { createAuth } from '@astrale-os/sdk/auth'
+import { call } from '@astrale-os/sdk/client'
+import { createGraph } from '@astrale-os/sdk/client'
+import { ClientSession } from '@astrale-os/sdk/client/session'
 
 import type { AstraleConfig } from '../lib/config'
 import type { AdminConnectionOptions, ConnectionOptions, ConnectionTarget } from './target'

package/src/errors.ts

@@ -2,8 +2,9 @@ export class AstraleError extends Error {
   code: string
   hint?: string
 
-  constructor(code: string, message: string, hint?: string) {
-    super(message)
+  constructor(code: string, message: string, hint?: string, options?: ErrorOptions) {
+    if (message.trim() === '') throw new TypeError('CLI error message must be non-blank.')
+    super(message, options)
     this.name = 'AstraleError'
     this.code = code
     this.hint = hint

package/src/graph/.spec/api.d.ts

@@ -1,7 +1,14 @@
+import type { ClassKey, ClassRef } from '@astrale-os/sdk/graph/class'
 import type { MutationAST } from '@astrale-os/sdk/mutation'
 import type { QueryAST, QueryDirection } from '@astrale-os/sdk/query'
 
-/** Untrusted CLI fields used to author or admit one exact Query V5 request. */
+/** Admit one canonical Domain-rooted Class Path into its DSL coordinate. */
+export function classReference(input: string, label: string): ClassRef
+
+/** Admit one canonical Domain-rooted Class Path into its exact string identity. */
+export function classKey(input: string, label: string): ClassKey
+
+/** Untrusted CLI fields used to author or admit one exact Query V6 request. */
 export interface QueryCommandInput {
   readonly sources: readonly string[]
   readonly definition?: string
@@ -12,16 +19,16 @@ export interface QueryCommandInput {
   readonly cursor?: string
 }
 
-/** Canonical query plus the caller-bound continuation token kept outside the AST. */
+/** Canonical query plus caller-bound pagination kept outside the AST. */
 export interface PreparedQuery {
   readonly ast: QueryAST
-  readonly cursor?: string
+  readonly page: Readonly<{ readonly size: number; readonly after?: string }>
 }
 
-/** Admit canonical Query V5 or author its supported Path/Definition/one-edge CLI subset. */
+/** Admit canonical Query V6 or author its supported Path/Class/one-edge CLI subset. */
 export function prepareQuery(input: QueryCommandInput): PreparedQuery
 
-/** Admit canonical Mutation V2 or its exact authoring input; legacy PatchData is rejected. */
+/** Admit canonical Mutation V3 or its exact authoring input; legacy PatchData is rejected. */
 export function prepareMutation(input: unknown): MutationAST
 
 /** Return the user-facing leaf of one exact qualified Property key. */

package/src/graph/.spec/layout.ts

@@ -1,6 +1,14 @@
 import { defineLayout } from '@astrale-os/spec/authoring'
 
 export default defineLayout({
-  entries: ['__tests__/', 'index.ts', 'mutation.ts', 'projection.ts', 'query.ts', 'tsconfig.json'],
+  entries: [
+    '__tests__/',
+    'class.ts',
+    'index.ts',
+    'mutation.ts',
+    'projection.ts',
+    'query.ts',
+    'tsconfig.json',
+  ],
   exact: true,
 })

package/src/graph/__tests__/mutation.test.ts

@@ -14,7 +14,7 @@ describe('prepareMutation', () => {
               {
                 op: 'node.create',
                 as: 'note',
-                class: '/:notes.example.dev:class.Note',
+                class: 'notes.example.dev:class.Note',
                 props: {},
               },
             ],
@@ -29,7 +29,7 @@ describe('prepareMutation', () => {
         {
           op: 'node.create',
           as: 'note',
-          class: '/:notes.example.dev:class.Note',
+          class: 'notes.example.dev:class.Note',
           props: {},
         },
       ],

package/src/graph/__tests__/query.test.ts

@@ -38,7 +38,7 @@ describe('prepareQuery', () => {
   })
 
   /** @evidence TEST-CLI-GRAPH-AUTHORS-DEFINITION-QUERY */
-  test('authors an exact Definition source without backend query text', () => {
+  test('authors an exact Class source without backend query text', () => {
     const prepared = prepareQuery({
       sources: [],
       definition: '/:issues.astrale.ai:class.Issue',
@@ -52,8 +52,8 @@ describe('prepareQuery', () => {
         kind: 'node',
         terms: [
           {
-            kind: 'definition',
-            definition: { origin: 'issues.astrale.ai', kind: 'class', name: 'Issue' },
+            kind: 'class',
+            class: { origin: 'issues.astrale.ai', kind: 'class', name: 'Issue' },
           },
         ],
         binding: 'n0',
@@ -64,6 +64,25 @@ describe('prepareQuery', () => {
     expect(prepared.page).toEqual({ size: 201 })
   })
 
+  test('unions positional Paths and one Class source in authored order', () => {
+    const prepared = prepareQuery({
+      sources: ['@note'],
+      definition: '/:issues.astrale.ai:class.Issue',
+    })
+
+    expect(JSON.parse(JSON.stringify(prepared.ast.source))).toEqual({
+      kind: 'node',
+      terms: [
+        { kind: 'path', path: '@note' },
+        {
+          kind: 'class',
+          class: { origin: 'issues.astrale.ai', kind: 'class', name: 'Issue' },
+        },
+      ],
+      binding: 'n0',
+    })
+  })
+
   /** @evidence TEST-CLI-GRAPH-ADMITS-QUERY-V6-ORDERING */
   test('admits one exact Property-ordered Query V6 document', () => {
     const ast = {
@@ -73,8 +92,8 @@ describe('prepareQuery', () => {
         kind: 'node',
         terms: [
           {
-            kind: 'definition',
-            definition: { origin: 'notes.example.dev', kind: 'class', name: 'Note' },
+            kind: 'class',
+            class: { origin: 'notes.example.dev', kind: 'class', name: 'Note' },
           },
         ],
         binding: 'n0',
@@ -149,6 +168,6 @@ describe('prepareQuery', () => {
     ).toThrow('--limit must be a positive integer')
     expect(() =>
       prepareQuery({ sources: [], definition: '/:notes.example.dev:view.note' }),
-    ).toThrow('--definition must be one canonical Class or Interface Path')
+    ).toThrow('--definition must be one canonical Class Path')
   })
 })

package/src/graph/class.ts

@@ -0,0 +1,30 @@
+import type { ClassKey as ClassKeyValue, ClassRef } from '@astrale-os/sdk/graph/class'
+
+import { ClassKey } from '@astrale-os/sdk/graph/class'
+import { Path } from '@astrale-os/sdk/graph/path'
+
+/** Admit one canonical Domain-rooted Class Path into its DSL coordinate. */
+export function classReference(input: string, label: string): ClassRef {
+  const path = Path.parse(input)
+  const step = path.ast.steps[0]
+  if (
+    path.ast.anchor.kind !== 'domain' ||
+    path.ast.steps.length !== 1 ||
+    step?.kind !== 'projection' ||
+    step.projection.kind !== 'class'
+  ) {
+    throw new TypeError(`${label} must be one canonical Class Path`)
+  }
+  return ClassKey.ref(
+    ClassKey.of({
+      origin: path.ast.anchor.origin,
+      kind: 'class',
+      name: step.projection.name,
+    }),
+  )
+}
+
+/** Admit one canonical Domain-rooted Class Path into its exact string identity. */
+export function classKey(input: string, label: string): ClassKeyValue {
+  return ClassKey.of(classReference(input, label))
+}

package/src/graph/index.ts

@@ -1,3 +1,4 @@
+export { classKey, classReference } from './class'
 export { prepareMutation } from './mutation'
 export { nodeProperty, unqualifyProperty } from './projection'
 export { prepareQuery, type PreparedQuery, type QueryCommandInput } from './query'