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

package/src/admin/catalog/client.ts

@@ -1,19 +1,10 @@
 import type { ClientSession } from '@astrale-os/sdk/client/session'
 import type { Node } from '@astrale-os/sdk/graph/node'
-import type { ResolvedClass } from '@astrale-os/sdk/schema'
 
 import { Path } from '@astrale-os/sdk/graph/path'
 import { Query } from '@astrale-os/sdk/query'
 
-import {
-  bindAdmin,
-  invokeAdminMethod,
-  requireAdminBinding,
-  requireAdminClass,
-  requireAdminCore,
-  requireAdminProperty,
-  type AdminBinding,
-} from '../binding'
+import { AdminContract, callAdminMethod } from '../contract'
 import { readAllNodes, type AdminGraphApi } from '../graph'
 import {
   AdminDomainNotFoundError,
@@ -38,31 +29,21 @@ export interface AdminCatalogApi {
 }
 
 export interface AdminCatalogDependencies {
-  readonly bind?: (session: ClientSession) => Promise<AdminBinding>
   readonly operationId?: (kind: 'publish' | 'configure-default') => string
 }
 
-/** Bind the discovered Admin revision and expose its Domain catalog journey. */
+/** Connect the Domain catalog journey without schema discovery or reflection. */
 export async function connectAdminCatalog(
   context: AdminCatalogContext,
   dependencies: AdminCatalogDependencies = {},
 ): Promise<AdminCatalogApi> {
-  const binding = requireAdminBinding(await (dependencies.bind ?? bindAdmin)(context.session))
-  const Domain = requireAdminClass(binding, 'Domain', 'node')
-  const Fleet = requireAdminClass(binding, 'Fleet', 'node')
-  const fleetInstallsByDefault = requireAdminClass(
-    binding,
-    'fleet_installs_domain_by_default',
-    'edge',
-  )
-  const fleet = requireAdminCore(binding, 'fleet')
   const operationId = dependencies.operationId ?? defaultOperationId
 
   const list = async (): Promise<DomainInfo[]> => {
     const [nodes, defaultsPage] = await Promise.all([
       readAllNodes(
         context.graph,
-        Query.from({ nodes: [Domain] }).select({
+        Query.from({ nodes: [AdminContract.classes.Domain] }).select({
           kind: 'nodes',
           projection: { kind: 'value' },
         }),
@@ -72,16 +53,20 @@ export async function connectAdminCatalog(
           maximumPages: MAXIMUM_PAGES,
         },
       ),
-      context.graph.neighbors(fleet, fleetInstallsByDefault, {
-        direction: 'outgoing',
-        page: { size: PAGE_SIZE },
-      }),
+      context.graph.neighbors(
+        AdminContract.fleet,
+        AdminContract.edges.fleetInstallsDomainByDefault,
+        {
+          direction: 'outgoing',
+          page: { size: PAGE_SIZE },
+        },
+      ),
     ])
     const defaults = await defaultsPage.collect({ maximumPages: MAXIMUM_PAGES })
     if (defaults.cursor !== null)
       throw new TypeError('Admin default Domain catalog exceeded its bound.')
     const defaultIds = new Set(defaults.nodes.map((node) => String(node.id)))
-    return nodes.map((node) => domainFromNode(Domain, node, defaultIds.has(String(node.id))))
+    return nodes.map((node) => domainFromNode(node, defaultIds.has(String(node.id))))
   }
 
   const requireDomain = async (identifier: string): Promise<DomainInfo> => {
@@ -110,7 +95,7 @@ export async function connectAdminCatalog(
       let entry = existing
       if (registryChanged) {
         entry = domainFromSummary(
-          await invokeAdminMethod(context.session, binding, Fleet, 'publishDomain', fleet, {
+          await callAdminMethod(context.session, AdminContract.fleet, 'publishDomain', {
             operationId: operationId('publish'),
             origin: input.origin,
             name: input.name,
@@ -127,17 +112,10 @@ export async function connectAdminCatalog(
         (entry.installByDefault ?? false) !== input.installByDefault
       if (defaultChanged) {
         entry = domainFromSummary(
-          await invokeAdminMethod(
-            context.session,
-            binding,
-            Domain,
-            'configureDefault',
-            Path.parse(entry.id),
-            {
-              operationId: operationId('configure-default'),
-              enabled: input.installByDefault,
-            },
-          ),
+          await callAdminMethod(context.session, Path.parse(entry.id), 'configureDefault', {
+            operationId: operationId('configure-default'),
+            enabled: input.installByDefault,
+          }),
           input.installByDefault === true,
         )
       }
@@ -150,29 +128,23 @@ export async function connectAdminCatalog(
   })
 }
 
-type DynamicDefinition = ResolvedClass<'node'>
-
-function domainFromNode(
-  definition: DynamicDefinition,
-  node: Node,
-  installByDefault: boolean,
-): DomainInfo {
+function domainFromNode(node: Node, installByDefault: boolean): DomainInfo {
   return Object.freeze({
     id: Path.id(node.id).raw,
-    origin: requiredProperty(definition, node, 'origin'),
-    name: requiredProperty(definition, node, 'name'),
-    url: requiredProperty(definition, node, 'discoveryUrl'),
-    ...optionalProperty(definition, node, 'description'),
+    origin: requiredProperty(node, 'origin'),
+    name: requiredProperty(node, 'name'),
+    url: requiredProperty(node, 'discoveryUrl'),
+    ...optionalProperty(node, 'description'),
     ...(installByDefault ? { installByDefault: true } : {}),
-    createdAt: requiredProperty(definition, node, 'createdAt'),
-    updatedAt: requiredProperty(definition, node, 'updatedAt'),
+    createdAt: requiredProperty(node, 'createdAt'),
+    updatedAt: requiredProperty(node, 'updatedAt'),
   })
 }
 
 function domainFromSummary(input: unknown, installByDefault: boolean): DomainInfo {
   const value = record(input, 'Admin Domain summary')
   return Object.freeze({
-    id: requiredString(value.id, 'Admin Domain id'),
+    id: requiredNodePath(value.id, 'Admin Domain id'),
     origin: requiredString(value.origin, 'Admin Domain origin'),
     name: requiredString(value.name, 'Admin Domain name'),
     url: requiredString(value.discoveryUrl, 'Admin Domain discovery URL'),
@@ -185,19 +157,15 @@ function domainFromSummary(input: unknown, installByDefault: boolean): DomainInf
   })
 }
 
-function requiredProperty(definition: DynamicDefinition, node: Node, name: string): string {
-  return requiredString(
-    node.props[requireAdminProperty(definition, name).key],
-    `Admin Domain.${name}`,
-  )
+function requiredProperty(node: Node, name: keyof typeof AdminContract.properties.domain): string {
+  return requiredString(node.props[AdminContract.properties.domain[name]], `Admin Domain.${name}`)
 }
 
 function optionalProperty(
-  definition: DynamicDefinition,
   node: Node,
-  name: string,
+  name: keyof typeof AdminContract.properties.domain,
 ): Readonly<Record<string, string>> {
-  const value = node.props[requireAdminProperty(definition, name).key]
+  const value = node.props[AdminContract.properties.domain[name]]
   return value === undefined ? {} : { [name]: requiredString(value, `Admin Domain.${name}`) }
 }
 
@@ -206,6 +174,15 @@ function requiredString(input: unknown, label: string): string {
   return input
 }
 
+function requiredNodePath(input: unknown, label: string): string {
+  const value = requiredString(input, label)
+  try {
+    return Path.parse(value).raw
+  } catch {
+    throw new TypeError(`${label} is invalid.`)
+  }
+}
+
 function record(input: unknown, label: string): Readonly<Record<string, unknown>> {
   if (typeof input !== 'object' || input === null || Array.isArray(input)) {
     throw new TypeError(`${label} is invalid.`)

package/src/admin/contract.ts

@@ -0,0 +1,46 @@
+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 { call } from '@astrale-os/sdk/client'
+import { Path } from '@astrale-os/sdk/graph/path'
+import { K, PropertyKey } from '@astrale-os/sdk/schema'
+
+const origin = 'admin.astrale.ai'
+
+function classRef(name: string): ClassRef {
+  return Object.freeze({ origin, kind: 'class', name }) as ClassRef
+}
+
+const Domain = classRef('Domain')
+
+export const AdminContract = Object.freeze({
+  origin,
+  fleet: Path.parse('/:admin.astrale.ai:core.fleet'),
+  classes: Object.freeze({
+    Domain,
+  }),
+  edges: Object.freeze({
+    fleetInstallsDomainByDefault: classRef('fleet_installs_domain_by_default'),
+  }),
+  properties: Object.freeze({
+    domain: Object.freeze({
+      origin: PropertyKey.of(Domain, 'origin'),
+      name: K.classes.Named.properties.name.key,
+      discoveryUrl: PropertyKey.of(Domain, 'discoveryUrl'),
+      description: K.classes.Descriptable.properties.description.key,
+      createdAt: K.classes.Timestamped.properties.createdAt.key,
+      updatedAt: K.classes.Timestamped.properties.updatedAt.key,
+    }),
+  }),
+})
+
+/** Invoke one stable Admin instance Method without schema discovery or reflection. */
+export function callAdminMethod(
+  session: ClientSession,
+  receiver: Path,
+  method: string,
+  input: Input,
+): Promise<unknown> {
+  return session.call(call(Path.instanceMethod(receiver, method), input))
+}

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

@@ -1,7 +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'
 
 export type InstanceState = 'provisioning' | 'ready' | 'deleting' | 'failed' | 'deleted'
 
@@ -11,10 +8,11 @@ export interface InstanceInfo {
   readonly url: string
   readonly hostId?: string
   readonly region?: string
-  readonly state?: InstanceState
+  readonly state: InstanceState
   readonly phase?: string
   readonly error?: string | null
   readonly createdAt?: string
+  readonly updatedAt?: string
   readonly organizationId?: string
 }
 
@@ -33,12 +31,11 @@ export interface DomainInstallReceipt {
 
 export interface AdminInstanceContext {
   readonly session: ClientSession
-  readonly graph: AdminGraphApi
 }
 
 export interface AdminInstanceApi {
   list(): Promise<OwnedInstanceInfo[]>
-  create(slug: string, hostId?: string): Promise<InstanceInfo>
+  create(slug: string): Promise<InstanceInfo>
   status(identifier: string): Promise<InstanceInfo>
   delete(identifier: string): Promise<InstanceInfo>
   installDomain(identifier: string, domain: string): Promise<DomainInstallReceipt>
@@ -51,7 +48,6 @@ export class AdminInstanceNotFoundError extends Error {
 }
 
 export interface AdminInstanceDependencies {
-  readonly bind?: (session: ClientSession) => Promise<DomainBinding>
   readonly operationId?: (kind: 'create' | 'status' | 'delete' | 'install-domain') => string
 }
 
@@ -63,4 +59,4 @@ export function findOwnedInstance(
   instances: readonly OwnedInstanceInfo[],
   identifier: string,
 ): OwnedInstanceInfo | undefined
-export function formatInstanceLocation(info: InstanceInfo): string
+export function formatInstanceState(info: InstanceInfo): string

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

@@ -1,10 +1,10 @@
 # CLI Admin Instance adapter
 
-The adapter discovers and binds the configured Admin Domain, proves its origin, and resolves the
-singleton Fleet receiver. Policy-visible `Instance` and `Host` Nodes come from bounded Graph queries;
-Host location is joined through `instance_runs_on_host`.
+The adapter calls the stable singleton Fleet receiver directly. Listing and automatic creation are
+one Admin Method call each; connection performs no schema discovery, introspection, or graph read.
+Every returned summary is decoded locally before it reaches a command.
 
-Automatic creation invokes `Fleet.createInstance`; explicit `--host-id` resolves one visible,
-non-reserved Host and invokes `Host.createInstance`. Status, deletion, and Domain installation
-invoke the exact Instance receiver. The adapter creates internal operation IDs but preserves the
-existing CLI projection and selection-required experience.
+Automatic creation invokes `Fleet.createInstance`. Status, deletion, and Domain installation first
+resolve a caller-visible Instance through Fleet and then invoke that exact Instance receiver. The
+adapter creates internal operation IDs but preserves the existing CLI projection and
+selection-required experience.

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

@@ -1,30 +1,25 @@
 import { describe, expect, test } from 'bun:test'
 
-import { adminBinding, adminSession } from '../../__tests__/fixture'
+import { adminSession } from '../../__tests__/fixture'
 import { connectAdminInstances } from '../client'
 
-function fixture(input: {
-  invoke?: (method: { owner: string; name: string }, receiver: unknown, input: unknown) => unknown
-}) {
+function fixture(input: { invoke?: (target: string, input: 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()
   return {
-    binding,
-    invoke: remote.invoke,
+    call: remote.call,
+    reflection: remote.reflection,
     calls,
     connect: () =>
       connectAdminInstances(
         { session: remote.session },
         {
-          bind: async () => binding,
           operationId: (kind) => `cli.instance.${kind}:test`,
         },
       ),
@@ -34,13 +29,15 @@ function fixture(input: {
 describe('V2 Admin Instance adapter', () => {
   test('lists caller-visible Instances through the Admin-owned Fleet operation', async () => {
     const contract = fixture({
-      invoke: (method) =>
-        method.name === 'listInstances'
+      invoke: (target) =>
+        target.endsWith('::listInstances')
           ? [
               {
                 id: '@instance-node',
                 slug: 'demo',
                 url: 'https://demo.eu.astrale.ai',
+                hostId: '@host-node',
+                region: 'fr-par',
                 state: 'ready',
                 createdAt: '2026-08-12T00:00:00.000Z',
                 updatedAt: '2026-08-12T00:00:00.000Z',
@@ -54,17 +51,20 @@ describe('V2 Admin Instance adapter', () => {
         id: '@instance-node',
         slug: 'demo',
         url: 'https://demo.eu.astrale.ai',
+        hostId: '@host-node',
+        region: 'fr-par',
         state: 'ready',
         createdAt: '2026-08-12T00:00:00.000Z',
+        updatedAt: '2026-08-12T00:00:00.000Z',
       },
     ])
     expect(contract.calls).toEqual([
       {
-        method: { owner: 'Fleet', name: 'listInstances' },
-        receiver: '/:admin.astrale.ai:core.fleet::listInstances',
+        target: '/:admin.astrale.ai:core.fleet::listInstances',
         value: {},
       },
     ])
+    expect(contract.reflection).not.toHaveBeenCalled()
   })
 
   test('delegates default placement to Fleet without reading Host inventory', async () => {
@@ -87,8 +87,7 @@ describe('V2 Admin Instance adapter', () => {
     })
     expect(contract.calls).toEqual([
       {
-        method: { owner: 'Fleet', name: 'createInstance' },
-        receiver: '/:admin.astrale.ai:core.fleet::createInstance',
+        target: '/:admin.astrale.ai:core.fleet::createInstance',
         value: { operationId: 'cli.instance.create:test', slug: 'demo' },
       },
     ])
@@ -96,8 +95,8 @@ describe('V2 Admin Instance adapter', () => {
 
   test('refreshes and deletes through the resolved Instance receiver', async () => {
     const contract = fixture({
-      invoke: (method) =>
-        method.name === 'listInstances'
+      invoke: (target) =>
+        target.endsWith('::listInstances')
           ? [
               {
                 id: '@instance-node',
@@ -112,25 +111,34 @@ describe('V2 Admin Instance adapter', () => {
               id: '@instance-node',
               slug: 'demo',
               url: 'https://demo.eu.astrale.ai',
-              state: method.name === 'delete' ? 'deleted' : 'ready',
+              state: target.endsWith('::delete') ? 'deleted' : 'ready',
+              createdAt: '2026-08-12T00:00:00.000Z',
+              updatedAt: '2026-08-12T00:00:00.000Z',
             },
     })
     const api = await contract.connect()
 
     await expect(api.status('demo')).resolves.toMatchObject({ state: 'ready' })
     await expect(api.delete('@instance-node')).resolves.toMatchObject({ state: 'deleted' })
-    expect(contract.calls.map(({ method }) => method)).toEqual([
-      { owner: 'Fleet', name: 'listInstances' },
-      { owner: 'Instance', name: 'status' },
-      { owner: 'Fleet', name: 'listInstances' },
-      { owner: 'Instance', name: 'delete' },
+    expect(contract.calls).toEqual([
+      { target: '/:admin.astrale.ai:core.fleet::listInstances', value: {} },
+      {
+        target: '@instance-node::status',
+        value: { operationId: 'cli.instance.status:test' },
+      },
+      { target: '/:admin.astrale.ai:core.fleet::listInstances', value: {} },
+      {
+        target: '@instance-node::delete',
+        value: { operationId: 'cli.instance.delete:test' },
+      },
     ])
+    expect(contract.reflection).not.toHaveBeenCalled()
   })
 
   test('installs a resolved catalog Domain through Instance.installDomain', async () => {
     const contract = fixture({
-      invoke: (method) =>
-        method.name === 'listInstances'
+      invoke: (target) =>
+        target.endsWith('::listInstances')
           ? [
               {
                 id: '@instance-node',
@@ -158,9 +166,108 @@ describe('V2 Admin Instance adapter', () => {
       ok: true,
     })
     expect(contract.calls.at(-1)).toEqual({
-      method: { owner: 'Instance', name: 'installDomain' },
-      receiver: '@instance-node::installDomain',
+      target: '@instance-node::installDomain',
       value: { operationId: 'cli.instance.install-domain:test', domain: '@crm-domain' },
     })
+    expect(contract.reflection).not.toHaveBeenCalled()
+  })
+
+  test('connects without network I/O and list performs exactly one call', async () => {
+    const contract = fixture({ invoke: () => [] })
+
+    const api = await contract.connect()
+    expect(contract.call).not.toHaveBeenCalled()
+    expect(contract.reflection).not.toHaveBeenCalled()
+
+    await expect(api.list()).resolves.toEqual([])
+    expect(contract.call).toHaveBeenCalledTimes(1)
+    expect(contract.reflection).not.toHaveBeenCalled()
+  })
+
+  test('rejects malformed inventory, lifecycle, Method, and install outputs', async () => {
+    await expect((await fixture({ invoke: () => ({}) }).connect()).list()).rejects.toThrow(
+      'Admin Instance inventory is invalid.',
+    )
+    await expect(
+      (
+        await fixture({
+          invoke: () => [{ id: '@instance-node', slug: 'demo', state: 'mystery' }],
+        }).connect()
+      ).list(),
+    ).rejects.toThrow('Admin Instance state is invalid.')
+    await expect(
+      (
+        await fixture({
+          invoke: () => [{ id: 'not-a-path', slug: 'demo', state: 'ready' }],
+        }).connect()
+      ).list(),
+    ).rejects.toThrow('Admin Instance id is invalid.')
+    await expect(
+      (
+        await fixture({
+          invoke: () => [
+            { id: '@instance-node', slug: 'demo', hostId: 'not-a-path', state: 'ready' },
+          ],
+        }).connect()
+      ).list(),
+    ).rejects.toThrow('Admin Host id is invalid.')
+
+    const malformedStatus = fixture({
+      invoke: (target) =>
+        target.endsWith('::listInstances')
+          ? [
+              {
+                id: '@instance-node',
+                slug: 'demo',
+                state: 'ready',
+                createdAt: '2026-08-12T00:00:00.000Z',
+                updatedAt: '2026-08-12T00:00:00.000Z',
+              },
+            ]
+          : {
+              id: '@instance-node',
+              slug: 'demo',
+              state: 'ready',
+              failure: {},
+              createdAt: '2026-08-12T00:00:00.000Z',
+              updatedAt: '2026-08-12T00:00:00.000Z',
+            },
+    })
+    await expect((await malformedStatus.connect()).status('demo')).rejects.toThrow(
+      'Admin failure message is invalid.',
+    )
+
+    const malformedInstall = fixture({
+      invoke: (target) =>
+        target.endsWith('::listInstances')
+          ? [
+              {
+                id: '@instance-node',
+                slug: 'demo',
+                state: 'ready',
+                createdAt: '2026-08-12T00:00:00.000Z',
+                updatedAt: '2026-08-12T00:00:00.000Z',
+              },
+            ]
+          : {
+              domain: '@crm-domain',
+              instance: '@instance-node',
+              origin: 'crm.acme.dev',
+              ok: 'yes',
+            },
+    })
+    await expect(
+      (await malformedInstall.connect()).installDomain('demo', '@crm-domain'),
+    ).rejects.toThrow('Admin Domain install outcome is invalid.')
+
+    const malformedInstallPath = fixture({
+      invoke: (target) =>
+        target.endsWith('::listInstances')
+          ? [{ id: '@instance-node', slug: 'demo', state: 'ready' }]
+          : { domain: 'not-a-path', instance: '@instance-node', origin: 'crm.acme.dev', ok: true },
+    })
+    await expect(
+      (await malformedInstallPath.connect()).installDomain('demo', '@crm-domain'),
+    ).rejects.toThrow('Admin Domain reference is invalid.')
   })
 })