@astrale-os/adapter-cloudflare 0.1.9 → 0.1.10

package/template/runtime/index.ts

@@ -1,11 +1,13 @@
 /**
  * Runtime composition root — the ONLY place request context (kernel/self/params/
  * auth) and `deps` meet the per-feature logic. Each `execute` resolves the port
- * it needs (`deps.summarizer()`, on-request) and delegates to the transport-
- * agnostic functions in `core/`. No business logic lives here.
+ * it needs (`deps.prober()`, on-request) and delegates to the per-operation I/O
+ * functions in `runtime/monitor/` (`watch`/`check`/`dependsOn`/`seed`), which in
+ * turn call `core/` for pure decisions. No business logic lives here.
  *
- *   - `createNote` is interface-hosted (static) → `remoteInterfaceMethods`.
- *   - `reference`  is class-hosted (instance)   → `remoteMethod` + `remoteClassMethods`.
+ *   - `watch`      is interface-hosted (static) → `remoteInterfaceMethods`.
+ *   - `check`      is class-hosted (instance)   → `remoteMethod` + `remoteClassMethods`.
+ *   - `dependsOn`  is class-hosted (instance).
  *   - `seed`       is class-hosted (static)     — the `postInstall` bootstrap.
  *
  * SDK-level `authorize` is an additive throw-to-deny check (returns void). For
@@ -20,43 +22,58 @@ import {
   type SchemaMethodsImpl,
 } from '@astrale-os/sdk'
 
-import { createNote, reference, seed } from '../core/note'
 import type { Deps } from '../deps'
+
+import { MONITOR_KEYS } from '../core/monitor'
 import { schema } from '../schema'
+import { check, dependsOn, seed, watch } from './monitor'
 
 const method = remoteMethod<Deps>()
 const interfaceMethods = remoteInterfaceMethods<Deps>()
 const classMethods = remoteClassMethods<Deps>()
 
-const NoteOpsMethods = interfaceMethods(schema, 'NoteOps', {
-  createNote: {
+const MonitorOpsMethods = interfaceMethods(schema, 'MonitorOps', {
+  watch: {
     authorize: async () => undefined,
-    execute: ({ kernel, params, deps }) => {
-      if (!kernel) throw new Error('createNote requires a kernel credential')
-      return createNote(kernel, deps.summarizer(), params)
+    execute: ({ kernel, params }) => {
+      return watch(kernel, params)
     },
   },
 })
 
-const referenceMethod = method(schema, 'Note', 'reference', {
+const checkMethod = method(schema, 'Monitor', 'check', {
+  authorize: async () => undefined,
+  execute: async ({ kernel, self, deps }) => {
+    if (!kernel) throw new Error('check requires a kernel credential')
+    const node = await self.node()
+    const url = node.props[MONITOR_KEYS.url]
+    if (typeof url !== 'string') throw new Error('Monitor node is missing its url property')
+    const prober = deps.prober({ class: node.class.raw, url })
+    return check(kernel, prober, self.path.raw, url)
+  },
+})
+
+const dependsOnMethod = method(schema, 'Monitor', 'dependsOn', {
   authorize: async () => undefined,
   execute: ({ kernel, self, params }) => {
-    if (!kernel) throw new Error('reference requires a kernel credential')
-    return reference(kernel, self.path.raw, params)
+    return dependsOn(kernel, self.path.raw, params)
   },
 })
 
-const seedMethod = method(schema, 'Note', 'seed', {
+const seedMethod = method(schema, 'Monitor', 'seed', {
   authorize: async () => undefined,
   execute: ({ kernel, deps }) => {
-    if (!kernel) throw new Error('seed requires a kernel credential')
-    return seed(kernel, deps.summarizer())
+    return seed(kernel, deps.prober())
   },
 })
 
-const NoteMethods = classMethods(schema, 'Note', { reference: referenceMethod, seed: seedMethod })
+const MonitorMethods = classMethods(schema, 'Monitor', {
+  check: checkMethod,
+  dependsOn: dependsOnMethod,
+  seed: seedMethod,
+})
 
 export const methods: SchemaMethodsImpl<typeof schema, Deps> = {
-  interface: { NoteOps: NoteOpsMethods },
-  class: { Note: NoteMethods },
+  interface: { MonitorOps: MonitorOpsMethods },
+  class: { Monitor: MonitorMethods },
 }

package/template/runtime/monitor/check.ts

@@ -0,0 +1,29 @@
+/**
+ * `Monitor.check` (instance) — probe the target via the resolved `Prober` port,
+ * classify the result (pure, `core/health`), and record status/latency back onto
+ * the node. `url` is the monitor's target and `prober` is already selected FOR
+ * this node (both resolved by the wiring in `runtime/index.ts` from `self.node()`).
+ */
+import { classify, MONITOR_KEYS } from '../../core/monitor'
+import type { Prober } from '../../integrations/prober/port'
+
+import type { CallableKernel } from './shared'
+
+export async function check(
+  kernel: CallableKernel,
+  prober: Prober,
+  selfPathRaw: string,
+  url: string,
+): Promise<{ status: string; statusCode: number; latencyMs: number }> {
+  const result = await prober.probe(url)
+  const status = classify(result.statusCode)
+  await kernel.call(`${selfPathRaw}::update`, {
+    props: {
+      [MONITOR_KEYS.status]: status,
+      [MONITOR_KEYS.statusCode]: result.statusCode,
+      [MONITOR_KEYS.latencyMs]: result.latencyMs,
+      [MONITOR_KEYS.lastCheckedAt]: new Date().toISOString(),
+    },
+  })
+  return { status, statusCode: result.statusCode, latencyMs: result.latencyMs }
+}

