@astrale-os/adapter-cloudflare 0.3.0 → 0.3.2

package/template/README.md

@@ -1,9 +1,12 @@
 # astrale-domain
 
-
 A standalone [Astrale](https://astrale.ai) domain, deployed as an Astrale-managed
 service (default) or as a worker on your own Cloudflare account.
 
+This is a **blank skeleton** — every folder is wired up and ready, but the domain
+ships with no classes, interfaces, views, or integrations. Fill in the terrain;
+nothing here is a demo you have to delete.
+
 ## For AI agents
 
 The complete domain-authoring guide is the `astrale-domain` skill (schema
@@ -30,30 +33,36 @@ astrale domain install <url> --direct    # mount it on an instance (CLI)
 pnpm prod                         # deploy prod → prints a URL
 ```
 
+A freshly-scaffolded skeleton deploys and installs as-is (an empty domain with no
+members) — then you add classes and handlers.
+
 ## What you write
 
 ```
-schema/        classes + interfaces (the data model) + compiled accessors
-core/<context>/ pure, transport-agnostic logic per bounded context (e.g. core/monitor)
+schema/        classes + interfaces + edges (the data model) + compiled accessors
+icons.ts       class icons (raw SVG), attached via nodeClass({ icon })
+core/<context>/ pure, transport-agnostic logic per bounded context
 integrations/  external-API ports + adapters + a lazy registry (built into deps)
 runtime/       the execute() handlers — the composition root (the methods map)
-views/         iframe-mountable UIs
-functions/     standalone Functions (e.g. webhooks)
+views/         iframe-mountable UIs (inline HTML or a client/ SPA)
+functions/     standalone Functions (e.g. webhooks, a postInstall seed)
 client/        the SPA served under /ui
 deps.ts        env → typed Deps container (what handlers read as ctx.deps)
 domain.ts      wires it all together — the worker-safe definition
 astrale.config.ts   binds the domain to its deploy adapter (node-only)
 ```
 
-`domain.ts` is the one place the domain contract is declared: it imports the
-modules above and passes them to `defineDomain({ schema, methods, deps, views,
-functions, … })` alongside the identity (`origin`, `requires`, `postInstall`).
-Nothing is discovered by folder name — a renamed or mistyped module is a compile
-error at that call, never a silently-missing route. Drop a field (`deps`,
-`views`, `functions`) when the domain has none. `astrale.config.ts` then binds
-that domain to a deploy adapter with `deploy(domain, cloudflare({ … }))` and
-chooses, per env, which `client` assets serve mounted `/ui` views — keeping the
-node-only adapter (wrangler, filesystem, frontend builds) out of the worker
+`schema/`, `runtime/`, `views/`, and `functions/` start with empty registries;
+`core/` and `integrations/` are empty folders with a short README each explaining
+the pattern. `domain.ts` is the one place the domain contract is declared: it
+imports the modules above and passes them to `defineDomain({ schema, methods,
+deps, views, functions, … })` alongside the identity (`origin`, `requires`,
+`postInstall`). Nothing is discovered by folder name — a renamed or mistyped
+module is a compile error at that call, never a silently-missing route. Drop a
+field (`deps`, `views`, `functions`) when the domain has none. `astrale.config.ts`
+then binds that domain to a deploy adapter with `deploy(domain, cloudflare({ … }))`
+and chooses, per env, which `client` assets serve mounted `/ui` views — keeping
+the node-only adapter (wrangler, filesystem, frontend builds) out of the worker
 bundle.
 
 Everything else — the Worker entry, the wrangler config, the signing identity —
@@ -97,11 +106,11 @@ adapter-owned keys `name`, `main`, `assets`, `routes` are rejected (use
 
 - **Edit a handler** (`core/` logic or `runtime/` wiring) → hot-reloads at the same URL. Nothing to reinstall.
 - **Edit the schema** (`schema/`) → rebuilds the graph; reinstall with `astrale domain install <url> --direct`.
-- **`postInstall`** (the static `Monitor.seed` method) runs once after install, as
-  the system identity, so the domain can seed `/monitoring/monitors` and
-  `/monitoring/pages/status` and set its own grants. It
-  must be a class-hosted static addressed by a typed colon-path
-  (`/:origin:class.X:seed`) — the kernel refuses tree paths here.
+- **`postInstall`** — author a standalone `seed` function in `functions/`, reference
+  it from `domain.ts` (`postInstall: functions.seed`), and the kernel runs it once
+  after install, as the system identity, so the domain can lay down its initial
+  graph and set its own grants. Functions are first-class domain members,
+  addressable at `/:origin:function.seed`.
 
 ## Identity
 

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

@@ -1,275 +1,66 @@
-import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { cleanup, render, renderHook, screen, waitFor } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 
 import { App } from '@/app'
+import { useShell } from '@/shell'
 
-import { checkableNode, installFakeKernel, installFakeParent, ok } from './harness'
-
-const KERNEL_URL = 'https://k.example.test/api'
+import { installFakeParent, type FakeParent } from './harness'
 
 /**
- * The router picks a view from `window.location.pathname`, so every test mounts
- * at the StatusPage view's path. `replaceState` rewrites the happy-dom location
- * without a reload; the fallback test overrides it.
+ * The router picks a view from `window.location.pathname`. This skeleton has no
+ * views registered, so every path falls through to the fallback — that's the
+ * test below. The second block exercises the shell handshake plumbing (via the
+ * fake parent) so you know the seam works the moment you add a real view.
+ *
+ * `replaceState` rewrites the happy-dom location without a reload.
  */
 function mountAt(path: string) {
   window.history.replaceState({}, '', path)
 }
 
 beforeEach(() => {
-  mountAt('/ui/status-page')
-})
-
-afterEach(() => {
-  cleanup()
+  mountAt('/ui/anything')
 })
 
-/**
- * Let the handshake + any kernel fetches settle, flushing the resulting React
- * state updates inside `act`. The handshake completes over a real MessagePort
- * (async hops), so a microtask isn't enough — a short timer pump is.
- */
-async function flush(ms = 20) {
-  await act(async () => {
-    await new Promise((r) => setTimeout(r, ms))
-  })
-}
+afterEach(cleanup)
 
-function handshake(targetNodeId?: string) {
-  return installFakeParent({
-    windowId: 'win-1',
-    kernelUrl: KERNEL_URL,
-    functionId: 'ui-status-page',
-    delegationToken: 'tok-A',
-    tokenExpiresAt: Date.now() + 3_600_000,
-    targetNodeId,
+describe('router fallback (no views registered)', () => {
+  it('renders the self-describing fallback for any path', () => {
+    render(<App />)
+    expect(screen.getByText('No view here')).toBeTruthy()
+    expect(screen.getByText(/No view registered for/)).toBeTruthy()
   })
-}
-
-/** A StatusPage node fixture — its rolled-up `status`, no `url`. */
-const page = (id: string, status: string, name = 'Public status') =>
-  checkableNode({ id, name, status, className: 'StatusPage' })
-
-const MONITOR_PATH = '/monitoring/monitors/astrale'
-
-const watchLinks = (critical = true) => [
-  {
-    class: { raw: '/:monitors.astrale.ai:class.watches' },
-    target: { raw: MONITOR_PATH },
-    props: { 'monitors.astrale.ai:class.watches.property.critical': critical },
-  },
-]
-
-const monitor = (status: string, statusCode = 200) =>
-  checkableNode({
-    id: 'monitor-1',
-    path: MONITOR_PATH,
-    name: 'Astrale homepage',
-    status,
-    statusCode,
-    latencyMs: 84,
-    lastCheckedAt: '2026-06-14T11:55:00Z',
-    url: 'https://astrale.ai',
-    className: 'Monitor',
-  })
-
-describe('status view (/ui/status-page)', () => {
-  it('loads the StatusPage node and renders its watched monitors', async () => {
-    const parent = handshake('page-1')
-    const kernel = installFakeKernel((body) => {
-      if (body.method === '@page-1::get') return ok(page('page-1', 'degraded'))
-      if (body.method === '@page-1::getLinks') return ok(watchLinks())
-      if (body.method === `${MONITOR_PATH}::get`) return ok(monitor('up'))
-      return { error: { code: 3002, message: `unexpected: ${body.method}` } }
-    })
-
-    try {
-      render(<App />)
-      await flush()
-
-      // Parent observed the child's handshakeAck.
-      await expect(parent.ack).resolves.toBeUndefined()
-
-      expect(screen.getByText('Public status')).toBeTruthy()
-      const badge = screen.getByText('DEGRADED')
-      expect(badge.className).toContain('status-degraded')
-      expect(screen.getByText('Astrale homepage')).toBeTruthy()
-      expect(screen.getByText('astrale.ai')).toBeTruthy()
-      expect(screen.getByText('Critical')).toBeTruthy()
-      expect(screen.getByText('84ms')).toBeTruthy()
-
-      expect(kernel.calls.map((c) => c.body.method)).toEqual([
-        '@page-1::get',
-        '@page-1::getLinks',
-        `${MONITOR_PATH}::get`,
-      ])
-    } finally {
-      kernel.restore()
-      parent.restore()
-    }
-  })
-
-  it('clicks "Check now", issues @<id>::check, and reflects the refreshed status', async () => {
-    const parent = handshake('page-1')
-    // First ::get is down; ::check rolls up server-side; the post-check ::get is up.
-    let checked = false
-    const kernel = installFakeKernel((body) => {
-      if (body.method === '@page-1::check') {
-        checked = true
-        return ok(null)
-      }
-      if (body.method === '@page-1::getLinks') return ok(watchLinks())
-      if (body.method === `${MONITOR_PATH}::get`) return ok(monitor(checked ? 'up' : 'down'))
-      return ok(page('page-1', checked ? 'up' : 'down'))
-    })
-
-    try {
-      render(<App />)
-      await flush()
-
-      expect(screen.getAllByText('DOWN').length).toBeGreaterThan(0)
-      expect(kernel.calls).toHaveLength(3)
-      expect(kernel.calls[0]!.body.method).toBe('@page-1::get')
-
-      await act(async () => {
-        fireEvent.click(screen.getByText('Check now'))
-      })
-      await flush()
-
-      // A ::check call was issued, then the node was re-fetched.
-      expect(kernel.calls.map((c) => c.body.method)).toEqual([
-        '@page-1::get',
-        '@page-1::getLinks',
-        `${MONITOR_PATH}::get`,
-        '@page-1::check',
-        '@page-1::get',
-        '@page-1::getLinks',
-        `${MONITOR_PATH}::get`,
-      ])
-      expect(screen.getAllByText('UP').length).toBeGreaterThan(0)
-    } finally {
-      kernel.restore()
-      parent.restore()
-    }
-  })
-
-  it('surfaces a check failure without losing the loaded record', async () => {
-    const parent = handshake('page-1')
-    const kernel = installFakeKernel((body) => {
-      if (body.method === '@page-1::check') {
-        return { error: { code: 2004, message: 'Permission denied' } }
-      }
-      if (body.method === '@page-1::getLinks') return ok(watchLinks())
-      if (body.method === `${MONITOR_PATH}::get`) return ok(monitor('up'))
-      return ok(page('page-1', 'up'))
-    })
-
-    try {
-      render(<App />)
-      await flush()
-
-      await act(async () => {
-        fireEvent.click(screen.getByText('Check now'))
-      })
-      await flush()
-
-      // The proper client maps the error code to a typed error, so the operator
-      // sees the clean server message (no `<code>:` prefix).
-      expect(screen.getByText(/Check failed:/)).toBeTruthy()
-      expect(screen.getByText(/Permission denied/)).toBeTruthy()
-      // The record is still shown.
-      expect(screen.getByText('Public status')).toBeTruthy()
-    } finally {
-      kernel.restore()
-      parent.restore()
-    }
-  })
-
-  it('renders the kernel error on the node-load error path', async () => {
-    const parent = handshake('missing-1')
-    const kernel = installFakeKernel(() => ({ error: { code: 3002, message: 'Path not found' } }))
+})
 
-    try {
-      render(<App />)
-      await flush()
+describe('shell handshake plumbing', () => {
+  let parent: FakeParent | undefined
 
-      expect(screen.getByText(/Failed to load/)).toBeTruthy()
-      expect(screen.getByText(/Path not found/)).toBeTruthy()
-    } finally {
-      kernel.restore()
-      parent.restore()
-    }
+  afterEach(() => {
+    parent?.restore()
+    parent = undefined
   })
 
-  it('re-fetches on a setTarget hot-swap', async () => {
-    const parent = handshake('page-1')
-    const kernel = installFakeKernel((body) => {
-      if (body.method.endsWith('::getLinks')) return ok([])
-      return body.method === '@page-2::get'
-        ? ok(page('page-2', 'down', 'Internal status'))
-        : ok(page('page-1', 'up', 'Public status'))
+  it('reaches `ready` with a kernel session after the parent handshake', async () => {
+    parent = installFakeParent({
+      windowId: 'w-1',
+      kernelUrl: 'https://k.example.test/api',
+      functionId: 'fn-1',
+      delegationToken: 'tok-A',
+      tokenExpiresAt: Date.now() + 60_000,
+      targetNodeId: 'node-1',
     })
 
-    try {
-      render(<App />)
-      await flush()
-      expect(screen.getByText('Public status')).toBeTruthy()
-      expect(screen.getAllByText('UP').length).toBeGreaterThan(0)
-
-      // Parent pushes a new target node.
-      parent.setTarget('page-2')
-      await flush()
-
-      expect(screen.getByText('Internal status')).toBeTruthy()
-      expect(screen.getByText('DOWN')).toBeTruthy()
-    } finally {
-      kernel.restore()
-      parent.restore()
-    }
-  })
-
-  it('explains a missing target instead of a blank screen', async () => {
-    const parent = handshake(undefined)
-    const kernel = installFakeKernel(() => ok(null))
-    try {
-      render(<App />)
-      await flush()
-
-      expect(screen.getByText(/No target node/)).toBeTruthy()
-      expect(kernel.calls).toHaveLength(0)
-    } finally {
-      kernel.restore()
-      parent.restore()
-    }
+    const { result } = renderHook(() => useShell())
+    // waitFor polls inside `act`, so the handshake's async state updates land
+    // wrapped — the parent's `ack` promise need not be awaited separately.
+    await waitFor(() => expect(result.current.status).toBe('ready'))
+    expect(result.current.session).not.toBeNull()
+    expect(result.current.nodeId).toBe('node-1')
   })
 
   it('falls back to a standalone preview with no parent', async () => {
-    // No fake parent → the shell sees window.parent === window and stands alone.
-    const kernel = installFakeKernel(() => ok(null))
-    try {
-      render(<App />)
-      await flush()
-
-      expect(screen.getByText(/No parent shell/)).toBeTruthy()
-      expect(kernel.calls).toHaveLength(0)
-    } finally {
-      kernel.restore()
-    }
-  })
-})
-
-describe('router fallback', () => {
-  it('renders "No view registered" for an unregistered path', async () => {
-    mountAt('/ui/nope')
-    const kernel = installFakeKernel(() => ok(null))
-    try {
-      render(<App />)
-      await flush()
-
-      expect(screen.getByText(/No view registered for \/ui\/nope/)).toBeTruthy()
-      expect(kernel.calls).toHaveLength(0)
-    } finally {
-      kernel.restore()
-    }
+    const { result } = renderHook(() => useShell())
+    await waitFor(() => expect(result.current.status).toBe('standalone'))
+    expect(result.current.session).toBeNull()
   })
 })

package/template/client/__tests__/harness.ts

@@ -238,50 +238,3 @@ export function fakeKernelSession(kernelUrl = 'https://k.example.test/api'): Ker
     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
-  status?: string
-  url?: string
-  statusCode?: number
-  latencyMs?: number
-  lastCheckedAt?: string
-  className?: string
-  domain?: string
-}): { id: string; path: string; class: { raw: string }; props: Record<string, unknown> } {
-  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.status !== undefined) {
-    props[`${domain}:class.${className}.property.status`] = opts.status
-  }
-  if (opts.url !== undefined) {
-    props[`${domain}:class.${className}.property.url`] = opts.url
-  }
-  if (opts.statusCode !== undefined) {
-    props[`${domain}:class.${className}.property.statusCode`] = opts.statusCode
-  }
-  if (opts.latencyMs !== undefined) {
-    props[`${domain}:class.${className}.property.latencyMs`] = opts.latencyMs
-  }
-  if (opts.lastCheckedAt !== undefined) {
-    props[`${domain}:class.${className}.property.lastCheckedAt`] = opts.lastCheckedAt
-  }
-  return {
-    id: opts.id,
-    path: opts.path ?? `/${opts.id}`,
-    class: { raw: `/:${domain}:class.${className}` },
-    props,
-  }
-}

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

@@ -0,0 +1,46 @@
+/**
+ * The kernel-boundary plumbing every view builds on, tested with ZERO
+ * infrastructure — no shell, no kernel, no session. Props in, values out. These
+ * are the helpers `@/shell` exposes for reading qualified node props (which the
+ * kernel stores under domain-prefixed keys) plus the shared display formatters.
+ * Your feature mappers (`<feature>.mappers.ts`) build on these.
+ */
+import { describe, expect, it } from 'vitest'
+
+import { qualifiedString, readProp, readPropBySuffix } from '@/shell'
+import { relativeTime } from '@/ui'
+
+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 = {
+      'acme.example.dev:class.Widget.property.label': 'Hello',
+      'kernel.astrale.ai:interface.Named.property.name': 'n',
+    }
+    expect(readPropBySuffix(props, '.property.label')).toBe('Hello')
+    expect(readPropBySuffix(props, '.property.status')).toBeUndefined()
+  })
+
+  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',
+      'acme.example.dev:class.Widget.property.name': 'domain name',
+    }
+    expect(qualifiedString(props, 'name')).toBe('domain name')
+  })
+})
+
+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/package.json

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

package/template/client/src/app.tsx

@@ -4,19 +4,17 @@
  * `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/`),
+ * `ROUTES` starts EMPTY — this is a blank skeleton, so every path falls through to
+ * `UnknownView`. Add a view by
+ *   1. writing a `ViewComponent` (usually wrapping `ViewFrame` — see `@/shell`),
  *   2. adding a `ROUTES` entry keyed by its mount path,
- *   3. registering a matching `defineView({ mount: '/ui/<path>' })` in `views/`.
+ *   3. registering a matching `defineView({ mount: '/ui/<path>' })` in the domain's
+ *      `views/`.
  */
 
 import { resolveView, useShell, type ViewRoutes } from '@/shell'
-import { StatusView } from '@/views/status'
 
-const ROUTES: ViewRoutes = {
-  '/ui/status-page': StatusView,
-}
+const ROUTES: ViewRoutes = {}
 
 export function App() {
   const shell = useShell()

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

@@ -16,5 +16,6 @@ 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 type { GraphEdge } from './transformers'
 export { resolveView, ViewFrame } from './view-router'
 export type { ViewComponent, ViewRoutes } from './view-router'

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

@@ -1,8 +1,11 @@
 /**
- * Graph-response transformers at the kernel boundary — turn raw `::get` /
- * `::listChildren` / `::getLinks` payloads into the shapes features consume.
- * Domain-neutral: per-class node→record mappers live in each feature's
- * `*.mappers.ts` and build on `qualifiedString` here.
+ * Graph-shape helpers at the kernel boundary — turn `shell.kernel.graph` results
+ * (`graph.node` / `graph.children` / `graph.links`, backed by `function.get`)
+ * into the shapes features consume. Domain-neutral: per-class node→record mappers
+ * live in each feature's `*.mappers.ts` and build on `qualifiedString` here.
+ *
+ * The graph sugar already returns typed records (`{ nodes }`, `{ edges }`) — no
+ * envelope-sniffing needed — so these are thin projections over those shapes.
  *
  * Props are stored under QUALIFIED keys
  * (`monitors.astrale.ai:class.Monitor.property.url`). The client must not import
@@ -13,6 +16,15 @@
  */
 import type { KernelNode } from './client'
 
+/** One incident edge as `shell.kernel.graph.links` returns it (a `GraphEdgeWire`). */
+export type GraphEdge = {
+  class: string
+  source: string
+  target: string
+  slug?: string | null
+  props?: Record<string, unknown>
+}
+
 /** Resolve a prop by `.property.<name>` suffix; domain keys win over kernel ones. */
 export function qualifiedProp(props: Record<string, unknown>, name: string): unknown {
   const suffix = `.property.${name}`
@@ -33,40 +45,31 @@ export function qualifiedString(props: Record<string, unknown>, name: string): s
   return typeof v === 'string' && v !== '' ? v : undefined
 }
 
-type RawLink = { class?: unknown; edgeClass?: unknown; target?: unknown; to?: unknown }
-
 /**
- * Targets of a `::getLinks` response whose edge class ends with `classTail`
- * (e.g. `'monitor_on_host'`). Tolerates bare-array and `{ links }` envelopes,
- * and both `target`/`to` + `class`/`edgeClass`.
+ * Targets of `graph.links` edges whose edge class ends with `classTail`
+ * (e.g. `'monitor_on_host'`). Accepts the `graph.links` result (`{ edges }`) or a
+ * bare `GraphEdge[]`.
  */
-export function linkTargets(raw: unknown, classTail: string): string[] {
-  const links: RawLink[] = Array.isArray(raw)
-    ? (raw as RawLink[])
-    : ((raw as { links?: RawLink[] } | null)?.links ?? [])
+export function linkTargets(
+  edges: GraphEdge[] | { edges: GraphEdge[] } | null | undefined,
+  classTail: string,
+): string[] {
+  const list: GraphEdge[] = Array.isArray(edges) ? edges : (edges?.edges ?? [])
   const out: string[] = []
-  for (const link of links) {
-    const cls =
-      typeof link.class === 'string'
-        ? link.class
-        : typeof link.edgeClass === 'string'
-          ? link.edgeClass
-          : ''
-    if (!cls.endsWith(classTail)) continue
-    const target =
-      typeof link.target === 'string'
-        ? link.target
-        : typeof link.to === 'string'
-          ? link.to
-          : undefined
-    if (target) out.push(target)
+  for (const edge of list) {
+    if (typeof edge.class !== 'string' || !edge.class.endsWith(classTail)) continue
+    if (typeof edge.target === 'string') out.push(edge.target)
   }
   return out
 }
 
-/** A `::listChildren` response as a node array (bare array or enveloped). */
-export function asNodeArray(raw: unknown): KernelNode[] {
-  if (Array.isArray(raw)) return raw as KernelNode[]
-  const obj = raw as { children?: KernelNode[]; nodes?: KernelNode[] } | null
-  return obj?.children ?? obj?.nodes ?? []
+/**
+ * The nodes of a `graph.children` / `graph.tree` result. Accepts the sugar result
+ * (`{ nodes }`) or a bare `KernelNode[]`.
+ */
+export function asNodeArray(
+  result: KernelNode[] | { nodes: KernelNode[] } | null | undefined,
+): KernelNode[] {
+  if (Array.isArray(result)) return result
+  return result?.nodes ?? []
 }