@astrale-os/adapter-cloudflare 0.1.9 → 0.2.0

package/template/client/__tests__/harness.ts

@@ -1,7 +1,11 @@
 /**
- * Test harness — a FAKE shell parent + a FAKE kernel, so the client's inline
- * handshake (`src/lib/shell.ts`) and JSON kernel client (`src/lib/kernel.ts`)
- * can be exercised with no real GUI/kernel.
+ * Test harness — a FAKE shell parent + a FAKE kernel, so the client's shell
+ * handshake (now `@astrale-os/shell`, `createShell({ mode: 'sandboxed' })`) and
+ * its kernel calls can be exercised with no real GUI/kernel.
+ *
+ * `fakeKernelSession()` is the unit-test counterpart: a `KernelClient` whose
+ * `call` hits the fake kernel directly (no handshake), for hooks tested in
+ * isolation.
  *
  * The fake parent mirrors `runParentHandshake`
  * (`shell/packages/shell/src/application/windowing/handshake.ts`):
@@ -17,6 +21,8 @@
  * the child believes it is framed.
  */
 
+import type { KernelClient } from '@/shell'
+
 const INIT_REQUEST_TYPE = 'astrale-shell/init-request'
 const INIT_RESPONSE_TYPE = 'astrale-shell/init-response'
 
@@ -196,26 +202,70 @@ export function ok(result: unknown): { result: unknown } {
   return { result }
 }
 
-/** Build a minimal kernel Note node whose props carry title/body. */
-export function noteNode(opts: {
+/**
+ * A `KernelClient` for unit tests that exercise feature hooks WITHOUT a
+ * handshake. Its `call` POSTs the kernel JSON envelope (`{ method, params, id }`)
+ * so the `installFakeKernel` fetch stub records it and `body.method`/
+ * `body.params` assertions hold — same wire the real `shell.kernel` speaks to a
+ * JSON kernel. The credential surface (`mintDelegation`/`authToken`/`url`) is
+ * stubbed minimally — the isolated hooks under test only ever touch `call`.
+ */
+export function fakeKernelSession(kernelUrl = 'https://k.example.test/api'): KernelClient {
+  let idSeq = 0
+  return {
+    async call(method: string, params: unknown = {}): Promise<unknown> {
+      idSeq += 1
+      const res = await fetch(kernelUrl, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/vnd.astrale.kernel+json',
+          accept: 'application/vnd.astrale.kernel+json',
+          authorization: 'tok-A',
+        },
+        body: JSON.stringify({ method, params, id: `c${idSeq}` }),
+      })
+      const obj = (await res.json()) as Record<string, unknown>
+      if (obj.error && typeof obj.error === 'object') {
+        const err = obj.error as { code?: unknown; message?: unknown }
+        const code = typeof err.code === 'number' ? err.code : 5000
+        const message = typeof err.message === 'string' ? err.message : 'Unknown error'
+        throw new Error(`${code}: ${message}`)
+      }
+      return obj.result
+    },
+    mintDelegation: async () => '<fake>',
+    authToken: () => '<fake>',
+    url: kernelUrl,
+  }
+}
+
+/**
+ * Build a minimal kernel `Checkable` node — a StatusPage (or any class via
+ * `className`, default `StatusPage`). Carries a domain-qualified `status` prop
+ * (`<domain>:class.<className>.property.status`); the name uses the kernel
+ * `Named.name` key.
+ */
+export function checkableNode(opts: {
   id: string
   path?: string
   name?: string
-  title?: string
-  body?: string
+  status?: string
+  className?: string
   domain?: string
 }): { id: string; path: string; class: { raw: string }; props: Record<string, unknown> } {
-  const domain = opts.domain ?? 'notes.astrale.ai'
+  const domain = opts.domain ?? 'monitors.astrale.ai'
+  const className = opts.className ?? 'StatusPage'
   const props: Record<string, unknown> = {}
   if (opts.name !== undefined) {
     props['kernel.astrale.ai:interface.Named.property.name'] = opts.name
   }
-  if (opts.title !== undefined) props[`${domain}:class.Note.property.title`] = opts.title
-  if (opts.body !== undefined) props[`${domain}:class.Note.property.body`] = opts.body
+  if (opts.status !== undefined) {
+    props[`${domain}:class.${className}.property.status`] = opts.status
+  }
   return {
     id: opts.id,
-    path: opts.path ?? `/notes/${opts.id}`,
-    class: { raw: `/:${domain}:class.Note` },
+    path: opts.path ?? `/${opts.id}`,
+    class: { raw: `/:${domain}:class.${className}` },
     props,
   }
 }