package/template/runtime/monitor/dependsOn.ts

@@ -0,0 +1,16 @@
+/**
+ * `Monitor.dependsOn` (instance) — link this Monitor to another it relies on via
+ * a `depends_on` edge. `target` is any node address (a tree path or `@<id>`).
+ */
+import { DEPENDS_ON_EDGE } from '../../core/monitor'
+
+import type { CallableKernel } from './shared'
+
+export async function dependsOn(
+  kernel: CallableKernel,
+  selfPathRaw: string,
+  params: { target: string },
+): Promise<{ linked: string }> {
+  await kernel.call(`${selfPathRaw}::link`, { edgeClass: DEPENDS_ON_EDGE, target: params.target })
+  return { linked: params.target }
+}

package/template/runtime/monitor/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Monitor runtime operations — one file per method, assembled here. The
+ * composition root (`runtime/index.ts`) imports these and wires them into the
+ * methods map. Each is transport-agnostic logic over a `CallableKernel` (+ the
+ * `Prober` port where it probes), delegating pure decisions to `core/` — so all
+ * are unit-testable with fakes.
+ */
+export { check } from './check'
+export { dependsOn } from './dependsOn'
+export { seed } from './seed'
+export { watch } from './watch'
+export type { CallableKernel } from './shared'

package/template/runtime/monitor/seed.ts

@@ -0,0 +1,74 @@
+/**
+ * `Monitor.seed` (static) — the domain's post-install bootstrap. The kernel calls
+ * it ONCE after install, as __SYSTEM__ (see `postInstall` in `domain.ts`), so the
+ * domain can lay down its initial state: the `/monitors` folder, a couple of
+ * starter Monitors (each probed once so they show real status immediately), and a
+ * `depends_on` edge between them. Idempotent: a re-run swallows `PATH_CONFLICT`
+ * per node (the starters use fixed slugs).
+ */
+import {
+  classify,
+  DEPENDS_ON_EDGE,
+  FOLDER_CLASS,
+  MONITOR_CLASS,
+  MONITOR_KEYS,
+  MONITORS_PARENT,
+  NAME_KEY,
+  NODE_CREATE,
+  STARTERS,
+} from '../../core/monitor'
+import type { Prober } from '../../integrations/prober/port'
+
+import { type CallableKernel, isPathConflict } from './shared'
+
+export async function seed(kernel: CallableKernel, prober: Prober): Promise<{ seeded: number }> {
+  // 1. The `/monitors` folder at the graph root.
+  try {
+    await kernel.call(NODE_CREATE, {
+      class: FOLDER_CLASS,
+      path: MONITORS_PARENT,
+      props: { [NAME_KEY]: 'monitors' },
+    })
+  } catch (e) {
+    if (!isPathConflict(e)) throw e
+  }
+
+  // 2. A couple of starter Monitors, each probed once for an initial status.
+  const ids: Record<string, string> = {}
+  let seeded = 0
+  for (const s of STARTERS) {
+    try {
+      const result = await prober.probe(s.url)
+      const created = (await kernel.call(NODE_CREATE, {
+        class: MONITOR_CLASS,
+        path: `${MONITORS_PARENT}/${s.slug}`,
+        props: {
+          [NAME_KEY]: s.name,
+          [MONITOR_KEYS.url]: s.url,
+          [MONITOR_KEYS.status]: classify(result.statusCode),
+          [MONITOR_KEYS.statusCode]: result.statusCode,
+          [MONITOR_KEYS.latencyMs]: result.latencyMs,
+          [MONITOR_KEYS.lastCheckedAt]: new Date().toISOString(),
+        },
+      })) as { id: string }
+      ids[s.slug] = created.id
+      seeded++
+    } catch (e) {
+      if (!isPathConflict(e)) throw e
+    }
+  }
+
+  // 3. Link the first starter as depending on the second (id-form on both sides
+  //    — layout-independent). Best-effort.
+  const from = ids[STARTERS[0]?.slug ?? '']
+  const to = ids[STARTERS[1]?.slug ?? '']
+  if (from && to) {
+    try {
+      await kernel.call(`@${from}::link`, { edgeClass: DEPENDS_ON_EDGE, target: `@${to}` })
+    } catch (e) {
+      if (!isPathConflict(e)) throw e
+    }
+  }
+
+  return { seeded }
+}

