@astrale-os/adapter-cloudflare 0.1.9 → 0.2.0

package/template/runtime/index.ts

@@ -1,62 +1,91 @@
 /**
  * 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.
+ * auth) and `deps` meet the per-feature logic. Each `execute` resolves what it
+ * needs (the `Prober` port, the self node) and delegates to the per-operation I/O
+ * functions in `runtime/monitor/` and `runtime/status-page/`. No business logic
+ * lives here.
  *
- *   - `createNote` is interface-hosted (static) → `remoteInterfaceMethods`.
- *   - `reference`  is class-hosted (instance)   → `remoteMethod` + `remoteClassMethods`.
- *   - `seed`       is class-hosted (static)     — the `postInstall` bootstrap.
+ * `check` is the `Checkable` interface method, declared `abstract`, so it is
+ * implemented PER CLASS (Monitor probes; StatusPage rolls up) — wired under
+ * `class.Monitor` / `class.StatusPage`, NOT a shared `interface` block. The
+ * kernel dispatches `@<node>::check` to the impl for that node's class.
  *
  * SDK-level `authorize` is an additive throw-to-deny check (returns void). For
  * finer worker checks see `assertPerm` / `requireOwnership` from `@astrale-os/sdk`.
- *
- * Exports the `methods` map the domain definition (`domain.ts`) wires in.
  */
-import {
-  remoteClassMethods,
-  remoteInterfaceMethods,
-  remoteMethod,
-  type SchemaMethodsImpl,
-} from '@astrale-os/sdk'
-
-import { createNote, reference, seed } from '../core/note'
+import { remoteClassMethods, remoteMethod, type SchemaMethodsImpl } from '@astrale-os/sdk'
+
 import type { Deps } from '../deps'
+
+import { MONITOR_KEYS } from '../core/monitor'
 import { schema } from '../schema'
+import { check as monitorCheck, seed, watch } from './monitor'
+import { add, check as pageCheck, create } from './status-page'
 
 const method = remoteMethod<Deps>()
-const interfaceMethods = remoteInterfaceMethods<Deps>()
 const classMethods = remoteClassMethods<Deps>()
 