package/template/client/__tests__/kernel.test.ts

@@ -1,68 +1,57 @@
-import { afterEach, describe, expect, it } from 'vitest'
+import { describe, expect, it } from 'vitest'
 
-import { kernelCall, readProp, readPropBySuffix } from '../src/lib/kernel'
-import { installFakeKernel } from './harness'
+import { qualifiedString, readProp, readPropBySuffix } from '@/shell'
+import { checkableFromNode } from '@/status'
+import { relativeTime } from '@/ui'
 
-const TYPE = 'application/vnd.astrale.kernel+json'
+import { checkableNode } from './harness'
 
-describe('kernelCall — inline JSON envelope client', () => {
-  let restore: (() => void) | undefined
-  afterEach(() => {
-    restore?.()
-    restore = undefined
+describe('prop readers', () => {
+  it('readProp returns the string value at the exact key', () => {
+    expect(readProp({ a: 'x', b: 1 }, 'a')).toBe('x')
+    expect(readProp({ a: 'x' }, 'missing')).toBeUndefined()
+    expect(readProp({ a: 1 }, 'a')).toBeUndefined() // non-string
   })
 
-  it('POSTs the envelope with a trailing slash, bare token, and kernel content type', async () => {
-    const k = installFakeKernel(() => ({ result: { ok: true } }))
-    restore = k.restore
-    const result = await kernelCall('https://k.test/api', 'tok-X', '@n1::get', {})
-    expect(result).toEqual({ ok: true })
-
-    const req = k.calls[0]!
-    expect(req.method).toBe('POST')
-    expect(req.url).toBe('https://k.test/api/') // slash added
-    expect(req.headers['authorization']).toBe('tok-X')
-    expect(req.headers['content-type']).toBe(TYPE)
-    expect(req.headers['accept']).toBe(TYPE)
-    expect(req.body).toMatchObject({ method: '@n1::get', params: {} })
-    expect(req.body.id).toBeTruthy()
+  it('readPropBySuffix matches the first key ending with the suffix', () => {
+    const props = {
+      'monitors.astrale.ai:class.Monitor.property.url': 'https://x.test',
+      'kernel.astrale.ai:interface.Named.property.name': 'n',
+    }
+    expect(readPropBySuffix(props, '.property.url')).toBe('https://x.test')
+    expect(readPropBySuffix(props, '.property.status')).toBeUndefined()
   })
 
-  it('does not double the trailing slash when the URL already ends in one', async () => {
-    const k = installFakeKernel(() => ({ result: 1 }))
-    restore = k.restore
-    await kernelCall('https://k.test/api/', 'tok', '@n::get')
-    expect(k.calls[0]!.url).toBe('https://k.test/api/')
+  it('qualifiedString prefers a domain key over the kernel one for the same suffix', () => {
+    const props = {
+      'kernel.astrale.ai:interface.Named.property.name': 'kernel name',
+      'monitors.astrale.ai:class.Monitor.property.name': 'domain name',
+    }
+    expect(qualifiedString(props, 'name')).toBe('domain name')
   })
+})
 
-  it('throws "<code>: <message>" on a kernel error envelope', async () => {
-    const k = installFakeKernel(() => ({ error: { code: 2004, message: 'Permission denied' } }))
-    restore = k.restore
-    await expect(kernelCall('https://k.test/api', 't', '@n::get')).rejects.toThrow(
-      '2004: Permission denied',
+describe('checkableFromNode mapper', () => {
+  it('projects the name and rolled-up status of a StatusPage node', () => {
+    const record = checkableFromNode(
+      checkableNode({ id: 'page-1', name: 'Public', status: 'degraded', className: 'StatusPage' }),
     )
+    expect(record).toEqual({ name: 'Public', status: 'degraded' })
   })
 
-  it('throws on an unexpected redirect envelope', async () => {
-    const k = installFakeKernel(() => ({ redirect: { url: 'https://other.test/api' } }))
-    restore = k.restore
-    await expect(kernelCall('https://k.test/api', 't', '@n::get')).rejects.toThrow(/redirect/)
+  it('falls back to the path segment for the name and unknown for a missing status', () => {
+    const record = checkableFromNode(checkableNode({ id: 'page-9', path: '/status-pages/edge' }))
+    expect(record.name).toBe('edge')
+    expect(record.status).toBe('unknown')
   })
 })
 
-describe('prop readers', () => {
-  it('readProp returns the string value at the exact key', () => {
-    expect(readProp({ a: 'x', b: 1 }, 'a')).toBe('x')
-    expect(readProp({ a: 'x' }, 'missing')).toBeUndefined()
-    expect(readProp({ a: 1 }, 'a')).toBeUndefined() // non-string
-  })
-
-  it('readPropBySuffix matches the first key ending with the suffix', () => {
-    const props = {
-      'notes.astrale.ai:class.Note.property.body': 'the body',
-      'kernel.astrale.ai:interface.Named.property.name': 'n',
-    }
-    expect(readPropBySuffix(props, '.property.body')).toBe('the body')
-    expect(readPropBySuffix(props, '.property.title')).toBeUndefined()
+describe('relativeTime', () => {
+  const now = Date.parse('2026-06-14T12:00:00Z')
+  it('renders coarse buckets and a dash for missing input', () => {
+    expect(relativeTime(undefined, now)).toBe('—')
+    expect(relativeTime('2026-06-14T11:55:00Z', now)).toBe('5m ago')
+    expect(relativeTime('2026-06-14T10:00:00Z', now)).toBe('2h ago')
+    expect(relativeTime('not-a-date', now)).toBe('not-a-date')
   })
 })

package/template/client/__tests__/seam.test.tsx

@@ -0,0 +1,115 @@
+/**
+ * What the presentation/logic seam unlocks:
+ *
+ *  1. PRESENTATION components (`@/ui`) test with ZERO infrastructure — no fake
+ *     shell, no fake kernel, no session. Just props in, DOM out. (Contrast
+ *     app.test.tsx, which stands up a handshake + kernel stub to reach the same
+ *     markup.)
+ *  2. FEATURE hooks (`@/status`) test against a bare `KernelClient` (the fake
+ *     kernel fetch stub) with no handshake — the write lifecycle and the
+ *     reload signal are verified once, in isolation.
+ */
+import { act, cleanup, render, renderHook, screen, waitFor } from '@testing-library/react'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { useCheck, useCheckable } from '@/status'
+import { StatusBadge } from '@/ui'
+
+import { checkableNode, fakeKernelSession, installFakeKernel, ok } from './harness'
+
+afterEach(cleanup)
+
+describe('presentation is pure (no kernel, no session, no shell)', () => {
+  it('StatusBadge renders the label and tone class for each status', () => {
+    const { rerender } = render(<StatusBadge status="up" />)
+    expect(screen.getByText('UP').className).toContain('status-up')
+
+    rerender(<StatusBadge status="degraded" />)
+    expect(screen.getByText('DEGRADED').className).toContain('status-degraded')
+
+    rerender(<StatusBadge status="down" />)
+    expect(screen.getByText('DOWN').className).toContain('status-down')
+
+    rerender(<StatusBadge status="weird" />)
+    expect(screen.getByText('UNKNOWN').className).toContain('status-unknown')
+  })
+})
+
+describe('useCheckable — query + reload signal', () => {
+  it('loads the record, then exposes reloading across a reload()', async () => {
+    const session = fakeKernelSession()
+    let status = 'down'
+    const kernel = installFakeKernel(() => ok(checkableNode({ id: 'page-1', name: 'API', status })))
+
+    try {
+      const { result } = renderHook(() => useCheckable(session, 'page-1'))
+      await waitFor(() => expect(result.current.state).toBe('ok'))
+      expect(result.current.record?.status).toBe('down')
+      expect(result.current.reloading).toBe(false)
+
+      // Server-side status flips; a reload picks it up and flags `reloading`.
+      status = 'up'
+      act(() => {
+        result.current.reload()
+      })
+      expect(result.current.reloading).toBe(true)
+
+      await waitFor(() => expect(result.current.reloading).toBe(false))
+      expect(result.current.record?.status).toBe('up')
+    } finally {
+      kernel.restore()
+    }
+  })
+
+  it('surfaces a node-load error', async () => {
+    const session = fakeKernelSession()
+    const kernel = installFakeKernel(() => ({ error: { code: 3002, message: 'Path not found' } }))
+    try {
+      const { result } = renderHook(() => useCheckable(session, 'missing'))
+      await waitFor(() => expect(result.current.state).toBe('error'))
+      expect(result.current.message).toMatch(/Path not found/)
+    } finally {
+      kernel.restore()
+    }
+  })
+})
+
+describe('useCheck — the shared write-lifecycle', () => {
+  it('idle → running → done, then resolves true', async () => {
+    const session = fakeKernelSession()
+    const kernel = installFakeKernel(() => ok(null))
+    try {
+      const { result } = renderHook(() => useCheck(session, 'page-1'))
+      expect(result.current.phase).toBe('idle')
+
+      let returned: boolean | undefined
+      await act(async () => {
+        returned = await result.current.run()
+      })
+      expect(returned).toBe(true)
+      expect(result.current.phase).toBe('done')
+      expect(result.current.error).toBeNull()
+    } finally {
+      kernel.restore()
+    }
+  })
+
+  it('captures a failure: phase failed, error set, resolves false', async () => {
+    const session = fakeKernelSession()
+    const kernel = installFakeKernel(() => ({
+      error: { code: 2004, message: 'Permission denied' },
+    }))
+    try {
+      const { result } = renderHook(() => useCheck(session, 'page-1'))
+      let returned: boolean | undefined
+      await act(async () => {
+        returned = await result.current.run()
+      })
+      expect(returned).toBe(false)
+      expect(result.current.phase).toBe('failed')
+      expect(result.current.error).toMatch(/Permission denied/)
+    } finally {
+      kernel.restore()
+    }
+  })
+})

package/template/client/index.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>astrale-domain · ui-note</title>
+    <title>astrale-domain · view</title>
   </head>
   <body>
     <div id="root"></div>

package/template/client/package.json

@@ -11,6 +11,7 @@
     "test": "vitest run"
   },
   "dependencies": {
+    "@astrale-os/shell": ">=0.1.0 <1.0.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
   },

package/template/client/src/app.tsx

@@ -1,94 +1,45 @@
-import type { NodeSession } from './lib/use-node'
-
-import { classShortName, type KernelNode, PROP, readProp, readPropBySuffix } from './lib/kernel'
-import { useNode } from './lib/use-node'
-import { useShell } from './lib/use-shell'
-
 /**
- * The `ui-note` view. Mounted by the Astrale shell as a sandboxed iframe; the
- * parent completes the handshake (see `lib/shell.ts`) and pushes the target
- * node id this view renders. The view then loads that Note from the kernel via
- * a minimal inline JSON client (`lib/kernel.ts`, `@<id>::get`) and renders its
- * title/body — no `@astrale-os/*` deps.
+ * Path-based view router for the domain's SPA bundle. The shell mounts each Astrale
+ * View in its own iframe at its own mount path, so inside the iframe
+ * `window.location.pathname` IS that path. `App` reads it (via `resolveView`) and
+ * renders the matching view; an unregistered path shows a self-describing fallback.
+ *
+ * Today there's one view — the StatusPage panel at `/ui/status-page`. The router
+ * (not a direct render) is the extension seam: add a view by
+ *   1. writing a `ViewComponent` (usually wrapping `ViewFrame` — see `views/`),
+ *   2. adding a `ROUTES` entry keyed by its mount path,
+ *   3. registering a matching `defineView({ mount: '/ui/<path>' })` in `views/`.
  */
-export function App() {
-  const { status, session, nodeId, reason } = useShell()
-
-  return (
-    <div className="wrap">
-      <div className="card">
-        {status === 'loading' && (
-          <>
-            <h1 className="title">Note</h1>
-            <p className="subline">ui-note · Astrale view SPA</p>
-            <p className="muted">Waiting for the shell handshake…</p>
-          </>
-        )}
 
-        {status === 'standalone' && (
-          <>
-            <h1 className="title">Note</h1>
-            <p className="subline">ui-note · Astrale view SPA</p>
-            <div className="banner">
-              No parent shell ({reason}). This view is meant to be mounted by the Astrale GUI, which
-              hands it a target node and a kernel token. Showing a standalone preview.
-            </div>
-            <p className="body muted">
-              When mounted by the shell, this card renders the Note you opened.
-            </p>
-          </>
-        )}
+import { resolveView, useShell, type ViewRoutes } from '@/shell'
+import { StatusView } from '@/views/status'
 
-        {status === 'ready' && session && <NoteCard session={session} nodeId={nodeId} />}
-      </div>
-    </div>
-  )
+const ROUTES: ViewRoutes = {
+  '/ui/status-page': StatusView,
 }
 
-/**
- * Renders one Note, loaded from the kernel via the live session. Split out so
- * `useNode` is called unconditionally (the parent only mounts this once the
- * handshake is `ready`, so `session` is non-null here).
- */
-function NoteCard({ session, nodeId }: { session: NodeSession; nodeId: string | undefined }) {
-  const state = useNode(session, nodeId)
-
-  const title =
-    state.status === 'ok' ? (readProp(state.node.props, PROP.named.name) ?? 'Note') : 'Note'
-
-  return (
-    <>
-      <h1 className="title">{title}</h1>
-      <p className="subline">
-        {state.status === 'ok'
-          ? `${classShortName(state.node)} · ${state.node.path}`
-          : 'ui-note · Astrale view SPA'}
-      </p>
-
-      {state.status === 'idle' && (
-        <p className="body muted">Handshake complete, but no target node / token yet.</p>
-      )}
-
-      {state.status === 'loading' && <p className="muted">Loading the Note…</p>}
+export function App() {
+  const shell = useShell()
+  const View = resolveView(ROUTES)
 
-      {state.status === 'error' && (
-        <div className="banner">Failed to load the Note: {state.message}</div>
-      )}
+  if (!View) return <UnknownView />
 
-      {state.status === 'ok' && <NoteBody node={state.node} />}
-    </>
-  )
+  return <>{View(shell)}</>
 }
 
-/**
- * The Note's `body` prop. Its key is domain-qualified
- * (`<domain>:class.Note.property.body`), so read it by suffix rather than a
- * build-time-unknown full key.
- */
-function NoteBody({ node }: { node: KernelNode }) {
-  const body = readPropBySuffix(node.props, '.property.body')
-  if (!body) {
-    return <p className="body muted">This Note has no body.</p>
-  }
-  return <p className="body">{body}</p>
+/** Fallback when the iframe's mount path has no registered view. */
+function UnknownView() {
+  return (
+    <div className="wrap">
+      <div className="card">
+        <h1 className="title">No view here</h1>
+        <p className="subline">Astrale view SPA</p>
+        <div className="banner">
+          No view registered for {window.location.pathname}. Add a ROUTES entry in{' '}
+          <code>src/app.tsx</code> (and a matching <code>defineView({'{ mount }'})</code> in the
+          domain's <code>views/</code>).
+        </div>
+      </div>
+    </div>
+  )
 }

package/template/client/src/main.tsx

@@ -1,9 +1,9 @@
 import { createRoot } from 'react-dom/client'
 
 import './styles.css'
-import { App } from './app'
+import { App } from '@/app'
 
 const root = document.getElementById('root')
-if (!root) throw new Error('ui-note client: #root missing from index.html')
+if (!root) throw new Error('astrale view client: #root missing from index.html')
 
 createRoot(root).render(<App />)

package/template/client/src/shell/client.ts

@@ -0,0 +1,67 @@
+/**
+ * Graph/prop helpers for the nodes the kernel returns — reading fully-qualified
+ * props and short class names off a `KernelNode`. Pure shaping: the kernel
+ * TRANSPORT now lives in `@astrale-os/shell` (`shell.kernel` → `session.call`),
+ * so this file no longer speaks the wire.
+ */
+
+/**
+ * Prop key constants — the graph stores props with fully-qualified keys
+ * (`<domain>:<member>.property.<name>`). The kernel `Named.name` key is fixed
+ * and known; domain props (`url`, `status`) are qualified by the (build-time
+ * unknown) domain origin — read those by suffix with `readPropBySuffix`.
+ */
+export const PROP = {
+  named: {
+    name: 'kernel.astrale.ai:interface.Named.property.name',
+  },
+} as const
+
+export type KernelNode = {
+  id: string
+  path: string
+  class: string | { raw?: string }
+  props: Record<string, unknown>
+}
+
+export function readProp(props: Record<string, unknown>, key: string): string | undefined {
+  const v = props[key]
+  return typeof v === 'string' ? v : undefined
+}
+
+/**
+ * Read a string prop by key suffix — for domain-qualified props whose full key
+ * embeds the (build-time-unknown) domain origin. e.g.
+ * `readPropBySuffix(props, '.property.url')`.
+ */
+export function readPropBySuffix(
+  props: Record<string, unknown>,
+  suffix: string,
+): string | undefined {
+  for (const [k, v] of Object.entries(props)) {
+    if (k.endsWith(suffix) && typeof v === 'string') return v
+  }
+  return undefined
+}
+
+/** Short class name from a `class.raw` path `/:<domain>:class.<Name>` → `<Name>`. */
+export function classShortName(node: KernelNode): string {
+  const raw = (typeof node.class === 'string' ? node.class : node.class?.raw) ?? ''
+  const last = raw.split(':').pop() ?? ''
+  const dot = last.indexOf('.')
+  return dot >= 0 ? last.slice(dot + 1) : last
+}
+
+/**
+ * Operator-facing message for a failed kernel call. Errors from the shell's
+ * kernel client carry a numeric `code` (e.g. `NotFoundError` → `code 3002`) with
+ * the raw server text in `message`; surface them as `<code>: <message>` so the
+ * code stays visible. Plain errors fall back to their message.
+ */
+export function errorMessage(err: unknown): string {
+  if (err instanceof Error) {
+    const code = (err as { code?: unknown }).code
+    return typeof code === 'number' ? `${code}: ${err.message}` : err.message
+  }
+  return String(err)
+}

package/template/client/src/shell/index.ts

@@ -0,0 +1,20 @@
+/**
+ * The kernel boundary — everything for talking to the kernel and the GUI
+ * shell, plus the common read/write primitives features build their
+ * `.query`/`.mutation` hooks on. Import from the barrel: `@/shell`.
+ */
+export { classShortName, errorMessage, PROP, readProp, readPropBySuffix } from './client'
+export type { KernelNode } from './client'
+export { callMethod, invokeNode, nodeAddr } from './invoke'
+export type { KernelClient } from '@astrale-os/shell'
+export { useNode } from './use-node'
+export type { NodeState } from './use-node'
+export { useShell } from './use-shell'
+export type { ShellState, ShellStatus } from './use-shell'
+export { useAsync } from './use-async'
+export type { AsyncResource, AsyncState } from './use-async'
+export { useCapability } from './use-capability'
+export type { Capability, Phase } from './use-capability'
+export { asNodeArray, linkTargets, qualifiedProp, qualifiedString } from './transformers'
+export { resolveView, ViewFrame } from './view-router'
+export type { ViewComponent, ViewRoutes } from './view-router'

package/template/client/src/shell/invoke.ts

@@ -0,0 +1,35 @@
+/**
+ * Kernel invocation primitives — the single place a view reaches the kernel,
+ * over the shell's proper `KernelClient` (`session.call`, wired by the sandboxed
+ * handshake: fresh delegation token per call, redirects followed). `callMethod`
+ * is the generic method-ref call; `invokeNode` is instance dispatch by node id
+ * (`@<id>::<method>` — the shell hands views node IDs, not paths); `nodeAddr`
+ * picks the stable address for a node.
+ */
+import type { KernelClient } from '@astrale-os/shell'
+
+import type { KernelNode } from './client'
+
+/** One kernel call through the live session (proper client: fresh token, redirects). */
+export function callMethod(
+  session: KernelClient,
+  method: string,
+  params: Record<string, unknown> = {},
+): Promise<unknown> {
+  return session.call(method, params)
+}
+
+/** Instance-method dispatch by node id. */
+export function invokeNode(
+  session: KernelClient,
+  nodeId: string,
+  method: string,
+  params: Record<string, unknown> = {},
+): Promise<unknown> {
+  return callMethod(session, `@${nodeId}::${method}`, params)
+}
+
+/** Stable instance address: tree path when known, else `@id`. */
+export function nodeAddr(node: KernelNode): string {
+  return node.path && node.path.startsWith('/') ? node.path : `@${node.id}`
+}