package/template/runtime/monitor/shared.ts

@@ -0,0 +1,17 @@
+/**
+ * Runtime-internal helpers shared across the Monitor operations (`watch`,
+ * `check`, `dependsOn`, `seed`). Not exported from the domain — just the seam the
+ * operation files agree on.
+ */
+
+/**
+ * The minimal kernel surface the operations need — kept narrow so each is
+ * unit-testable with a fake `{ call }`. The SDK hands the real client at the
+ * `runtime/index.ts` seam.
+ */
+export type CallableKernel = { call(path: string, params: unknown): Promise<unknown> }
+
+/** True for the kernel's create-collision error — lets `seed` stay idempotent. */
+export function isPathConflict(e: unknown): boolean {
+  return e instanceof Error && e.message.includes('PATH_CONFLICT')
+}

package/template/runtime/monitor/watch.ts

@@ -0,0 +1,37 @@
+import type { CallableKernel } from './shared'
+
+/**
+ * `MonitorOps.watch` (static) — create a Monitor node under `/monitors`. The slug
+ * FORMAT is pure (`core/monitor`'s `monitorSlug`); the entropy suffix (impure,
+ * clock/RNG) is generated HERE, keeping core deterministic.
+ */
+import {
+  MONITOR_CLASS,
+  MONITOR_KEYS,
+  MONITORS_PARENT,
+  monitorSlug,
+  NAME_KEY,
+  NODE_CREATE,
+} from '../../core/monitor'
+
+/** Short clock+RNG entropy to dodge same-ms / same-host slug collisions. */
+function randomSuffix(): string {
+  return `${Date.now().toString(36).slice(-4)}${Math.random().toString(36).slice(2, 6)}`
+}
+
+export async function watch(
+  kernel: CallableKernel,
+  params: { url: string; name?: string },
+): Promise<{ id: string; path: string }> {
+  const path = `${MONITORS_PARENT}/${monitorSlug(params.url, randomSuffix())}`
+  const created = (await kernel.call(NODE_CREATE, {
+    class: MONITOR_CLASS,
+    path,
+    props: {
+      [NAME_KEY]: params.name ?? params.url,
+      [MONITOR_KEYS.url]: params.url,
+      [MONITOR_KEYS.status]: 'unknown',
+    },
+  })) as { id: string }
+  return { id: created.id, path }
+}

package/template/schema/index.ts

@@ -11,13 +11,20 @@
 import { defineSchema, KernelSchema } from '@astrale-os/kernel-core'
 import { compileDomain, type Domain } from '@astrale-os/kernel-core/domain'
 
-import { Note, NoteOps, references } from './note'
+import { depends_on, Monitor, MonitorOps } from './monitor'
 
 export const schema = defineSchema('astrale-domain.example.dev', {
-  interfaces: { NoteOps },
-  classes: { Note, references },
+  interfaces: { MonitorOps },
+  classes: { Monitor, depends_on },
   imports: [KernelSchema],
 })
+
+/**
+ * The compiled domain — resolved class/interface paths + qualified prop keys.
+ * `compileDomain` is pure (no env), so this is safe to import from the worker
+ * and from build tooling alike. `core/keys.ts` re-exports it as the single source
+ * of graph-facing strings (class paths, prop keys) — never hand-write those.
+ */
 export const D: Domain<typeof schema> = compileDomain(schema)
 
-export * from './note'
+export * from './monitor'

package/template/schema/monitor.ts

