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

package/src/connection/exchange.ts

@@ -1,9 +1,9 @@
-import type { Fetch } from '@astrale-os/kernel-client'
 import type { IssuerId } from '@astrale-os/sdk/auth'
+import type { Fetch } from '@astrale-os/sdk/client'
 
-import { call, Client } from '@astrale-os/kernel-client'
-import { createAuth } from '@astrale-os/kernel-client/auth'
+import { createAuth } from '@astrale-os/sdk/auth'
 import { credential, exchange as exchangeProtocol } from '@astrale-os/sdk/auth'
+import { call, Client } from '@astrale-os/sdk/client'
 
 import type { SourceCredentialResolver } from './credential'
 import type { ConnectionTarget } from './target'
@@ -33,12 +33,13 @@ export function createExchangeCredentialResolver(
       const client = new Client({ url: `${kernelIssuer}/invoke`, fetch, timeoutMs })
       try {
         const authenticated = client.as(sourceToken)
-        const auth = createAuth((path, input, options) =>
-          authenticated.call(call(path, input), {
+        const auth = createAuth(async (path, input, options) => {
+          const result = await authenticated.call(call(path, input), {
             ...options,
             delegate: { ttlSeconds: delegationTtlSeconds },
-          }),
-        )
+          })
+          return result.value
+        })
         const user = await auth.whoami({ signal })
         const key = Object.freeze({
           kernelIssuer,
@@ -110,15 +111,20 @@ async function exchange(
     exchangeProtocol.paths(domainIssuer).configuration,
     domainIssuer,
   ).toString()
-  const configurationResponse = await fetch(configurationUrl, {
-    method: 'GET',
-    redirect: 'error',
-    credentials: 'omit',
-    cache: 'no-store',
-    referrerPolicy: 'no-referrer',
-    headers: { accept: 'application/json' },
-    signal,
-  })
+  const configurationResponse = await fetchExchange(
+    fetch,
+    configurationUrl,
+    {
+      method: 'GET',
+      redirect: 'error',
+      credentials: 'omit',
+      cache: 'no-store',
+      referrerPolicy: 'no-referrer',
+      headers: { accept: 'application/json' },
+      signal,
+    },
+    'Domain issuer discovery could not be reached.',
+  )
   if (!configurationResponse.ok) {
     throw new AstraleError(
       'TOKEN_EXCHANGE_DISCOVERY_FAILED',
@@ -138,18 +144,23 @@ async function exchange(
     )
   }
 
-  const response = await fetch(endpoint, {
-    method: 'POST',
-    redirect: 'error',
-    credentials: 'omit',
-    cache: 'no-store',
-    referrerPolicy: 'no-referrer',
-    headers: {
-      authorization: `Bearer ${envelope}`,
-      accept: exchangeProtocol.MEDIA_TYPE,
+  const response = await fetchExchange(
+    fetch,
+    endpoint,
+    {
+      method: 'POST',
+      redirect: 'error',
+      credentials: 'omit',
+      cache: 'no-store',
+      referrerPolicy: 'no-referrer',
+      headers: {
+        authorization: `Bearer ${envelope}`,
+        accept: exchangeProtocol.MEDIA_TYPE,
+      },
+      signal,
     },
-    signal,
-  })
+    'Domain token exchange could not be reached.',
+  )
   const body = await boundedJson(response, signal)
   if (!response.ok) {
     let admitted: exchangeProtocol.ErrorResponse
@@ -192,6 +203,20 @@ async function exchange(
   return Object.freeze({ credential: exchanged.token, expiresAt: exchanged.expiresAt })
 }
 
+async function fetchExchange(
+  fetch: Fetch,
+  input: string,
+  init: RequestInit,
+  message: string,
+): Promise<Response> {
+  try {
+    return await fetch(input, init)
+  } catch (cause) {
+    if (init.signal?.aborted) throw cause
+    throw new AstraleError('TOKEN_EXCHANGE_UNAVAILABLE', message, undefined, { cause })
+  }
+}
+
 function requireExchangeTransport(
   target: ConnectionTarget & { readonly domainIssuer: IssuerId },
 ): void {

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/index.ts

@@ -0,0 +1,18 @@
+import type { OperationRecovery } from '../command'
+
+import { printFailureDebug } from '../../lib/failure-debug'
+import { classifyFailure } from './classify'
+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 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 { 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 { 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'
@@ -21,6 +21,7 @@ import { fetchWithCaFile } from '../lib/ca-fetch'
 import { readConfig } from '../lib/config'
 import { log } from '../lib/log'
 import { isMachine } from '../lib/output'
+import { bindCredentialIdentity } from './auth'
 import { createCliCredential, validateCredentialSelection } from './credential'
 import { resolveAdminConnectionTarget, resolveConnectionTarget } from './target'
 
@@ -38,6 +39,8 @@ export interface ConnectionContext {
   readonly graph: GraphApi
   readonly auth: AuthApi
   readonly target: ConnectionTarget
+  /** Local identity label selected for this session; absent for raw credentials or anonymous use. */
+  readonly identity?: string
 }
 
 interface OwnedConnection {
@@ -63,6 +66,7 @@ export async function withClientSession<Value>(
   const target = await resolveConnectionTarget(options, config, {
     managed: (slug) => lookupManagedInstance(slug, options),
   })
+  options = await bindCredentialIdentity(options, target)
   warnMissingExplicitTarget(options, target)
   return runResolvedClientSession(target, timeoutMs, options, config, action, openConnection)
 }
@@ -76,6 +80,7 @@ export async function withAdminClientSession<Value>(
   const timeoutMs = resolveTimeoutMs(options.timeout)
   const config = await readConfig()
   const target = await resolveAdminConnectionTarget(options, config)
+  options = await bindCredentialIdentity(options, target)
   return runResolvedClientSession(target, timeoutMs, options, config, action, openConnection)
 }
 
@@ -141,7 +146,13 @@ function openConnection(
   const graph = createGraph((call, request) => session.call(call, request))
   const authApi = createAuth((path, input, request) => session.call(call(path, input), request))
   return {
-    context: Object.freeze({ session, graph, auth: authApi, target }),
+    context: Object.freeze({
+      session,
+      graph,
+      auth: authApi,
+      target,
+      ...(options.as === undefined ? {} : { identity: options.as }),
+    }),
     close() {
       session.close()
     },

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. */