@astrale-os/cli 1.0.0-beta.12 → 1.0.0-beta.13

package/dist/types/admin/contract.d.ts

@@ -0,0 +1,26 @@
+import type { Input } from '@astrale-os/sdk/client';
+import type { ClientSession } from '@astrale-os/sdk/client/session';
+import type { ClassRef } from '@astrale-os/sdk/schema';
+import { Path } from '@astrale-os/sdk/graph/path';
+export declare const AdminContract: Readonly<{
+    origin: "admin.astrale.ai";
+    fleet: Path;
+    classes: Readonly<{
+        Domain: ClassRef;
+    }>;
+    edges: Readonly<{
+        fleetInstallsDomainByDefault: ClassRef;
+    }>;
+    properties: Readonly<{
+        domain: Readonly<{
+            origin: `${string}:class.${string}.property.origin`;
+            name: "kernel.astrale.ai:class.Named.property.name";
+            discoveryUrl: `${string}:class.${string}.property.discoveryUrl`;
+            description: "kernel.astrale.ai:class.Descriptable.property.description";
+            createdAt: "kernel.astrale.ai:class.Timestamped.property.createdAt";
+            updatedAt: "kernel.astrale.ai:class.Timestamped.property.updatedAt";
+        }>;
+    }>;
+}>;
+/** Invoke one stable Admin instance Method without schema discovery or reflection. */
+export declare function callAdminMethod(session: ClientSession, receiver: Path, method: string, input: Input): Promise<unknown>;

package/dist/types/admin/instance/client.d.ts

@@ -1,5 +1,4 @@
 import type { ClientSession } from '@astrale-os/sdk/client/session';