@@ -0,0 +1,80 @@
+/**
+ * Monitor context — the domain's single bounded slice.
+ *
+ * One file per context: a class (or a few tightly-related classes) plus the
+ * edges that bind them. Here that is the `MonitorOps` interface, the `Monitor`
+ * class that implements it, and the `depends_on` edge from one Monitor to
+ * another. To grow the domain, add `schema/<context>.ts` and register its
+ * members in `schema/index.ts`.
+ *
+ *   - Interface `MonitorOps`  one static op, `watch`. Static → the impl gets no
+ *                             `self`; it creates a brand-new Monitor.
+ *   - Class `Monitor`         implements `[MonitorOps, Container]`, inheriting
+ *                             `watch` and adding instance methods `check`
+ *                             (probe + record live status) and `dependsOn`
+ *                             (links this Monitor to one it relies on).
+ *   - Edge `depends_on`       Monitor → Monitor. A dependency graph of checks,
+ *                             materialized by `dependsOn` (and by `seed`).
+ */
+import { edgeClass, KernelSchema, nodeClass, nodeInterface } from '@astrale-os/kernel-core'
+import { fn } from '@astrale-os/kernel-dsl'
+import { z } from 'zod'
+
+/**
+ * Thin ref to a created node — what node-creating ops return. A remote method
+ * returns a plain `{ id, path }`, never `ref(SELF)` (whose full-Node value does
+ * not round-trip over the worker wire).
+ */
+export const MonitorRef = z.object({ id: z.string(), path: z.string() })
+
+/** What a single probe records — returned by `check`. */
+export const ProbeOutcome = z.object({
+  status: z.string(),
+  statusCode: z.number().int(),
+  latencyMs: z.number().int(),
+})
+
+export const MonitorOps = nodeInterface({
+  methods: {
+    watch: fn({
+      static: true,
+      params: { url: z.string(), name: z.string().optional() },
+      returns: MonitorRef,
+    }),
+  },
+})
+
+export const Monitor = nodeClass({
+  implements: [MonitorOps, KernelSchema.interfaces.Container],
+  props: {
+    /** The target URL this monitor probes. */
+    url: z.string(),
+    // Live status, written by `check`. PLAIN STRING, not `z.enum()`: `::update`
+    // currently drops `z.enum()` props silently, and `check` updates this.
+    // Values: 'up' | 'down' | 'unknown' (the initial value before the first check).
+    status: z.string().optional(),
+    /** Last observed HTTP status code (0 = host unreachable). */
+    statusCode: z.number().int().optional(),
+    /** Last observed round-trip latency, in ms. */
+    latencyMs: z.number().int().optional(),
+    /** ISO timestamp of the last check. */
+    lastCheckedAt: z.string().optional(),
+  },
+  methods: {
+    // Instance: probe the target via the resolved `Prober` port (the external
+    // integration), then record status/latency back onto this node.
+    check: fn({ returns: ProbeOutcome }),
+    // Instance: link this Monitor to another it depends on (a `depends_on` edge).
+    dependsOn: fn({ params: { target: z.string() }, returns: z.object({ linked: z.string() }) }),
+    // Post-install bootstrap (wired as `postInstall` in domain.ts). Static: the
+    // kernel calls it ONCE after install, as __SYSTEM__, with no `self`. Must
+    // stay idempotent — a re-install runs it again.
+    seed: fn({ static: true, returns: z.object({ seeded: z.number().int() }) }),
+  },
+})
+
+export const depends_on = edgeClass(
+  { as: 'dependent', types: [Monitor] },
+  { as: 'dependency', types: [Monitor] },
+  { props: { reason: z.string().optional() } },
+)

package/template/views/index.ts

@@ -3,8 +3,15 @@
  * key; each becomes a View node at `/<origin>/core/views/<slug>` whose iframe
  * binding the SDK stamps with the worker's live serving URL when it builds the
  * install bundle.
+ *
+ * `welcome` is a worker-rendered inline-HTML view (no SPA). `ui-monitor` and
+ * `ui-monitor-badge` are BOTH served by the one `client/` SPA — it routes on the
+ * mount path (`/ui/monitor` vs `/ui/monitor-badge`) to pick which view to render.
  */
-import { note } from './note'
+import { monitor } from './monitor'
 import { welcome } from './welcome'
 
-export const views = { welcome, 'ui-note': note }
+export const views = {
+  welcome,
+  'ui-monitor': monitor,
+}

package/template/views/monitor.ts