-const NoteOpsMethods = interfaceMethods(schema, 'NoteOps', {
-  createNote: {
-    authorize: async () => undefined,
-    execute: ({ kernel, params, deps }) => {
-      if (!kernel) throw new Error('createNote requires a kernel credential')
-      return createNote(kernel, deps.summarizer(), params)
-    },
+// ── Monitor ─────────────────────────────────────────────────────────
+
+const monitorCheckMethod = method(schema, 'Monitor', 'check', {
+  authorize: async () => undefined,
+  execute: async ({ kernel, self, deps }) => {
+    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')
+    // Pass the node to the picker — the prober is chosen FOR this monitor.
+    return monitorCheck(kernel, deps.prober({ class: node.class.raw, url }), self.path.raw, url)
   },
 })
 
-const referenceMethod = method(schema, 'Note', 'reference', {
+const watchMethod = method(schema, 'Monitor', 'watch', {
   authorize: async () => undefined,
-  execute: ({ kernel, self, params }) => {
-    if (!kernel) throw new Error('reference requires a kernel credential')
-    return reference(kernel, self.path.raw, params)
+  execute: ({ kernel, params }) => {
+    return watch(kernel, 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())
+  },
+})
+
+// ── StatusPage ──────────────────────────────────────────────────────
+
+const pageCheckMethod = method(schema, 'StatusPage', 'check', {
+  authorize: async () => undefined,
+  execute: ({ kernel, self }) => {
+    return pageCheck(kernel, self.path.raw)
+  },
+})
+
+const createMethod = method(schema, 'StatusPage', 'create', {
+  authorize: async () => undefined,
+  execute: ({ kernel, params }) => {
+    return create(kernel, params)
   },
 })
 
-const NoteMethods = classMethods(schema, 'Note', { reference: referenceMethod, seed: seedMethod })
+const addMethod = method(schema, 'StatusPage', 'add', {
+  authorize: async () => undefined,
+  execute: ({ kernel, self, params }) => {
+    return add(kernel, self.path.raw, params)
+  },
+})
 
 export const methods: SchemaMethodsImpl<typeof schema, Deps> = {
-  interface: { NoteOps: NoteOpsMethods },
-  class: { Note: NoteMethods },
+  class: {
+    Monitor: classMethods(schema, 'Monitor', {
+      check: monitorCheckMethod,
+      watch: watchMethod,
+      seed: seedMethod,
+    }),
+    StatusPage: classMethods(schema, 'StatusPage', {
+      check: pageCheckMethod,
+      create: createMethod,
+      add: addMethod,
+    }),
+  },
 }

package/template/runtime/monitor/check.ts

@@ -0,0 +1,29 @@
+import type { Prober } from '../../integrations/prober/port'
+import type { CallableKernel } from '../shared'
+
+/**
+ * `Monitor.check` (instance) — implements `Checkable.check` for a single endpoint:
+ * probe the target via the resolved `Prober` port, classify (pure, `core/monitor`),
+ * record status/latency on the node, and return the verdict. `url` + `prober` are
+ * resolved by the wiring (`runtime/index.ts`) from `self.node()`.
+ */
+import { classify, MONITOR_KEYS } from '../../core/monitor'
+
+export async function check(
+  kernel: CallableKernel,
+  prober: Prober,
+  selfPathRaw: string,
+  url: string,
+): Promise<{ status: string }> {
+  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 }
+}

package/template/runtime/monitor/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Monitor operations — one file per method, assembled here for the composition
+ * root (`runtime/index.ts`). Each is transport-agnostic logic over a
+ * `CallableKernel` (+ the `Prober` port where it probes), delegating pure
+ * decisions to `core/monitor` — so all are unit-testable with fakes.
+ */
+export { check } from './check'
+export { seed } from './seed'
+export { watch } from './watch'

package/template/runtime/monitor/seed.ts

@@ -0,0 +1,95 @@
+import type { Prober } from '../../integrations/prober/port'
+
+/**
+ * `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 comes up demonstrable: a `/monitors` folder + starter Monitors (each
+ * probed once), and a `/status-pages` folder + one StatusPage that `watches` them
+ * (its initial status rolled up from the probes). Idempotent: node creates swallow
+ * `PATH_CONFLICT` (fixed paths) and re-linking a `watches` edge is a graph no-op.
+ * It grants nothing — the installing owner reaches these nodes via root-propagated
+ * perms; grant explicitly here for non-owner access.
+ */
+import {
+  classify,
+  FOLDER_CLASS,
+  MONITOR_CLASS,
+  MONITOR_KEYS,
+  MONITORS_PARENT,
+  NAME_KEY,
+  NODE_CREATE,
+  rollup,
+  STARTER_PAGE,
+  STARTERS,
+  STATUS_PAGE_CLASS,
+  STATUS_PAGES_PARENT,
+  PAGE_KEYS,
+  WATCHES_EDGE,
+  WATCHES_KEYS,
+} from '../../core/monitor'
+import { type CallableKernel, isPathConflict } from '../shared'
+
+/** Create a node, swallowing a re-seed's `PATH_CONFLICT`. Returns true if newly created. */
+async function ensure(kernel: CallableKernel, params: unknown): Promise<boolean> {
+  try {
+    await kernel.call(NODE_CREATE, params)
+    return true
+  } catch (e) {
+    if (!isPathConflict(e)) throw e
+    return false
+  }
+}
+
+export async function seed(kernel: CallableKernel, prober: Prober): Promise<{ seeded: number }> {
+  await ensure(kernel, {
+    class: FOLDER_CLASS,
+    path: MONITORS_PARENT,
+    props: { [NAME_KEY]: 'monitors' },
+  })
+
+  // Probe + create each starter Monitor; collect the verdict for the page roll-up.
+  const members: { status: string; critical: boolean }[] = []
+  let seeded = 0
+  for (const s of STARTERS) {
+    const result = await prober.probe(s.url)
+    const status = classify(result.statusCode)
+    members.push({ status, critical: s.critical })
+    const created = await ensure(kernel, {
+      class: MONITOR_CLASS,
+      path: `${MONITORS_PARENT}/${s.slug}`,
+      props: {
+        [NAME_KEY]: s.name,
+        [MONITOR_KEYS.url]: s.url,
+        [MONITOR_KEYS.status]: status,
+        [MONITOR_KEYS.statusCode]: result.statusCode,
+        [MONITOR_KEYS.latencyMs]: result.latencyMs,
+        [MONITOR_KEYS.lastCheckedAt]: new Date().toISOString(),
+      },
+    })
+    if (created) seeded++
+  }
+
+  // A StatusPage watching every starter, its status rolled up from the probes.
+  await ensure(kernel, {
+    class: FOLDER_CLASS,
+    path: STATUS_PAGES_PARENT,
+    props: { [NAME_KEY]: 'status-pages' },
+  })
+  const pagePath = `${STATUS_PAGES_PARENT}/${STARTER_PAGE.slug}`
+  await ensure(kernel, {
+    class: STATUS_PAGE_CLASS,
+    path: pagePath,
+    props: { [NAME_KEY]: STARTER_PAGE.name, [PAGE_KEYS.status]: rollup(members) },
+  })
+  // Re-linking the same (page, monitor) `watches` edge is a graph no-op, so this
+  // needs no conflict guard.
+  for (const s of STARTERS) {
+    await kernel.call(`${pagePath}::link`, {
+      edgeClass: WATCHES_EDGE,
+      target: `${MONITORS_PARENT}/${s.slug}`,
+      props: { [WATCHES_KEYS.critical]: s.critical },
+    })
+  }
+
+  return { seeded }
+}

package/template/runtime/monitor/watch.ts

@@ -0,0 +1,31 @@
+/**
+ * `Monitor.watch` (static) — create a Monitor node under `/monitors`. The slug
+ * format is pure (`core/monitor`'s `uniqueSlug`); the entropy suffix (impure,
+ * clock/RNG) comes from `runtime/shared`, keeping core deterministic.
+ */
+import {
+  MONITOR_CLASS,
+  MONITOR_KEYS,
+  MONITORS_PARENT,
+  NAME_KEY,
+  NODE_CREATE,
+  uniqueSlug,
+} from '../../core/monitor'
+import { type CallableKernel, randomSuffix } from '../shared'
+
+export async function watch(
+  kernel: CallableKernel,
+  params: { url: string; name?: string },
+): Promise<{ id: string; path: string }> {
+  const path = `${MONITORS_PARENT}/${uniqueSlug(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/runtime/shared.ts

@@ -0,0 +1,21 @@
+/**
+ * Runtime-internal helpers shared across the context's operations. 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')
+}
+
+/** Short clock+RNG entropy to dodge same-ms / same-stem slug collisions (impure). */
+export function randomSuffix(): string {
+  return `${Date.now().toString(36).slice(-4)}${Math.random().toString(36).slice(2, 6)}`
+}

package/template/runtime/status-page/add.ts

@@ -0,0 +1,21 @@
+import type { CallableKernel } from '../shared'
+
+/**
+ * `StatusPage.add` (instance) — watch a Monitor: create a `watches` edge from
+ * this page to `monitor`, tagged `critical` (default false). `monitor` is any
+ * node address (a tree path or `@<id>`).
+ */
+import { WATCHES_EDGE, WATCHES_KEYS } from '../../core/monitor'
+
+export async function add(
+  kernel: CallableKernel,
+  selfPathRaw: string,
+  params: { monitor: string; critical?: boolean },
+): Promise<{ watched: string }> {
+  await kernel.call(`${selfPathRaw}::link`, {
+    edgeClass: WATCHES_EDGE,
+    target: params.monitor,
+    props: { [WATCHES_KEYS.critical]: params.critical ?? false },
+  })
+  return { watched: params.monitor }
+}

package/template/runtime/status-page/check.ts

@@ -0,0 +1,50 @@
+import type { CallableKernel } from '../shared'
+
+/**
+ * `StatusPage.check` (instance) — implements `Checkable.check` for a page: walk
+ * the `watches` edges, re-check each monitor (a cross-node `@<id>::check` call),
+ * roll the verdicts up (pure, `core/monitor`), record the page status, return it.
+ *
+ * `getLinks` returns raw `Edge`s whose endpoint/prop accessors aren't typed yet
+ * (an SDK gap) — `parseWatches` is the small cast that bridges it.
+ */
+import { PAGE_KEYS, rollup, WATCHES_EDGE, WATCHES_KEYS } from '../../core/monitor'
+
+/** A raw `watches` edge as `getLinks` returns it (endpoints are string-or-`{raw}`). */
+type RawEdge = {
+  class?: string | { raw: string }
+  target?: string | { raw: string }
+  props?: Record<string, unknown>
+}
+
+function rawOf(p: RawEdge['target']): string | undefined {
+  if (typeof p === 'string') return p
+  return typeof p?.raw === 'string' ? p.raw : undefined
+}
+
+/** The monitors this page watches: each target ref + its `critical` flag. */
+function parseWatches(raw: unknown): { monitor: string; critical: boolean }[] {
+  const edges = (Array.isArray(raw) ? raw : []) as RawEdge[]
+  const out: { monitor: string; critical: boolean }[] = []
+  for (const e of edges) {
+    if (rawOf(e.class) !== WATCHES_EDGE) continue
+    const monitor = rawOf(e.target)
+    if (monitor) out.push({ monitor, critical: e.props?.[WATCHES_KEYS.critical] === true })
+  }
+  return out
+}
+
+export async function check(
+  kernel: CallableKernel,
+  selfPathRaw: string,
+): Promise<{ status: string }> {
+  const links = await kernel.call(`${selfPathRaw}::getLinks`, { direction: 'out' })
+  const members = []
+  for (const w of parseWatches(links)) {
+    const { status } = (await kernel.call(`${w.monitor}::check`, {})) as { status: string }
+    members.push({ status, critical: w.critical })
+  }
+  const status = rollup(members)
+  await kernel.call(`${selfPathRaw}::update`, { props: { [PAGE_KEYS.status]: status } })
+  return { status }
+}

package/template/runtime/status-page/create.ts

@@ -0,0 +1,24 @@
+/**
+ * `StatusPage.create` (static) — create a StatusPage node under `/status-pages`.
+ */
+import {
+  NAME_KEY,
+  NODE_CREATE,
+  STATUS_PAGE_CLASS,
+  STATUS_PAGES_PARENT,
+  uniqueSlug,
+} from '../../core/monitor'
+import { type CallableKernel, randomSuffix } from '../shared'
+
+export async function create(
+  kernel: CallableKernel,
+  params: { name: string },
+): Promise<{ id: string; path: string }> {
+  const path = `${STATUS_PAGES_PARENT}/${uniqueSlug(params.name, randomSuffix())}`
+  const created = (await kernel.call(NODE_CREATE, {
+    class: STATUS_PAGE_CLASS,
+    path,
+    props: { [NAME_KEY]: params.name },
+  })) as { id: string }
+  return { id: created.id, path }
+}

package/template/runtime/status-page/index.ts

@@ -0,0 +1,8 @@
+/**
+ * StatusPage operations — one file per method, assembled here for the
+ * composition root (`runtime/index.ts`). Transport-agnostic logic over a
+ * `CallableKernel`, delegating the roll-up decision to `core/monitor`.
+ */
+export { add } from './add'
+export { check } from './check'
+export { create } from './create'

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 { Checkable, Monitor, StatusPage, watches } from './monitor'
 
 export const schema = defineSchema('astrale-domain.example.dev', {
-  interfaces: { NoteOps },
-  classes: { Note, references },
+  interfaces: { Checkable },
+  classes: { Monitor, StatusPage, watches },
   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/monitor/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,94 @@
+/**
+ * Monitoring context — the domain's single bounded slice: a `Checkable` contract
+ * implemented by two classes, plus the edge that binds them.
+ *
+ *   - Interface `Checkable`   one `abstract` method, `check()`. Abstract → each
+ *                             implementing class brings its OWN body, and the
+ *                             kernel dispatches by the node's class.
+ *   - Class `Monitor`         a single HTTP check. `check()` probes `url`;
+ *                             `watch` creates one; `seed` lays down the demo set.
+ *   - Class `StatusPage`      a roll-up. `check()` re-checks the monitors it
+ *                             `watches` and aggregates; `create` makes a page;
+ *                             `add` watches a monitor.
+ *   - Edge `watches`          StatusPage → Monitor, with a `critical` flag.
+ */
+import { edgeClass, 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 the static factories return (a full Node
+ *  value does not round-trip over the worker wire). */
+export const NodeRef = z.object({ id: z.string(), path: z.string() })
+
+/** What `check()` reports — the subject's current health verdict. */
+export const CheckResult = z.object({ status: z.string() })
+
+export const Checkable = nodeInterface({
+  methods: {
+    // `abstract` → no shared body; every implementer supplies its own `check`,
+    // wired per-class in `runtime/`. `@<node>::check` dispatches by the node's class.
+    check: fn({ inheritance: 'abstract', returns: CheckResult }),
+  },
+})
+
+export const Monitor = nodeClass({
+  implements: [Checkable],
+  props: {
+    /** The target URL this monitor probes. */
+    url: z.string(),
+    // Live status, written by `check`. PLAIN STRING, not `z.enum()`: `::update`
+    // silently drops `z.enum()` props. Values: 'up' | 'down' | 'unknown'.
+    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: {
+    // Implements `Checkable.check` for a single endpoint (probe `url`). Redeclared
+    // here — a concrete class must declare each abstract method it implements, so
+    // the compiler materializes Monitor's OWN `check` node for per-class dispatch.
+    // The body lives in `runtime/monitor/check.ts`.
+    check: fn({ returns: CheckResult }),
+    /** Create a Monitor under `/monitors`. */
+    watch: fn({
+      static: true,
+      params: { url: z.string(), name: z.string().optional() },
+      returns: NodeRef,
+    }),
+    // Post-install bootstrap (wired as `postInstall` in domain.ts). Static: the
+    // kernel calls it ONCE after install, as __SYSTEM__. Must stay idempotent.
+    seed: fn({ static: true, returns: z.object({ seeded: z.number().int() }) }),
+  },
+})
+
+export const StatusPage = nodeClass({
+  implements: [Checkable],
+  props: {
+    /** Rolled-up status, written by `check`. 'up' | 'degraded' | 'down' | 'unknown'. */
+    status: z.string().optional(),
+  },
+  methods: {
+    // Implements `Checkable.check` for a page (roll up the watched monitors).
+    // Redeclared so StatusPage materializes its OWN `check` node. Body in
+    // `runtime/status-page/check.ts`.
+    check: fn({ returns: CheckResult }),
+    /** Create a StatusPage under `/status-pages`. */
+    create: fn({ static: true, params: { name: z.string() }, returns: NodeRef }),
+    /** Watch a monitor (a `watches` edge); `critical` decides the roll-up weight. */
+    add: fn({
+      params: { monitor: z.string(), critical: z.boolean().optional() },
+      returns: z.object({ watched: z.string() }),
+    }),
+  },
+})
+
+export const watches = edgeClass(
+  { as: 'page', types: [StatusPage] },
+  { as: 'monitor', types: [Monitor] },
+  // `critical` drives the roll-up: a critical monitor down ⇒ page `down`; a
+  // non-critical one down ⇒ `degraded`.
+  { props: { critical: z.boolean() } },
+)

package/template/views/index.ts

@@ -3,8 +3,14 @@
  * 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-status-page` is
+ * the `client/` SPA (mounted at `/ui/status-page`, offered for any StatusPage).
  */
-import { note } from './note'
+import { statusPage } from './status-page'
 import { welcome } from './welcome'
 
-export const views = { welcome, 'ui-note': note }
+export const views = {
+  welcome,
+  'ui-status-page': statusPage,
+}

package/template/views/status-page.ts

@@ -0,0 +1,16 @@
+/**
+ * `ui-status-page` — the domain's SPA view, mounted at `/ui/status-page` and
+ * served from the `client/` bundle. `viewFor: selfOf(StatusPage)` attaches a
+ * `view_for` edge to the `StatusPage` class meta-node, so the GUI offers this
+ * view for any StatusPage instance.
+ */
+import { selfOf } from '@astrale-os/kernel-dsl'
+import { defineView } from '@astrale-os/sdk'
+
+import { StatusPage } from '../schema/monitor'
+
+export const statusPage = defineView({
+  auth: 'public',
+  mount: '/ui/status-page',
+  viewFor: selfOf(StatusPage),
+})