@astrale-os/cli 0.8.1-alpha.2 → 0.8.1-alpha.3

package/dist/astrale.js

@@ -2576,7 +2576,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@astrale-os/cli",
-    version: "0.8.1-alpha.2",
+    version: "0.8.1-alpha.3",
     description: "Astrale CLI — connect to existing Astrale kernels",
     keywords: [
       "astrale",
@@ -90137,6 +90137,9 @@ var init_mutation2 = __esm(() => {
 
 // src/graph/mutation.ts
 function prepareMutation(input) {
+  if (isLegacyPatchData(input)) {
+    throw new TypeError("Legacy PatchData { nodes, edges } is not Mutation V3. Author { preconditions, operations } or a canonical astrale.graph.mutation/v3 document.");
+  }
   if (isCanonicalCandidate(input))
     return MutationAST.decode(input);
   return MutationAST.create(input);
@@ -90144,6 +90147,9 @@ function prepareMutation(input) {
 function isCanonicalCandidate(input) {
   return input !== null && typeof input === "object" && !Array.isArray(input) && (Object.hasOwn(input, "format") || Object.hasOwn(input, "version"));
 }
+function isLegacyPatchData(input) {
+  return input !== null && typeof input === "object" && !Array.isArray(input) && !Object.hasOwn(input, "operations") && (Object.hasOwn(input, "nodes") || Object.hasOwn(input, "edges"));
+}
 var init_mutation3 = __esm(() => {
   init_mutation2();
 });
@@ -90308,6 +90314,99 @@ var init_binary4 = __esm(() => {
   init_output();
 });
 
+// src/commands/call-describe.ts
+function describeCallableFromSchema(path5, schema2) {
+  if (path5.ast.anchor.kind !== "domain")
+    return;
+  const origin = path5.ast.anchor.origin;
+  const last = path5.ast.steps.at(-1);
+  const document = asRecord2(schema2);
+  if (document === undefined || last === undefined)
+    return;
+  if (last.kind === "method") {
+    const owner = path5.ast.steps.at(-2);
+    if (owner?.kind === "projection" && (owner.projection.kind === "class" || owner.projection.kind === "interface")) {
+      const bag = asRecord2(owner.projection.kind === "class" ? document.classes : document.interfaces);
+      const definition3 = asRecord2(bag?.[owner.projection.name]);
+      const method = asRecord2(asRecord2(definition3?.methods)?.[last.name]);
+      if (method !== undefined) {
+        return Object.freeze({
+          path: path5.raw,
+          origin,
+          class: owner.projection.name,
+          method: last.name,
+          dispatch: last.dispatch,
+          ...callableFields(method)
+        });
+      }
+    }
+    const matches3 = findNamedMethods(document, origin, path5.raw, last.name, last.dispatch);
+    if (matches3.length === 1)
+      return matches3[0];
+    if (matches3.length > 1) {
+      return Object.freeze({
+        path: path5.raw,
+        origin,
+        method: last.name,
+        dispatch: last.dispatch,
+        candidates: Object.freeze(matches3)
+      });
+    }
+    return;
+  }
+  if (last.kind === "projection" && last.projection.kind === "function") {
+    const fn2 = asRecord2(asRecord2(document.functions)?.[last.projection.name]);
+    if (fn2 === undefined)
+      return;
+    return Object.freeze({
+      path: path5.raw,
+      origin,
+      function: last.projection.name,
+      ...callableFields(fn2)
+    });
+  }
+  return;
+}
+function missingCallableDescription(path5) {
+  return new AstraleError("CALL_DESCRIBE_UNAVAILABLE", `No callable schema is installed for ${path5}.`, "Use a Domain-rooted Path such as /:host.astrale.ai:class.Manager:createInstance. Method Paths are not Function nodes.");
+}
+function findNamedMethods(schema2, origin, path5, method, dispatch) {
+  const matches3 = [];
+  for (const bag of [schema2.classes, schema2.interfaces]) {
+    const definitions2 = asRecord2(bag);
+    if (definitions2 === undefined)
+      continue;
+    for (const [className, definition3] of Object.entries(definitions2)) {
+      const methodDef = asRecord2(asRecord2(asRecord2(definition3)?.methods)?.[method]);
+      if (methodDef === undefined)
+        continue;
+      matches3.push(Object.freeze({
+        path: path5,
+        origin,
+        class: className,
+        method,
+        dispatch,
+        ...callableFields(methodDef)
+      }));
+    }
+  }
+  return matches3;
+}
+function callableFields(value2) {
+  return {
+    ...typeof value2.description === "string" ? { description: value2.description } : {},
+    ...value2.auth === undefined ? {} : { auth: value2.auth },
+    ...value2.input === undefined ? {} : { input: value2.input },
+    ...value2.output === undefined ? {} : { output: value2.output }
+  };
+}
+function asRecord2(input) {
+  return input !== null && typeof input === "object" && !Array.isArray(input) ? input : undefined;
+}
+var init_call_describe = __esm(() => {
+  init_errors2();
+});
+
 // src/commands/call.ts
 var exports_call = {};
 __export(exports_call, {
@@ -90374,28 +90473,20 @@ async function describeOperation(path5, opts) {
   await runKernelCommand({
     opts,
     label: `Schema for ${path5}`,
-    fn: async ({ graph }) => await graph.get(Path.parse(path5)),
-    format: (node4, fmtOpts) => {
-      const input = nodeProperty(node4, "inputSchema");
-      const outputSchema = nodeProperty(node4, "outputSchema");
-      const schema2 = {};
-      if (input)
-        schema2.input = tryParseJson(input);
-      if (outputSchema)
-        schema2.output = tryParseJson(outputSchema);
-      output(Object.keys(schema2).length > 0 ? schema2 : node4, fmtOpts);
-    }
+    fn: async ({ graph }) => {
+      const parsed = Path.parse(path5);
+      if (parsed.ast.anchor.kind !== "domain") {
+        throw missingCallableDescription(path5);
+      }
+      const domain3 = await graph.getOrThrow(Path.parse(`/:${parsed.ast.anchor.origin}`));
+      const described = describeCallableFromSchema(parsed, nodeProperty(domain3, "schema"));
+      if (described === undefined)
+        throw missingCallableDescription(path5);
+      return described;
+    },
+    format: (schema2, fmtOpts) => output(schema2, fmtOpts)
   });
 }
-function tryParseJson(value2) {
-  if (typeof value2 !== "string")
-    return value2;
-  try {
-    return JSON.parse(value2);
-  } catch {
-    return value2;
-  }
-}
 async function parseParams(rawParams, dataFlag) {
   if (dataFlag) {
     if (rawParams.length > 0) {
@@ -90471,6 +90562,7 @@ var init_call2 = __esm(() => {
   init_binary4();
   init_log();
   init_output();
+  init_call_describe();
   PARAM_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
   call_default = {
     name: "call",
@@ -90490,16 +90582,19 @@ Self-reference:
   (e.g. via 'astrale get @self --json'). Resolution authenticates to
   the selected Kernel and never trusts a local registration or JWT sub.
 
+  --describe reads the callable's input/output from the installed Domain
+  schema. Method Paths are not Function nodes.
+
 Examples:
-  $ astrale call /:host.astrale.ai:class.KernelInstance:list
+  $ astrale call /:host.astrale.ai:class.Manager:createInstance --describe
   $ astrale call /:blog.acme.com:class.Author:list limit=10
   $ astrale call '@self::deactivate'
-  $ astrale call /:shell.astrale.ai:function.search-domains --json
+  $ astrale call /:kernel.astrale.ai:function.journal --data '{"limit":5}' --json
 `,
     arguments: [
       {
         name: "path",
-        description: "Operation path (e.g., /:host.astrale.ai:class.KernelInstance:list or /node::method)"
+        description: "Operation path (e.g., /:host.astrale.ai:class.Manager:createInstance or /node::method)"
       },
       { name: "params...", description: "Params as key=value pairs", required: false }
     ],
@@ -90597,7 +90692,7 @@ async function getCommand(target2, opts) {
   try {
     ({ path: path5, meta: meta3 } = await expandSelfInPath(target2, opts));
   } catch (error52) {
-    log.error(error52 instanceof Error ? error52.message : "Invalid target");
+    await formatKernelError(error52, isMachine(opts), undefined, opts.debug);
     process.exit(1);
   }
   await runKernelCommand({
@@ -90611,7 +90706,7 @@ var get_default;
 var init_get = __esm(() => {
   init_path5();
   init_connection2();
-  init_log();
+  init_errors12();
   init_output();
   get_default = {
     name: "get",
@@ -91173,24 +91268,37 @@ function printRecord(record10) {
 `);
 }
 function acceptRecord2(input, index) {
-  if (!isRecord8(input) || !Number.isSafeInteger(input.sequence) || typeof input.timestamp !== "string" || typeof input.topic !== "string") {
+  if (!isRecord8(input) || !Number.isSafeInteger(input.sequence) || typeof input.topic !== "string") {
     throw new TypeError(`Kernel journal record ${index} is invalid`);
   }
-  for (const key of ["principal", "correlationId", "causationId"]) {
-    if (input[key] !== undefined && typeof input[key] !== "string") {
-      throw new TypeError(`Kernel journal record ${index}.${key} must be text`);
-    }
+  const occurredAt = optionalText2(input.occurredAt, index, "occurredAt");
+  const timestamp = optionalText2(input.timestamp, index, "timestamp") ?? occurredAt;
+  if (timestamp === undefined) {
+    throw new TypeError(`Kernel journal record ${index} is missing occurredAt/timestamp`);
   }
+  const correlation = isRecord8(input.correlation) ? input.correlation : undefined;
+  const correlationId = optionalText2(input.correlationId, index, "correlationId") ?? optionalText2(correlation?.invocationId, index, "correlation.invocationId");
+  const principal = optionalText2(input.principal, index, "principal");
   return Object.freeze({
     sequence: input.sequence,
-    timestamp: input.timestamp,
+    timestamp,
     topic: input.topic,
     payload: input.payload,
-    ...input.principal === undefined ? {} : { principal: input.principal },
-    ...input.correlationId === undefined ? {} : { correlationId: input.correlationId },
-    ...input.causationId === undefined ? {} : { causationId: input.causationId }
+    ...occurredAt === undefined ? {} : { occurredAt },
+    ...optionalText2(input.committedAt, index, "committedAt") === undefined ? {} : { committedAt: input.committedAt },
+    ...principal === undefined ? {} : { principal },
+    ...correlationId === undefined ? {} : { correlationId },
+    ...optionalText2(input.causationId, index, "causationId") === undefined ? {} : { causationId: input.causationId }
   });
 }
+function optionalText2(input, index, field) {
+  if (input === undefined)
+    return;
+  if (typeof input !== "string") {
+    throw new TypeError(`Kernel journal record ${index}.${field} must be text`);
+  }
+  return input;
+}
 function positiveInteger3(flag, raw2) {
   if (!/^\d+$/.test(raw2))
     throw new TypeError(`${flag} must be a positive integer`);
@@ -92742,7 +92850,8 @@ Examples:
 var exports_list = {};
 __export(exports_list, {
   default: () => list_default,
-  buildInstanceRows: () => buildInstanceRows
+  buildInstanceRows: () => buildInstanceRows,
+  adminInventoryUnavailable: () => adminInventoryUnavailable
 });
 function buildInstanceRows(managed, bookmarks, show) {
   const rows = [];
@@ -92786,9 +92895,19 @@ function buildInstanceRows(managed, bookmarks, show) {
   }
   return rows;
 }
-var COLUMNS, list_default;
+function adminInventoryUnavailable(cause) {
+  const code = cause instanceof AstraleError ? cause.code : undefined;
+  if (code !== undefined && ADMIN_INVENTORY_CODES.has(code)) {
+    return new AstraleError("ADMIN_INVENTORY_UNAVAILABLE", "Managed instance listing needs the Admin Domain and an IdP-backed identity. Admin is not deployed in this environment.", "Use `astrale instance list --bookmarked` for local kernel bookmarks. Key-backed identities cannot mint an Admin Domain token.");
+  }
+  if (cause instanceof AstraleError)
+    return cause;
+  return new AstraleError("ADMIN_INVENTORY_UNAVAILABLE", cause instanceof Error ? cause.message : String(cause), "Use `astrale instance list --bookmarked` for local kernel bookmarks.");
+}
+var COLUMNS, list_default, ADMIN_INVENTORY_CODES;
 var init_list = __esm(() => {
   init_source();
+  init_errors2();
   init_admin_instance();
   init_admin_instance();
   init_admin_target();
@@ -92823,7 +92942,11 @@ var init_list = __esm(() => {
         }));
         let managed = [];
         if (!opts.bookmarked) {
-          managed = await withSpinner("Fetching instances", !isMachine(opts), () => listOwnedInstances(opts));
+          try {
+            managed = await withSpinner("Fetching instances", !isMachine(opts), () => listOwnedInstances(opts));
+          } catch (error52) {
+            throw adminInventoryUnavailable(error52);
+          }
         }
         if (isMachine(opts)) {
           output({
@@ -92848,6 +92971,15 @@ var init_list = __esm(() => {
       }
     }
   };
+  ADMIN_INVENTORY_CODES = new Set([
+    "TOKEN_EXCHANGE_SOURCE_INVALID",
+    "TOKEN_EXCHANGE_SOURCE_EXPIRED",
+    "TOKEN_EXCHANGE_UNSUPPORTED",
+    "TOKEN_EXCHANGE_DISCOVERY_FAILED",
+    "TOKEN_EXCHANGE_PROTOCOL_ERROR",
+    "TOKEN_EXCHANGE_INSECURE",
+    "ADMIN_DOMAIN_ISSUER_MISSING"
+  ]);
 });
 
 // src/commands/instance/bookmark.ts
@@ -93591,8 +93723,23 @@ __export(exports_install, {
   isIdentityOverride: () => isIdentityOverride,
   installViaAdmin: () => installViaAdmin,
   domainRefFromTarget: () => domainRefFromTarget,
+  directInstallCallInput: () => directInstallCallInput,
   default: () => install_default
 });
+function directInstallCallInput(url3, token, operation2 = crypto.randomUUID()) {
+  return Object.freeze({
+    operation: operation2,
+    domains: [
+      Object.freeze({
+        source: Object.freeze({
+          kind: "remote",
+          url: url3,
+          ...token === undefined ? {} : { token }
+        })
+      })
+    ]
+  });
+}
 async function installViaAdmin(target2, opts, dependencies = {}) {
   const admin = { ...defaultAdminInstallDependencies, ...dependencies };
   const interactive = !!process.stdin.isTTY && !(opts.ci || opts.noPrompt || process.env.CI);
@@ -93710,20 +93857,18 @@ async function installDirect(target2, opts) {
   await runKernelCommand({
     opts,
     label: `Installing domain from ${url3}`,
-    fn: async ({ session }) => await session.call(createPathCall(Path.project(exports_syscalls.install.ref).raw, {
-      domains: [{ url: url3, ...opts.token ? { token: opts.token } : {} }]
-    })),
+    fn: async ({ session }) => await session.call(createPathCall(Path.project(exports_syscalls.install.ref).raw, directInstallCallInput(url3, opts.token))),
     format: (result, fmtOpts, isRaw) => {
       if (isRaw) {
         output(result, fmtOpts);
         return;
       }
-      const installed = result[0];
-      if (!installed)
-        throw new Error("Kernel install returned no installed Domain receipt.");
-      log.success(`Domain installed: ${installed.origin}@${installed.revision}`);
-      if (installed.etag)
-        log.dim(`  publication: ${installed.etag}`);
+      const installed = result.transitions[0]?.intent;
+      if (installed === undefined) {
+        throw new Error("Kernel install returned no committed Domain transition.");
+      }
+      const revision = installed.target?.schemaRevision ?? result.operation;
+      log.success(`Domain installed: ${installed.origin}@${revision}`);
       if (isIdentityOverride(installed.origin, host) && installed.origin !== consentedOrigin) {
         log.warn(`Installed origin "${installed.origin}" differs from the serving host "${host}" ` + `and was not confirmed before install (the worker's /meta did not declare it). ` + `Every ${installed.origin}/* call on this instance now routes to ${host}.`);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/cli",
-  "version": "0.8.1-alpha.2",
+  "version": "0.8.1-alpha.3",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",

package/src/commands/__tests__/call-describe.test.ts

@@ -0,0 +1,67 @@
+import { Path } from '@astrale-os/sdk/graph/path'
+import { describe, expect, test } from 'bun:test'
+
+import { describeCallableFromSchema } from '../call-describe'
+
+const schema = {
+  classes: {
+    Manager: {
+      methods: {
+        createInstance: {
+          auth: 'authorized',
+          description: 'Create one child Instance.',
+          input: { type: 'object', required: ['operationId', 'slug'] },
+          output: { mode: 'value' },
+        },
+      },
+    },
+  },
+  functions: {
+    journal: {
+      description: 'Read the authorized Kernel journal.',
+      input: { type: 'object' },
+    },
+  },
+}
+
+describe('describeCallableFromSchema', () => {
+  test('reads a static Class method from the Domain schema', () => {
+    const described = describeCallableFromSchema(
+      Path.parse('/:host.astrale.ai:class.Manager:createInstance'),
+      schema,
+    )
+    expect(described).toMatchObject({
+      origin: 'host.astrale.ai',
+      class: 'Manager',
+      method: 'createInstance',
+      dispatch: 'static',
+      description: 'Create one child Instance.',
+      auth: 'authorized',
+    })
+    expect(described?.input).toMatchObject({ required: ['operationId', 'slug'] })
+  })
+
+  test('finds an instance method when the receiver Path is not a Class projection', () => {
+    expect(
+      describeCallableFromSchema(
+        Path.parse('/:host.astrale.ai:core.manager::createInstance'),
+        schema,
+      ),
+    ).toMatchObject({
+      origin: 'host.astrale.ai',
+      class: 'Manager',
+      method: 'createInstance',
+      dispatch: 'instance',
+    })
+  })
+
+  test('reads a standalone Function from the Domain schema', () => {
+    expect(
+      describeCallableFromSchema(Path.parse('/:kernel.astrale.ai:function.journal'), schema),
+    ).toMatchObject({
+      origin: 'kernel.astrale.ai',
+      function: 'journal',
+      description: 'Read the authorized Kernel journal.',
+    })
+  })
+})

package/src/commands/__tests__/install-direct.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from 'bun:test'
+
+import { directInstallCallInput } from '../domain/install'
+
+describe('directInstallCallInput', () => {
+  test('sends the current remote install syscall, not a legacy url list', () => {
+    expect(directInstallCallInput('https://tasks.example.test', 'secret', 'op-1')).toEqual({
+      operation: 'op-1',
+      domains: [
+        {
+          source: {
+            kind: 'remote',
+            url: 'https://tasks.example.test',
+            token: 'secret',
+          },
+        },
+      ],
+    })
+  })
+})

package/src/commands/__tests__/instance-list-admin.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from 'bun:test'
+
+import { AstraleError } from '../../errors'
+import { adminInventoryUnavailable } from '../instance/list'
+
+describe('adminInventoryUnavailable', () => {
+  test('turns key-backed Admin exchange failures into a bookmark-only instruction', () => {
+    const error = adminInventoryUnavailable(
+      new AstraleError(
+        'TOKEN_EXCHANGE_SOURCE_INVALID',
+        'The source identity credential has no valid expiration.',
+      ),
+    )
+    expect(error.code).toBe('ADMIN_INVENTORY_UNAVAILABLE')
+    expect(error.message).toContain('Admin is not deployed')
+    expect(error.hint).toContain('instance list --bookmarked')
+  })
+
+  test('turns a missing Admin Domain issuer into the same instruction', () => {
+    const error = adminInventoryUnavailable(
+      new AstraleError('ADMIN_DOMAIN_ISSUER_MISSING', 'no Domain issuer'),
+    )
+    expect(error.code).toBe('ADMIN_INVENTORY_UNAVAILABLE')
+    expect(error.hint).toContain('Key-backed identities cannot mint an Admin Domain token')
+  })
+})

package/src/commands/__tests__/logs.test.ts

@@ -66,4 +66,27 @@ describe('acceptJournalPage', () => {
     expect(() => acceptJournalPage({ records: [{}] })).toThrow('record 0')
     expect(() => acceptJournalPage({ records: [], cursor: 7 })).toThrow('cursor')
   })
+
+  test('admits journal v2 records that use occurredAt instead of timestamp', () => {
+    const page = acceptJournalPage({
+      records: [
+        {
+          sequence: 10241,
+          topic: 'function.invoke',
+          occurredAt: '2026-08-19T16:51:10.049Z',
+          committedAt: '2026-08-19T16:51:10.070Z',
+          payload: { outcome: 'rejected' },
+          correlation: { invocationId: 'cf862a64-3aa1-4343-ba86-f9b516c4ff95' },
+        },
+      ],
+    })
+    expect(page.records[0]).toMatchObject({
+      sequence: 10241,
+      topic: 'function.invoke',
+      timestamp: '2026-08-19T16:51:10.049Z',
+      occurredAt: '2026-08-19T16:51:10.049Z',
+      committedAt: '2026-08-19T16:51:10.070Z',
+      correlationId: 'cf862a64-3aa1-4343-ba86-f9b516c4ff95',
+    })
+  })
 })

package/src/commands/call-describe.ts

@@ -0,0 +1,131 @@
+import type { Path } from '@astrale-os/sdk/graph/path'
+
+import { AstraleError } from '../errors'
+
+type JsonRecord = Record<string, unknown>
+
+export interface CallableDescription {
+  readonly path: string
+  readonly origin: string
+  readonly method?: string
+  readonly function?: string
+  readonly class?: string
+  readonly dispatch?: 'static' | 'instance'
+  readonly description?: string
+  readonly auth?: unknown
+  readonly input?: unknown
+  readonly output?: unknown
+  readonly candidates?: readonly CallableDescription[]
+}
+
+/** Resolve one callable's input/output from an installed Domain schema document. */
+export function describeCallableFromSchema(
+  path: Path,
+  schema: unknown,
+): CallableDescription | undefined {
+  if (path.ast.anchor.kind !== 'domain') return undefined
+  const origin = path.ast.anchor.origin
+  const last = path.ast.steps.at(-1)
+  const document = asRecord(schema)
+  if (document === undefined || last === undefined) return undefined
+
+  if (last.kind === 'method') {
+    const owner = path.ast.steps.at(-2)
+    if (
+      owner?.kind === 'projection' &&
+      (owner.projection.kind === 'class' || owner.projection.kind === 'interface')
+    ) {
+      const bag = asRecord(
+        owner.projection.kind === 'class' ? document.classes : document.interfaces,
+      )
+      const definition = asRecord(bag?.[owner.projection.name])
+      const method = asRecord(asRecord(definition?.methods)?.[last.name])
+      if (method !== undefined) {
+        return Object.freeze({
+          path: path.raw,
+          origin,
+          class: owner.projection.name,
+          method: last.name,
+          dispatch: last.dispatch,
+          ...callableFields(method),
+        })
+      }
+    }
+    const matches = findNamedMethods(document, origin, path.raw, last.name, last.dispatch)
+    if (matches.length === 1) return matches[0]
+    if (matches.length > 1) {
+      return Object.freeze({
+        path: path.raw,
+        origin,
+        method: last.name,
+        dispatch: last.dispatch,
+        candidates: Object.freeze(matches),
+      })
+    }
+    return undefined
+  }
+
+  if (last.kind === 'projection' && last.projection.kind === 'function') {
+    const fn = asRecord(asRecord(document.functions)?.[last.projection.name])
+    if (fn === undefined) return undefined
+    return Object.freeze({
+      path: path.raw,
+      origin,
+      function: last.projection.name,
+      ...callableFields(fn),
+    })
+  }
+  return undefined
+}
+
+export function missingCallableDescription(path: string): AstraleError {
+  return new AstraleError(
+    'CALL_DESCRIBE_UNAVAILABLE',
+    `No callable schema is installed for ${path}.`,
+    'Use a Domain-rooted Path such as /:host.astrale.ai:class.Manager:createInstance. Method Paths are not Function nodes.',
+  )
+}
+
+function findNamedMethods(
+  schema: JsonRecord,
+  origin: string,
+  path: string,
+  method: string,
+  dispatch: 'static' | 'instance',
+): CallableDescription[] {
+  const matches: CallableDescription[] = []
+  for (const bag of [schema.classes, schema.interfaces]) {
+    const definitions = asRecord(bag)
+    if (definitions === undefined) continue
+    for (const [className, definition] of Object.entries(definitions)) {
+      const methodDef = asRecord(asRecord(asRecord(definition)?.methods)?.[method])
+      if (methodDef === undefined) continue
+      matches.push(
+        Object.freeze({
+          path,
+          origin,
+          class: className,
+          method,
+          dispatch,
+          ...callableFields(methodDef),
+        }),
+      )
+    }
+  }
+  return matches
+}
+
+function callableFields(value: JsonRecord): Partial<CallableDescription> {
+  return {
+    ...(typeof value.description === 'string' ? { description: value.description } : {}),
+    ...(value.auth === undefined ? {} : { auth: value.auth }),
+    ...(value.input === undefined ? {} : { input: value.input }),
+    ...(value.output === undefined ? {} : { output: value.output }),
+  }
+}
+
+function asRecord(input: unknown): JsonRecord | undefined {
+  return input !== null && typeof input === 'object' && !Array.isArray(input)
+    ? (input as JsonRecord)
+    : undefined
+}

package/src/commands/call.ts

@@ -8,6 +8,7 @@ import { nodeProperty } from '../graph/index'
 import { presentBinary } from '../lib/binary'
 import { log } from '../lib/log'
 import { output, present } from '../lib/output'
+import { describeCallableFromSchema, missingCallableDescription } from './call-describe'
 
 type CallOpts = KernelCommandOpts & {
   data?: string
@@ -97,28 +98,20 @@ async function describeOperation(path: string, opts: CallOpts): Promise<void> {
   await runKernelCommand({
     opts,
     label: `Schema for ${path}`,
-    // The Function node carries the schemas as props (function.get depth:0).
-    fn: async ({ graph }) => await graph.get(Path.parse(path)),
-    format: (node, fmtOpts) => {
-      const input = nodeProperty(node, 'inputSchema')
-      const outputSchema = nodeProperty(node, 'outputSchema')
-      const schema: Record<string, unknown> = {}
-      if (input) schema.input = tryParseJson(input)
-      if (outputSchema) schema.output = tryParseJson(outputSchema)
-      output(Object.keys(schema).length > 0 ? schema : node, fmtOpts)
+    fn: async ({ graph }) => {
+      const parsed = Path.parse(path)
+      if (parsed.ast.anchor.kind !== 'domain') {
+        throw missingCallableDescription(path)
+      }
+      const domain = await graph.getOrThrow(Path.parse(`/:${parsed.ast.anchor.origin}`))
+      const described = describeCallableFromSchema(parsed, nodeProperty(domain, 'schema'))
+      if (described === undefined) throw missingCallableDescription(path)
+      return described
     },
+    format: (schema, fmtOpts) => output(schema, fmtOpts),
   })
 }
 
-function tryParseJson(value: unknown): unknown {
-  if (typeof value !== 'string') return value
-  try {
-    return JSON.parse(value)
-  } catch {
-    return value
-  }
-}
-
 // ── Param parsing ───────────────────────────────────────────
 
 export async function parseParams(
@@ -221,17 +214,20 @@ Self-reference:
   (e.g. via 'astrale get @self --json'). Resolution authenticates to
   the selected Kernel and never trusts a local registration or JWT sub.
 
+  --describe reads the callable's input/output from the installed Domain
+  schema. Method Paths are not Function nodes.
+
 Examples:
-  $ astrale call /:host.astrale.ai:class.KernelInstance:list
+  $ astrale call /:host.astrale.ai:class.Manager:createInstance --describe
   $ astrale call /:blog.acme.com:class.Author:list limit=10
   $ astrale call '@self::deactivate'
-  $ astrale call /:shell.astrale.ai:function.search-domains --json
+  $ astrale call /:kernel.astrale.ai:function.journal --data '{"limit":5}' --json
 `,
   arguments: [
     {
       name: 'path',
       description:
-        'Operation path (e.g., /:host.astrale.ai:class.KernelInstance:list or /node::method)',
+        'Operation path (e.g., /:host.astrale.ai:class.Manager:createInstance or /node::method)',
     },
     { name: 'params...', description: 'Params as key=value pairs', required: false },
   ],

package/src/commands/domain/install.ts

@@ -20,12 +20,35 @@ import { isMachine, output } from '../../lib/output'
 import { confirmWithInput, promptText, selectFrom } from '../../lib/prompt'
 import { isHttpUrl } from '../../lib/validation'
 
-/** Exact output of the public Kernel install syscall for one requested root. */
-type DirectInstallResult = readonly {
-  origin: string
-  revision: string
-  etag?: string
-}[]
+/** Public Kernel install syscall input for one remote URL. */
+export function directInstallCallInput(
+  url: string,
+  token?: string,
+  operation: string = crypto.randomUUID(),
+) {
+  return Object.freeze({
+    operation,
+    domains: [
+      Object.freeze({
+        source: Object.freeze({
+          kind: 'remote' as const,
+          url,
+          ...(token === undefined ? {} : { token }),
+        }),
+      }),
+    ],
+  })
+}
+
+type DirectInstallResult = {
+  readonly operation: string
+  readonly transitions: readonly {
+    readonly intent: {
+      readonly origin: string
+      readonly target?: { readonly schemaRevision?: string } | null
+    }
+  }[]
+}
 
 type InstallOpts = KernelCommandOpts &
   AdminTargetCommandOpts & {
@@ -330,19 +353,22 @@ async function installDirect(target: string | undefined, opts: InstallOpts): Pro
     label: `Installing domain from ${url}`,
     fn: async ({ session }) =>
       (await session.call(
-        createPathCall(Path.project(syscalls.install.ref).raw, {
-          domains: [{ url, ...(opts.token ? { token: opts.token } : {}) }],
-        }),
+        createPathCall(
+          Path.project(syscalls.install.ref).raw,
+          directInstallCallInput(url, opts.token),
+        ),
       )) as DirectInstallResult,
     format: (result, fmtOpts, isRaw) => {
       if (isRaw) {
         output(result, fmtOpts)
         return
       }
-      const installed = result[0]
-      if (!installed) throw new Error('Kernel install returned no installed Domain receipt.')
-      log.success(`Domain installed: ${installed.origin}@${installed.revision}`)
-      if (installed.etag) log.dim(`  publication: ${installed.etag}`)
+      const installed = result.transitions[0]?.intent
+      if (installed === undefined) {
+        throw new Error('Kernel install returned no committed Domain transition.')
+      }
+      const revision = installed.target?.schemaRevision ?? result.operation
+      log.success(`Domain installed: ${installed.origin}@${revision}`)
       // Belt-and-braces: the kernel-confirmed origin is authoritative. If it
       // aliases the host and the pre-install gate never consented to THAT
       // origin (lying or absent `/meta`), say so loudly after the fact.

package/src/commands/get.ts

@@ -4,8 +4,8 @@ import type { KernelCommandOpts } from '../connection'
 import type { CommandDefinition } from '../program/index'
 
 import { expandSelfInPath, runKernelCommand, withSelfHint } from '../connection'
-import { log } from '../lib/log'
-import { output } from '../lib/output'
+import { formatKernelError } from '../connection/errors'
+import { isMachine, output } from '../lib/output'
 
 type GetOpts = KernelCommandOpts
 
@@ -16,7 +16,7 @@ export async function getCommand(target: string, opts: GetOpts): Promise<void> {
   try {
     ;({ path, meta } = await expandSelfInPath(target, opts))
   } catch (error) {
-    log.error(error instanceof Error ? error.message : 'Invalid target')
+    await formatKernelError(error, isMachine(opts), undefined, opts.debug)
     process.exit(1)
   }
 

package/src/commands/instance/list.ts

@@ -4,6 +4,7 @@ import type { KernelCommandOpts } from '../../connection'
 import type { Column } from '../../lib/output'
 import type { CommandDefinition } from '../../program/index'
 
+import { AstraleError } from '../../errors'
 import { listOwnedInstances } from '../../lib/admin-instance'
 import {
   formatInstanceLocation,
@@ -61,9 +62,13 @@ export default {
 
       let managed: OwnedInstanceInfo[] = []
       if (!opts.bookmarked) {
-        managed = await withSpinner('Fetching instances', !isMachine(opts), () =>
-          listOwnedInstances(opts),
-        )
+        try {
+          managed = await withSpinner('Fetching instances', !isMachine(opts), () =>
+            listOwnedInstances(opts),
+          )
+        } catch (error) {
+          throw adminInventoryUnavailable(error)
+        }
       }
       if (isMachine(opts)) {
         output(
@@ -148,3 +153,31 @@ export function buildInstanceRows(
 
   return rows
 }
+
+const ADMIN_INVENTORY_CODES = new Set([
+  'TOKEN_EXCHANGE_SOURCE_INVALID',
+  'TOKEN_EXCHANGE_SOURCE_EXPIRED',
+  'TOKEN_EXCHANGE_UNSUPPORTED',
+  'TOKEN_EXCHANGE_DISCOVERY_FAILED',
+  'TOKEN_EXCHANGE_PROTOCOL_ERROR',
+  'TOKEN_EXCHANGE_INSECURE',
+  'ADMIN_DOMAIN_ISSUER_MISSING',
+])
+
+/** Admin-managed inventory is not available without a deployed Admin Domain + IdP identity. */
+export function adminInventoryUnavailable(cause: unknown): AstraleError {
+  const code = cause instanceof AstraleError ? cause.code : undefined
+  if (code !== undefined && ADMIN_INVENTORY_CODES.has(code)) {
+    return new AstraleError(
+      'ADMIN_INVENTORY_UNAVAILABLE',
+      'Managed instance listing needs the Admin Domain and an IdP-backed identity. Admin is not deployed in this environment.',
+      'Use `astrale instance list --bookmarked` for local kernel bookmarks. Key-backed identities cannot mint an Admin Domain token.',
+    )
+  }
+  if (cause instanceof AstraleError) return cause
+  return new AstraleError(
+    'ADMIN_INVENTORY_UNAVAILABLE',
+    cause instanceof Error ? cause.message : String(cause),
+    'Use `astrale instance list --bookmarked` for local kernel bookmarks.',
+  )
+}

package/src/commands/logs.ts

@@ -29,6 +29,8 @@ export interface JournalRecord {
   readonly timestamp: string
   readonly topic: string
   readonly payload: unknown
+  readonly occurredAt?: string
+  readonly committedAt?: string
   readonly principal?: string
   readonly correlationId?: string
   readonly causationId?: string
@@ -146,27 +148,45 @@ function acceptRecord(input: unknown, index: number): JournalRecord {
   if (
     !isRecord(input) ||
     !Number.isSafeInteger(input.sequence) ||
-    typeof input.timestamp !== 'string' ||
     typeof input.topic !== 'string'
   ) {
     throw new TypeError(`Kernel journal record ${index} is invalid`)
   }
-  for (const key of ['principal', 'correlationId', 'causationId'] as const) {
-    if (input[key] !== undefined && typeof input[key] !== 'string') {
-      throw new TypeError(`Kernel journal record ${index}.${key} must be text`)
-    }
+  const occurredAt = optionalText(input.occurredAt, index, 'occurredAt')
+  const timestamp = optionalText(input.timestamp, index, 'timestamp') ?? occurredAt
+  if (timestamp === undefined) {
+    throw new TypeError(`Kernel journal record ${index} is missing occurredAt/timestamp`)
   }
+  const correlation = isRecord(input.correlation) ? input.correlation : undefined
+  const correlationId =
+    optionalText(input.correlationId, index, 'correlationId') ??
+    optionalText(correlation?.invocationId, index, 'correlation.invocationId')
+  const principal = optionalText(input.principal, index, 'principal')
   return Object.freeze({
     sequence: input.sequence as number,
-    timestamp: input.timestamp,
+    timestamp,
     topic: input.topic,
     payload: input.payload,
-    ...(input.principal === undefined ? {} : { principal: input.principal as string }),
-    ...(input.correlationId === undefined ? {} : { correlationId: input.correlationId as string }),
-    ...(input.causationId === undefined ? {} : { causationId: input.causationId as string }),
+    ...(occurredAt === undefined ? {} : { occurredAt }),
+    ...(optionalText(input.committedAt, index, 'committedAt') === undefined
+      ? {}
+      : { committedAt: input.committedAt as string }),
+    ...(principal === undefined ? {} : { principal }),
+    ...(correlationId === undefined ? {} : { correlationId }),
+    ...(optionalText(input.causationId, index, 'causationId') === undefined
+      ? {}
+      : { causationId: input.causationId as string }),
   })
 }
 
+function optionalText(input: unknown, index: number, field: string): string | undefined {
+  if (input === undefined) return undefined
+  if (typeof input !== 'string') {
+    throw new TypeError(`Kernel journal record ${index}.${field} must be text`)
+  }
+  return input
+}
+
 function positiveInteger(flag: string, raw: string): number {
   if (!/^\d+$/.test(raw)) throw new TypeError(`${flag} must be a positive integer`)
   const value = Number.parseInt(raw, 10)

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

@@ -38,6 +38,8 @@ describe('prepareMutation', () => {
 
   /** @evidence TEST-CLI-GRAPH-REJECTS-PATCH-DATA */
   test('rejects legacy PatchData instead of narrowing it', () => {
-    expect(() => prepareMutation({ nodes: { create: [] }, edges: { create: [] } })).toThrow()
+    expect(() => prepareMutation({ nodes: { create: [] }, edges: { create: [] } })).toThrow(
+      /Legacy PatchData/,
+    )
   })
 })

package/src/graph/mutation.ts

@@ -4,6 +4,11 @@ import { MutationAST } from '@astrale-os/sdk/mutation'
 
 /** Admit the canonical document or Core's exact rich authoring input at the CLI JSON boundary. */
 export function prepareMutation(input: unknown): MutationASTValue {
+  if (isLegacyPatchData(input)) {
+    throw new TypeError(
+      'Legacy PatchData { nodes, edges } is not Mutation V3. Author { preconditions, operations } or a canonical astrale.graph.mutation/v3 document.',
+    )
+  }
   if (isCanonicalCandidate(input)) return MutationAST.decode(input)
   return MutationAST.create(input as MutationInput)
 }
@@ -16,3 +21,13 @@ function isCanonicalCandidate(input: unknown): boolean {
     (Object.hasOwn(input, 'format') || Object.hasOwn(input, 'version'))
   )
 }
+
+function isLegacyPatchData(input: unknown): boolean {
+  return (
+    input !== null &&
+    typeof input === 'object' &&
+    !Array.isArray(input) &&
+    !Object.hasOwn(input, 'operations') &&
+    (Object.hasOwn(input, 'nodes') || Object.hasOwn(input, 'edges'))
+  )
+}

package/src/program/__tests__/program.test.ts

@@ -187,7 +187,7 @@ describe('program composition', () => {
       'whoami',
     ])
     expect(createHash('sha256').update(JSON.stringify(surface)).digest('hex')).toBe(
-      'e030c6f672dea850a90bef16cf4222ea6af45e60f50cfc829c85bd90d9543632',
+      '4a57bfc347f9abebcea239427214eb25fbaf9ca704170c8b4a933d0c9ba4d14e',
     )
   })