@@ -0,0 +1,22 @@
+/**
+ * `ui-monitor` — a rich View backed by the `client/` React + Vite SPA (instead of
+ * an inline-HTML `render` like `welcome`). Because it declares `mount` rather
+ * than `render`, the View node's iframe binding points at
+ * `<serving url>/ui/monitor` — the SDK stamps it from the worker's live URL when
+ * it builds the install bundle. The Cloudflare adapter serves `/ui/*` from
+ * `../.dist` (built by `client/` with base `/ui/`) via the Worker's `ASSETS`
+ * binding.
+ *
+ * `viewFor: selfOf(Monitor)` attaches a `view_for` edge to the `Monitor` class
+ * meta-node, so the GUI offers this view for any Monitor instance.
+ */
+import { selfOf } from '@astrale-os/kernel-dsl'
+import { defineView } from '@astrale-os/sdk'
+
+import { Monitor } from '../schema/monitor'
+
+export const monitor = defineView({
+  auth: 'public',
+  mount: '/ui/monitor',
+  viewFor: selfOf(Monitor),
+})

package/template/client/src/lib/kernel.ts

@@ -1,135 +0,0 @@
-/**
- * Minimal, self-contained kernel JSON client — just enough to load a node via
- * `@<id>::get`, without pulling in `@astrale-os/kernel-client` (and its
- * transitive deps). It reproduces the kernel ENVELOPE wire shape inline.
- *
- * Wire contract (authoritative source: `kernel/api/envelope/`):
- *   - Request:  POST <kernelUrl> with headers
- *       content-type: application/vnd.astrale.kernel+json
- *       accept:       application/vnd.astrale.kernel+json
- *       authorization: <delegationToken>      (BARE token — no "Bearer " prefix)
- *     body JSON `{ method, params, id }` (see `encode.ts:encodeKernelRequest`).
- *   - Response: JSON, exactly one of (decode precedence error → redirect → result,
- *     mirroring `decode.ts:decodeKernelResponse`):
- *       { error: { code, message }, id }   → throw Error("<code>: <message>")
- *       { redirect, id }                   → throw (we don't follow redirects here)
- *       { result, id }                     → return result
- *
- * Deliberately JSON-only: no msgpack codec, no streaming/binary, no redirect
- * following, no schema/batching. Those live in `@astrale-os/kernel-client`,
- * which this self-contained build omits on purpose.
- */
-
-// From `kernel/api/envelope/types.ts` (KERNEL_CONTENT_TYPE_JSON). Inlined so the
-// template needs no @astrale-os import.
-const KERNEL_CONTENT_TYPE_JSON = 'application/vnd.astrale.kernel+json'
-
-// Module-local monotonic request id. Strings keep ids stable across reloads and
-// distinguishable in logs; the kernel echoes `id` back but we don't correlate
-// (one request per fetch).
-let idSeq = 0
-function nextId(): string {
-  idSeq += 1
-  return `c${idSeq}`
-}
-
-/**
- * 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 (`title`, `body`) 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.body')`.
- */
-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
-}
-
-/**
- * POST a single kernel call and return its `result`. Throws on a kernel error
- * envelope or an unexpected redirect. `token` is the bare delegation credential
- * from the shell handshake; the iframe authenticates SOLELY with it (the parent
- * minted it for this kernel, so the audience already matches — no cookie/mint).
- */
-export async function kernelCall(
-  kernelUrl: string,
-  token: string,
-  method: string,
-  params: Record<string, unknown> = {},
-): Promise<unknown> {
-  // The kernel routes on a trailing slash; the parent absolutizes the URL, but
-  // not always with the slash, so normalize here.
-  const url = kernelUrl.endsWith('/') ? kernelUrl : `${kernelUrl}/`
-  const id = nextId()
-
-  const res = await fetch(url, {
-    method: 'POST',
-    headers: {
-      'content-type': KERNEL_CONTENT_TYPE_JSON,
-      accept: KERNEL_CONTENT_TYPE_JSON,
-      authorization: token,
-    },
-    body: JSON.stringify({ method, params, id }),
-  })
-
-  let body: unknown
-  try {
-    body = await res.json()
-  } catch {
-    throw new Error(`kernel returned a non-JSON response (HTTP ${res.status})`)
-  }
-
-  if (body === null || typeof body !== 'object') {
-    throw new Error(`kernel returned an unexpected response (HTTP ${res.status})`)
-  }
-  const obj = body as Record<string, unknown>
-
-  // Decode precedence error → redirect → result (mirrors decodeKernelResponse).
-  if ('error' in obj && 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}`)
-  }
-  if ('redirect' in obj && obj.redirect) {
-    // Redirects (remote-domain Functions) aren't followed by this minimal
-    // client — they require credential re-minting against the target worker.
-    throw new Error('unexpected redirect from kernel (not supported by the template client)')
-  }
-  return obj.result
-}