-import { type AdminBinding } from '../binding';
 import { type DomainInstallReceipt, type InstanceInfo, type OwnedInstanceInfo } from './model';
 export interface AdminInstanceContext {
     readonly session: ClientSession;
@@ -12,11 +11,10 @@ export interface AdminInstanceApi {
     installDomain(identifier: string, domain: string): Promise<DomainInstallReceipt>;
 }
 export interface AdminInstanceDependencies {
-    readonly bind?: (session: ClientSession) => Promise<AdminBinding>;
     readonly operationId?: (kind: 'create' | 'status' | 'delete' | 'install-domain') => string;
 }
 /**
- * Bind one discovered Admin root revision and expose only the public Instance
- * product journey. No Host lifecycle method is present on this capability.
+ * Connect the public Instance journey through stable Admin call paths. Routine
+ * operations perform no schema discovery. No Host lifecycle method is present.
  */
 export declare function connectAdminInstances(context: AdminInstanceContext, dependencies?: AdminInstanceDependencies): Promise<AdminInstanceApi>;

package/dist/types/admin/instance/model.d.ts

@@ -4,10 +4,13 @@ export interface InstanceInfo {
     readonly id: string;
     readonly slug: string;
     readonly url: string;
+    readonly hostId?: string;
+    readonly region?: string;
     readonly state: InstanceState;
     readonly phase?: string;
     readonly error?: string | null;
     readonly createdAt?: string;
+    readonly updatedAt?: string;
     readonly organizationId?: string;
 }
 /** An Instance returned through the caller-scoped Admin graph inventory. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/cli",
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.13",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",

package/src/admin/.spec/architecture.md

@@ -1,10 +1,10 @@
 # CLI Admin adapters
 
-This private aggregate translates the frozen CLI command journey into the discovered V2
-`admin.astrale.ai` contract. It binds the exact served Domain revision through Kernel Client,
-uses `GraphApi` for policy-visible inventory, and invokes receiver-oriented Methods through
-`DomainBinding`. It does not import Admin implementation code, hard-code one schema revision, call
-Host directly, or persist remote graph truth.
+This private aggregate translates the frozen CLI command journey into the stable public
+`admin.astrale.ai` contract. Routine commands use canonical Admin Class, Property, Core receiver,
+and Method paths through Kernel Client. They do not download, inspect, bind, or rebuild the Admin
+schema. Strict local decoders admit every untrusted Admin result. The adapter does not import Admin
+implementation code, call Host directly, or persist remote graph truth.
 
 `instance` owns create/list/status/delete/install projection and explicitly excludes the reserved
 Admin Host from consumer placement. `catalog` owns Domain inventory, publication, and default-set
@@ -13,3 +13,10 @@ configuration. `graph` is their bounded cursor helper and is not re-exported by
 Commander grammar, help text, output shapes, bookmark behavior, and current interactive host
 selection remain owned by the existing command surface; these adapters change only its remote
 semantic owner.
+
+## Performance contract
+
+`instance list` performs one Admin method call after connection setup and no schema-discovery call.
+Against the production beta Admin endpoint, the complete command must finish in less than 1 second
+with a warm route/cache and less than 2 seconds from a cold CLI process. Unit tests prove the
+single-call/no-reflection shape; retained live evidence proves the wall-clock bounds.

package/src/admin/__tests__/fixture.ts

@@ -1,101 +1,25 @@
+import type { Call } from '@astrale-os/sdk/client'
 import type { ClientSession } from '@astrale-os/sdk/client/session'
-import type { CallableReference } from '@astrale-os/sdk/client/session'
 
-import {
-  callableAddress,
-  core,
-  defineSchema,
-  edgeClass,
-  method,
-  nodeClass,
-  property,
-  schema,
-} from '@astrale-os/sdk/schema'
 import { mock } from 'bun:test'
 
-import type { AdminBinding } from '../binding'
-
-const operation = () =>
-  method({
-    auth: 'authenticated',
-    input: { type: 'object', additionalProperties: true },
-    output: { type: 'object', additionalProperties: true },
-  })
-
-const Domain = nodeClass({
-  properties: {
-    origin: property({ type: 'string' }, { required: true }),
-    name: property({ type: 'string' }, { required: true }),
-    discoveryUrl: property({ type: 'string' }, { required: true }),
-    description: property({ type: 'string' }),
-    createdAt: property({ type: 'string' }, { required: true }),
-    updatedAt: property({ type: 'string' }, { required: true }),
-  },
-  methods: { configureDefault: operation() },
-})
-const Fleet = nodeClass({
-  methods: {
-    publishDomain: operation(),
-    listInstances: operation(),
-    createInstance: operation(),
-  },
-})
-const Host = nodeClass({
-  properties: {
-    id: property({ type: 'string' }, { required: true }),
-    state: property({ type: 'string' }, { required: true }),
-  },
-  methods: { createInstance: operation() },
-})
-const Instance = nodeClass({
-  methods: {
-    status: operation(),
-    delete: operation(),
-    installDomain: operation(),
-  },
-})
-const fleet_installs_domain_by_default = edgeClass.directed({
-  source: { as: 'fleet', accepts: [Fleet], outgoing: '0..*' },
-  target: { as: 'domain', accepts: [Domain], incoming: '0..*' },
-})
-const fleet_reserves_admin_host = edgeClass.directed({
-  source: { as: 'fleet', accepts: [Fleet], outgoing: '0..1' },
-  target: { as: 'host', accepts: [Host], incoming: '0..1' },
-})
-
-export const AdminTestSchema = defineSchema('admin.astrale.ai', {
-  classes: {
-    Domain,
-    Fleet,
-    Host,
-    Instance,
-    fleet_installs_domain_by_default,
-    fleet_reserves_admin_host,
-  },
-  core: { nodes: { fleet: core.node(() => Fleet, {}) }, edges: [] },
-})
-
-export const AdminTestDomain = schema.resolve(AdminTestSchema)
-
-export function adminBinding(): AdminBinding {
-  return { domain: AdminTestDomain, graph: {} } as unknown as AdminBinding
-}
-
-export function adminSession(
-  implementation?: (
-    method: { readonly owner: string; readonly name: string },
-    receiver: unknown,
-    input: unknown,
-  ) => unknown,
-) {
-  const invoke = mock(async (reference: CallableReference, input: unknown) => {
-    const address = callableAddress(reference.callable)
-    if (address.kind !== 'method') throw new Error('Expected an Admin Method.')
-    return implementation?.(
-      { owner: address.owner.name, name: address.name },
-      reference.target,
-      input,
-    )
+export function adminSession(implementation?: (target: string, input: unknown) => unknown): {
+  readonly call: ReturnType<typeof mock>
+  readonly reflection: ReturnType<typeof mock>
+  readonly session: ClientSession
+} {
+  const call = mock(async (request: Call) =>
+    implementation?.(String(request.target), request.input),
+  )
+  const reflection = mock(() => {
+    throw new Error('Routine Admin commands must not perform schema discovery or reflection.')
   })
-  return { invoke, session: { invoke } as unknown as ClientSession }
+  const session = {
+    call,
+    installation: reflection,
+    snapshot: reflection,
+    bind: reflection,
+    invoke: reflection,
+  } as unknown as ClientSession
+  return { call, reflection, session }
 }

package/src/admin/catalog/.spec/api.d.ts

@@ -1,5 +1,4 @@
 import type { ClientSession } from '@astrale-os/sdk/client/session'
-import type { DomainBinding } from '@astrale-os/shell'
 
 import type { AdminGraphApi } from '../../graph/.spec/api.js'
 
@@ -55,7 +54,6 @@ export class AdminDomainNotFoundError extends Error {
 }
 
 export interface AdminCatalogDependencies {
-  readonly bind?: (session: ClientSession) => Promise<DomainBinding>
   readonly operationId?: (kind: 'publish' | 'configure-default') => string
 }
 

package/src/admin/catalog/.spec/architecture.md

@@ -1,6 +1,7 @@
 # CLI Admin catalog adapter
 
-The adapter reads policy-visible `Domain` Nodes through bounded Graph pages and derives default
-membership from the Fleet relation. Publication invokes `Fleet.publishDomain`; a requested default
-change is a separate explicit `Domain.configureDefault` call. Unchanged publication input is a
-no-op, and an omitted description preserves the current value.
+The adapter reads policy-visible `Domain` Nodes through bounded Graph pages using stable Class and
+Property keys, and derives default membership from the stable Fleet relation. It performs no schema
+discovery or reflection. Publication invokes `Fleet.publishDomain`; a requested default change is a
+separate explicit `Domain.configureDefault` call. Unchanged publication input is a no-op, and an
+omitted description preserves the current value.

package/src/admin/catalog/__tests__/client.test.ts

@@ -2,23 +2,35 @@ import type { Node } from '@astrale-os/sdk/graph/node'
 import type { QueryAST } from '@astrale-os/sdk/query'
 
 import { NodeId } from '@astrale-os/sdk/graph/node'
+import { normalizeProperties } from '@astrale-os/sdk/graph/properties'
+import { PropertyKey } from '@astrale-os/sdk/schema'
 import { describe, expect, mock, test } from 'bun:test'
 
 import type { AdminGraphApi } from '../../graph'
 
-import { AdminTestDomain, adminBinding, adminSession } from '../../__tests__/fixture'
+import { adminSession } from '../../__tests__/fixture'
 import { connectAdminCatalog } from '../client'
 
+const domainProperties = Object.freeze({
+  origin: PropertyKey('admin.astrale.ai:class.Domain.property.origin'),
+  name: PropertyKey('kernel.astrale.ai:class.Named.property.name'),
+  discoveryUrl: PropertyKey('admin.astrale.ai:class.Domain.property.discoveryUrl'),
+  description: PropertyKey('kernel.astrale.ai:class.Descriptable.property.description'),
+  createdAt: PropertyKey('kernel.astrale.ai:class.Timestamped.property.createdAt'),
+  updatedAt: PropertyKey('kernel.astrale.ai:class.Timestamped.property.updatedAt'),
+})
+
 function domainNode(id: string, origin: string): Node {
   return {
     id: NodeId(id),
-    class: AdminTestDomain.classes.Domain.key,
-    props: AdminTestDomain.classes.Domain.properties.from({
-      origin,
-      name: origin.split('.')[0]!,
-      discoveryUrl: `https://${origin}`,
-      createdAt: '2026-08-12T00:00:00.000Z',
-      updatedAt: '2026-08-12T00:00:00.000Z',
+    class: 'admin.astrale.ai:Domain' as Node['class'],
+    props: normalizeProperties({
+      [domainProperties.origin]: origin,
+      [domainProperties.name]: origin.split('.')[0]!,
+      [domainProperties.discoveryUrl]: `https://${origin}`,
+      [domainProperties.description]: `${origin} description`,
+      [domainProperties.createdAt]: '2026-08-12T00:00:00.000Z',
+      [domainProperties.updatedAt]: '2026-08-12T00:00:00.000Z',
     }),
   }
 }
@@ -26,18 +38,16 @@ function domainNode(id: string, origin: string): Node {
 function fixture(input: {
   domains?: readonly Node[]
   defaults?: readonly Node[]
-  invoke?: (method: { owner: string; name: string }, receiver: unknown, value: unknown) => unknown
+  invoke?: (target: string, value: unknown) => unknown
 }) {
   const calls: Array<{
-    method: { owner: string; name: string }
-    receiver: string
+    target: string
     value: unknown
   }> = []
-  const remote = adminSession((method, receiver, value) => {
-    calls.push({ method, receiver: String(receiver), value })
-    return input.invoke?.(method, receiver, value)
+  const remote = adminSession((target, value) => {
+    calls.push({ target, value })
+    return input.invoke?.(target, value)
   })
-  const binding = adminBinding()
   const query = mock(async (_ast: QueryAST) => ({
     result: {
       kind: 'nodes' as const,
@@ -46,22 +56,30 @@ function fixture(input: {
     page: {},
   }))
   const defaultNodes = input.defaults ?? []
-  const neighbors = mock(async () => ({
-    nodes: defaultNodes,
-    first: defaultNodes[0] ?? null,
-    graph: { nodes: defaultNodes, edges: [] },
-    cursor: null,
-    collect: async () => ({ nodes: defaultNodes, cursor: null }),
-  }))
+  const neighbors = mock(
+    async (
+      _source: Parameters<AdminGraphApi['neighbors']>[0],
+      _via: Parameters<AdminGraphApi['neighbors']>[1],
+      _options: Parameters<AdminGraphApi['neighbors']>[2],
+    ) => ({
+      nodes: defaultNodes,
+      first: defaultNodes[0] ?? null,
+      graph: { nodes: defaultNodes, edges: [] },
+      cursor: null,
+      collect: async () => ({ nodes: defaultNodes, cursor: null }),
+    }),
+  )
   const graph = { query, neighbors } as unknown as AdminGraphApi
   return {
-    invoke: remote.invoke,
+    call: remote.call,
+    reflection: remote.reflection,
+    query,
+    neighbors,
     calls,
     connect: () =>
       connectAdminCatalog(
         { session: remote.session, graph },
         {
-          bind: async () => binding,
           operationId: (kind) => `cli.domain.${kind}:test`,
         },
       ),
@@ -83,16 +101,57 @@ describe('V2 Admin Domain catalog adapter', () => {
   test('lists Domain nodes through GraphApi and joins the Fleet default relation', async () => {
     const crm = domainNode('crm-domain', 'crm.acme.dev')
     const notes = domainNode('notes-domain', 'notes.acme.dev')
-    const api = await fixture({ domains: [crm, notes], defaults: [crm] }).connect()
+    const contract = fixture({ domains: [crm, notes], defaults: [crm] })
+    const api = await contract.connect()
 
     await expect(api.list()).resolves.toEqual([
-      expect.objectContaining({
+      {
         id: '@crm-domain',
         origin: 'crm.acme.dev',
+        name: 'crm',
+        url: 'https://crm.acme.dev',
+        description: 'crm.acme.dev description',
         installByDefault: true,
-      }),
-      expect.objectContaining({ id: '@notes-domain', origin: 'notes.acme.dev' }),
+        createdAt: '2026-08-12T00:00:00.000Z',
+        updatedAt: '2026-08-12T00:00:00.000Z',
+      },
+      {
+        id: '@notes-domain',
+        origin: 'notes.acme.dev',
+        name: 'notes',
+        url: 'https://notes.acme.dev',
+        description: 'notes.acme.dev description',
+        createdAt: '2026-08-12T00:00:00.000Z',
+        updatedAt: '2026-08-12T00:00:00.000Z',
+      },
     ])
+    expect(contract.query).toHaveBeenCalledWith(
+      {
+        format: 'astrale.graph.query',
+        version: 'v6',
+        source: {
+          kind: 'node',
+          terms: [
+            {
+              kind: 'class',
+              class: { origin: 'admin.astrale.ai', kind: 'class', name: 'Domain' },
+            },
+          ],
+          binding: 'n0',
+        },
+        steps: [],
+        select: { kind: 'nodes', binding: 'n0', projection: { kind: 'value' } },
+      },
+      { page: { size: 256 } },
+    )
+    const [source, edge, options] = contract.neighbors.mock.calls[0]!
+    expect(String(source)).toBe('/:admin.astrale.ai:core.fleet')
+    expect(edge).toEqual({
+      origin: 'admin.astrale.ai',
+      kind: 'class',
+      name: 'fleet_installs_domain_by_default',
+    })
+    expect(options).toEqual({ direction: 'outgoing', page: { size: 256 } })
   })
 
   test('publishes through Fleet then configures the Domain default explicitly', async () => {
@@ -109,8 +168,7 @@ describe('V2 Admin Domain catalog adapter', () => {
     ).resolves.toMatchObject({ changed: true, isNew: true, entry: { installByDefault: true } })
     expect(contract.calls).toEqual([
       {
-        method: { owner: 'Fleet', name: 'publishDomain' },
-        receiver: '/:admin.astrale.ai:core.fleet::publishDomain',
+        target: '/:admin.astrale.ai:core.fleet::publishDomain',
         value: {
           operationId: 'cli.domain.publish:test',
           origin: 'crm.acme.dev',
@@ -119,8 +177,7 @@ describe('V2 Admin Domain catalog adapter', () => {
         },
       },
       {
-        method: { owner: 'Domain', name: 'configureDefault' },
-        receiver: '@crm-domain::configureDefault',
+        target: '@crm-domain::configureDefault',
         value: {
           operationId: 'cli.domain.configure-default:test',
           enabled: true,
@@ -137,6 +194,52 @@ describe('V2 Admin Domain catalog adapter', () => {
     await expect(
       api.publish({ origin: 'crm.acme.dev', name: 'crm', url: 'https://crm.acme.dev' }),
     ).resolves.toMatchObject({ changed: false, isNew: false })
-    expect(contract.invoke).not.toHaveBeenCalled()
+    expect(contract.call).not.toHaveBeenCalled()
+    expect(contract.reflection).not.toHaveBeenCalled()
+  })
+
+  test('connects without schema discovery or graph I/O', async () => {
+    const contract = fixture({})
+
+    await contract.connect()
+
+    expect(contract.call).not.toHaveBeenCalled()
+    expect(contract.reflection).not.toHaveBeenCalled()
+    expect(contract.query).not.toHaveBeenCalled()
+    expect(contract.neighbors).not.toHaveBeenCalled()
+  })
+
+  test('rejects malformed graph records and publication summaries', async () => {
+    const invalidNode = {
+      id: NodeId('invalid-domain'),
+      class: 'admin.astrale.ai:Domain' as Node['class'],
+      props: normalizeProperties({
+        [domainProperties.origin]: 'invalid.example.dev',
+        [domainProperties.name]: 'invalid',
+        [domainProperties.discoveryUrl]: 'https://invalid.example.dev',
+        [domainProperties.createdAt]: '2026-08-12T00:00:00.000Z',
+      }),
+    }
+    await expect((await fixture({ domains: [invalidNode] }).connect()).list()).rejects.toThrow(
+      'Admin Domain.updatedAt is invalid.',
+    )
+
+    const malformed = fixture({ invoke: () => ({ id: '@domain-only' }) })
+    await expect(
+      (await malformed.connect()).publish({
+        origin: 'crm.acme.dev',
+        name: 'crm',
+        url: 'https://crm.acme.dev',
+      }),
+    ).rejects.toThrow('Admin Domain origin is invalid.')
+
+    const malformedPath = fixture({ invoke: () => ({ ...summary('crm.acme.dev'), id: 'bad' }) })
+    await expect(
+      (await malformedPath.connect()).publish({
+        origin: 'crm.acme.dev',
+        name: 'crm',
+        url: 'https://crm.acme.dev',
+      }),
+    ).rejects.toThrow('Admin Domain id is invalid.')
   })
 })