@astrale-os/adapter-cloudflare 0.1.8 → 0.1.9

package/src/params.ts

@@ -55,37 +55,38 @@ export interface CloudflareParams {
    * worker-entry codegen and aren't supported through this field yet.
    */
   wrangler?: Record<string, unknown>
-}
-
-/** Params for the Astrale-managed adapter (`astrale(envs)`). */
-export interface AstraleParams {
   /**
-   * Target instance slug the domain installs onto (e.g. `'bryan-e2e5'`).
-   * Required for `deploy` (managed publish + install); ignored by `watch`
-   * (local dev) — so dev-only envs may omit it.
-   */
-  instance?: string
-  /** Catalog package name. Default: the origin's first DNS label. */
-  name?: string
-  /** Admin kernel URL the publish calls target. Default the platform admin. */
-  adminUrl?: string
-  /** Routing region of the `.svc` service URL. Default `'eu'`. */
-  region?: string
-  /** CLI identity (`--as`) for the publish calls. Default: the CLI's active identity. */
-  identity?: string
-  /** Gitignored secrets file. `watch`: injected into local wrangler dev. `deploy`: shipped on the install call and applied to the managed service env (encrypted at rest platform-side; platform keys win precedence). */
-  secrets?: string
-  /** Local dev port for `wrangler dev`. Default 8787. */
-  port?: number
-  /**
-   * Public URL the dev server is reached through (tunnel / sandbox preview /
-   * reverse proxy), e.g. `'https://my-box.preview.dev'`. Sets BOTH effects an
-   * off-localhost dev needs: wrangler binds 0.0.0.0 (reachable from outside)
-   * and `WORKER_URL` is pinned to this URL so the worker's per-request-Host
-   * identity (`iss`) doesn't drift to the proxy's internal hostname.
-   * Usually injected by `pnpm dev --host <url>` rather than written here.
+   * Route subrequests to platform INSTANCE hostnames through a service binding
+   * instead of the public edge. A Cloudflare Worker can't fetch a same-zone
+   * hostname served by another Worker — Cloudflare 522s it — so without this the
+   * worker can't fetch an instance kernel's JWKS to verify an inbound credential
+   * from that instance, and every cross-instance call (install hooks, the GUI's
+   * delegated calls, authed views) fails with `2002 Credential verification
+   * failed`. Point it at a router Worker that reaches those hosts internally
+   * (Astrale: `admin-router`).
+   *
+   * Wires BOTH halves the SDK needs: the `<binding>` service binding in the
+   * generated wrangler config, and a `routeSubrequest` predicate in the worker
+   * entry that diverts matching hosts through it.
+   *
+   * ON BY DEFAULT (targets `admin-router`) so every adapter-deployed worker can
+   * verify cross-instance credentials out of the box. Pass `false` to disable
+   * (a domain that never talks to another instance, or an account without a
+   * router), or an object to override the target / binding name / host match.
+   *
+   *   router: false                      // opt out
+   *   router: { service: 'my-router' }   // override target
    */
-  host?: string
-  /** Extra plain vars for local `watch`. */
-  vars?: Record<string, string>
+  router?:
+    | false
+    | {
+        /** Router Worker the binding targets. Default `'admin-router'`. */
+        service?: string
+        /** Service-binding name the worker reads. Default `'ROUTER'`. */
+        binding?: string
+        /** Host suffix that marks an instance host. Default `'.astrale.ai'`. */
+        hostSuffix?: string
+        /** Min dot-separated label count for an instance host. Default `4` (`<slug>.<region>.astrale.ai`). */
+        minLabels?: number
+      }
 }

package/src/parse-output.ts

@@ -14,7 +14,7 @@ const WORKERS_DEV_RE = /(https:\/\/[^\s]+\.workers\.dev)/i
  * The fallback (when no explicit "Ready on" line) only accepts a localhost URL
  * on the EXPECTED port — wrangler may print unrelated localhost URLs (e.g. an
  * inspector/devtools endpoint on a different port) before readiness, and taking
- * one of those would point `astrale instance install <url>` at a dead endpoint.
+ * one of those would point `astrale domain install <url>` at a dead endpoint.
  */
 export function parseDevReadyUrl(text: string, port: number): string | undefined {
   const ready = READY_RE.exec(text)

package/template/.agents/skills/astrale-cli/SKILL.md

@@ -38,6 +38,7 @@ astrale logs <service>
 astrale status
 astrale browser
 astrale instance ...
+astrale domain ...
 astrale admin ...
 astrale identity ...
 astrale auth ...
@@ -50,7 +51,7 @@ Command groups:
 |---|---|
 | Kernel | `call`, `token`, `get`, `ls`, `describe`, `query`, `logs` |
 | Context | `status`, `whoami`, `use` |
-| Management | `admin`, `instance`, `identity`, `auth`, `idp`, `update` |
+| Management | `admin`, `instance`, `domain`, `identity`, `auth`, `idp`, `update` |
 | Agent | `browser` |
 
 Shared kernel options are merged onto kernel-touching commands at registration
@@ -148,7 +149,6 @@ astrale instance use my-app
 astrale instance active
 astrale instance bookmark staging --url https://kernel.example.com
 astrale instance forget staging
-astrale instance install https://domain.example.com
 ```
 
 Important distinctions:
@@ -164,23 +164,37 @@ Important distinctions:
 ## Domain Dev Workflow
 
 **The `astrale` CLI is connect-only — it does not build, run, or deploy
-domains.** There is no `astrale domain …` command group. Domain development
-lives in two separate tools:
+domains.** The `astrale domain` group manages the admin catalog and installs a
+running domain onto an instance (`list`, `publish`, `install`); it does NOT
+build or run domains. `astrale domain list` shows the published catalog (add
+`--check` to probe each URL's reachability, `--default-only` for the
+install-on-every-instance set, `-q` to pipe install URLs). Building, running,
+and deploying live in two separate tools:
 
 - **`create-astrale-domain`** scaffolds a new standalone domain project
   (`pnpm create astrale-domain <slug>`), writing an `astrale.config.ts`.
-- **`astrale-domain`** (the `@astrale-os/devkit` bin, behind the project's
+- **`astrale-domain`** (the `@astrale-os/sdk` bin, behind the project's
   `pnpm dev` / `pnpm prod` scripts) runs `dev | prod | deploy <env> | build`.
 
-Domains are **installed by URL**, never from a file: run or deploy the domain
-worker, then `astrale instance install <url> -i <slug>` — the kernel fetches a
-signed install bundle from the running worker. There is no committed
-`spec.json` and no `astrale domain install`; install lives under the
-`instance` group because it operates on an instance graph.
+Domains are **installed by URL or catalog origin**, never from a file (there is
+no committed `spec.json`). `astrale domain install` has two modes:
+
+- **default (via admin)** — `astrale domain install <origin|url> -i <slug>`
+  installs a PUBLISHED domain through the admin control plane
+  (`DomainEntry.install`), addressed by its catalog `origin` (the unique
+  registry key) or `url`. Run it bare to pick from the catalog interactively.
+  The target instance is the active one or `-i <slug>` and **must be
+  admin-managed** (otherwise it fails loudly and points you at `--direct`).
+- **`--direct`** — `astrale domain install <url> --direct` installs a url
+  straight onto the instance kernel (`Root.installDomain`), bypassing the
+  catalog. Works on ANY instance you can authenticate to (managed, bookmarked,
+  or local), using your own authority, and is the only mode that runs the
+  identity-override consent gate. Use it for dev/local instances and
+  freshly-deployed, not-yet-published workers.
 
 With the **managed (`astrale`) adapter**, `pnpm prod` publishes the bundle
 through the platform AND installs it on the configured instance in one step —
-no manual `instance install`. The service serves at
+no manual `domain install`. The service serves at
 `https://<name>-<hash>.svc.<region>.astrale.ai` (the CLI session is the auth).
 
 For authoring domains end-to-end (schema, handlers, external APIs, deploys),

package/template/.agents/skills/astrale-domain/SKILL.md

@@ -36,14 +36,21 @@ pnpm prod     # deploy + (astrale adapter) auto-install on your instance
 Project anatomy (the scaffold is the reference — read its comments):
 
 ```
-astrale.config.ts   # THE manifest: schema + postInstall + adapter (where it ships)
+domain.ts           # THE manifest — wires it ALL: defineDomain({ schema, methods,
+                    #   deps, views, functions, client }) + origin/postInstall.
+                    #   Modules are imported & passed EXPLICITLY (no folder magic);
+                    #   a renamed module is a compile error here, not a missing route.
+astrale.config.ts   # binds the domain to its deploy adapter (deploy(domain, …)) — node-only
 schema/             # classes/interfaces/edges — the contract (zod props, fn signatures)
-methods/            # handler logic (transport-agnostic fns) + thin wiring (index.ts)
-services/           # RECOMMENDED: ports + factories for external APIs (see §4)
+                    #   + compiled.ts (D = compileDomain) — the public compiled entry
+core/               # pure, transport-agnostic logic + keys.ts (compiled accessors)
+integrations/       # external-API ports + adapters + a lazy registry (see §4) — what deps is built from
+runtime/index.ts    # composition root: the methods map; each execute resolves deps → calls core logic
 functions/          # standalone remote functions (webhook-shaped endpoints)
 views/              # iframe-mountable UI declarations (defineView)
 client/             # the SPA served under /ui (vite)
-env.ts              # typed worker env — config + secrets arrive here, as ctx.deps
+deps.ts             # env → typed Deps container (the seam defineDomain({ deps }) mounts)
+env.ts              # typed worker env — config + secrets arrive here, mapped by deps.ts → ctx.deps
 ```
 
 Iteration loop: edit → `pnpm prod` → call it. Managed redeploys keep the same
@@ -97,9 +104,10 @@ Conventions and rules:
 
 ## 2 · Handlers
 
-Separate LOGIC from WIRING. Logic = plain async functions taking the kernel
-client + ports + params (testable with fakes). Wiring = `method()` /
-`classMethods()` / `interfaceMethods()` in `methods/index.ts`:
+Separate LOGIC from WIRING. Logic = plain async functions in `core/` taking the
+kernel client + ports + params (testable with fakes). Wiring = `method()` /
+`classMethods()` / `interfaceMethods()` in `runtime/index.ts` (the composition
+root — the only place request context + `deps` meet the `core/` logic):
 
 ```ts
 const kickoff = method(schema, 'Project', 'kickoff', {
@@ -113,9 +121,11 @@ const kickoff = method(schema, 'Project', 'kickoff', {
 
 Handler context: `kernel` (callback client bound to the composed credential —
 caller's delegated authority ∪ this function's own), `self` (instance methods),
-`params` (zod-validated), `deps` (your typed `Env`), `auth` (principal,
-verified claims). Construct external clients from `deps` per request — NEVER
-at module load (workers must be import-side-effect-free).
+`params` (zod-validated), `deps` (your typed `Deps` from `deps.ts`; raw `Env` if
+you omit the mapper), `auth` (principal, verified claims). Resolve ports from
+`deps` per request (`deps.summarizer()` — the registry builds + caches them per
+isolate) — NEVER construct external clients at module load (workers must be
+import-side-effect-free).
 
 ## 3 · Talking to the kernel (and other domains)
 
@@ -155,16 +165,20 @@ Almost every real domain wraps an external API (payment, calendar, LLM
 gateway, cloud provider). The shape (see admin/domain for the full-scale
 example — Scaleway/WorkOS/KV):
 
-1. **Port** — a narrow interface declaring only what the logic needs
-   (`WeatherClient { forecast(city) }`). Logic depends on the port, never on
-   fetch/SDKs/env.
-2. **Factory** — `createXClient(env)` in `services/`: reads config + secrets
-   from `env`, validates LOUDLY (`if (!env.X_API_KEY) throw`), sets base URLs
-   (overridable so tests point at a stub), timeouts (`AbortSignal.timeout`),
-   and maps upstream failures to meaningful errors with the upstream detail in
-   `cause` (the kernel threads cause chains to callers).
-3. **Wiring** — the `execute` hook builds the client from `deps` per request
-   and passes it to the logic.
+1. **Port** — a narrow interface in `integrations/<feature>/port.ts` declaring
+   only what the logic needs (`WeatherClient { forecast(city) }`, the scaffold's
+   `Summarizer { summarize(body) }`). `core/` logic depends on the port, never
+   on fetch/SDKs/env.
+2. **Adapter(s) + registry** — `createXClient(config)` in
+   `integrations/<feature>/` (one per backend), plus a `registry.ts` that reads
+   config + secrets from `env`, validates LOUDLY (`if (!env.X_API_KEY) throw`),
+   sets base URLs (overridable so tests point at a stub), timeouts
+   (`AbortSignal.timeout`), and maps upstream failures to errors with the
+   upstream detail in `cause`. The registry builds the chosen adapter LAZILY +
+   caches it per isolate (a worker never validates an unused backend's env).
+3. **Wiring** — `deps.ts` mounts the registry (`defineDomain({ deps })`); the
+   `execute` hook resolves the PORT from `deps` (`deps.summarizer()`) per
+   request and passes it to the `core/` logic.
 
 Secrets & config:
 - Declare every var as a typed field on `Env` in `env.ts`. Secrets ship via
@@ -202,8 +216,10 @@ Anti-patterns (all observed in production code — don't):
 ## 5 · Views & standalone functions (webhooks)
 
 - `defineView({ auth, mount: '/ui/contact', viewFor: selfOf(Contact) })` in
-  `views/` + register in `views/index.ts` — the MAP KEY is the view's node
-  slug (`'ui-contact'` → `/<origin>/core/views/ui-contact`). Installs a View
+  `views/`, collected into the `views` map in `views/index.ts`, which
+  `astrale.config.ts` imports and passes to `defineDomain({ views })`. The MAP
+  KEY is the view's node slug (`'ui-contact'` → `/<origin>/core/views/ui-contact`).
+  Installs a View
   node whose binding URL = `<serving url><mount>` (managed:
   `https://<slug>.svc.<region>.astrale.ai/ui/contact`). The client/ SPA
   serves `/ui/*` — BOTH adapters ship it (cloudflare via Workers Assets;
@@ -276,12 +292,13 @@ capture when the sender's shape is fixed (see distribution's proxy functions).
 
 ## 7 · Deploy & install
 
-Adapter choice in `astrale.config.ts`:
-- `cloudflare({...})` — your CF account; `dev` (wrangler dev), `prod` (route or
-  workers.dev); ships secrets + SPA assets; extra bindings via a deep-merged
-  `wrangler` block.
-- `astrale({ dev: {...}, prod: { instance: '<slug>' } })` — managed (the
-  scaffold's DEFAULT): publishes
+Adapter choice in `astrale.config.ts` (each adapter is its OWN package — swap
+BOTH the import and the call):
+- `cloudflare({...})` from `@astrale-os/adapter-cloudflare` — your CF account;
+  `dev` (wrangler dev), `prod` (route or workers.dev); ships secrets + SPA
+  assets; extra bindings via a deep-merged `wrangler` block.
+- `astrale({ dev: {...}, prod: { instance: '<slug>' } })` from
+  `@astrale-os/adapter-astrale` — managed (the scaffold's DEFAULT): publishes
   the bundle THROUGH the platform and installs it as a host-local service next
   to your instance (`https://<name>-<hash>.svc.<region>.astrale.ai`). No CF
   account; auth = your `astrale auth login` session. Ships the client SPA
@@ -303,7 +320,7 @@ service URL stable).
 (`/:origin:class.X:seed`; tree paths are rejected) and MUST be idempotent
 (catch path-conflicts). Seed folders, defaults, and demo data here.
 
-Manual install of any served domain: `astrale instance install <url>`.
+Manual install of any served domain: `astrale domain install <url> --direct`.
 
 The managed catalog surface (what `pnpm prod` shells into) is callable
 directly — useful for recovery and inspection:

package/template/.env.example

@@ -4,3 +4,11 @@
 # prod. These files are gitignored — copy this to `.env.dev` and fill in.
 #
 # EXAMPLE_API_KEY=sk-...
+#
+# ── Summarizer (the example external-API integration) ──────────────────────
+# The scaffold summarizes notes with a no-network heuristic by default. To use a
+# real OpenAI-compatible model instead, set NOTE_SUMMARIZER=http and provide:
+# NOTE_SUMMARIZER=http
+# SUMMARIZER_API_KEY=sk-...
+# SUMMARIZER_BASE_URL=https://api.openai.com/v1
+# SUMMARIZER_MODEL=gpt-4o-mini

package/template/README.md

@@ -19,20 +19,35 @@ calls), use the `astrale-cli` skill.
 ```bash
 pnpm install
 pnpm dev                          # wrangler dev → prints a local URL
-astrale instance install <url>    # mount it on an instance (CLI)
+astrale domain install <url> --direct    # mount it on an instance (CLI)
 pnpm prod                         # deploy prod → prints a URL
 ```
 
-## What you write (★)
+## What you write
 
 ```
-schema/      ★ classes + interfaces (the data model)
-methods/     ★ the execute() handlers
-views/       ★ iframe-mountable UIs
-functions/   ★ standalone Functions (e.g. the post-install seed)
-astrale.config.ts   identity (origin) · requires · postInstall · adapter
+schema/        classes + interfaces (the data model) + compiled accessors
+core/          pure, transport-agnostic logic + keys.ts (never hand-write keys)
+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)
+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 everything is declared: it imports the modules
+above and passes them to `defineDomain({ schema, methods, deps, views,
+functions, client, … })` 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`, `client`) when the domain has none.
+`astrale.config.ts` then binds that domain to a deploy adapter with
+`deploy(domain, cloudflare({ … }))` — keeping the node-only adapter (wrangler,
+filesystem) out of the worker bundle.
+
 Everything else — the Worker entry, the wrangler config, the signing identity —
 is generated under `.astrale/` (gitignored) by the adapter. You never edit it.
 
@@ -72,8 +87,8 @@ adapter-owned keys `name`, `main`, `assets`, `routes` are rejected (use
 
 ## The loop
 
-- **Edit a handler** (`methods/`) → hot-reloads at the same URL. Nothing to reinstall.
-- **Edit the schema** (`schema/`) → rebuilds the graph; reinstall with `astrale instance install <url>`.
+- **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 `Note.seed` method) runs once after install, as
   the system identity, so the domain can seed itself and set its own grants. It
   must be a class-hosted static addressed by a typed colon-path

package/template/astrale.config.ts

@@ -1,43 +1,37 @@
 /**
- * astrale.config.ts — the single source of truth for this domain's identity and
- * deployment. `origin` defaults to `schema.domain`; `postInstall` points at the
- * static `Note.seed` method the kernel runs after install (a typed colon-path —
- * the kernel refuses tree paths here, since they can't prove their origin);
- * `adapter` chooses the target.
+ * astrale.config.ts — binds the worker-safe domain (`domain.ts`) to its deploy
+ * adapter for the `astrale-domain` CLI. This is a NODE-only module: it imports
+ * the adapter (wrangler + filesystem). The generated worker never imports this
+ * file — it imports `domain.ts` directly — so the adapter stays out of the bundle.
+ *
+ * This variant deploys to YOUR OWN Cloudflare account (the `cloudflare` adapter).
  *
  *   pnpm dev                       # wrangler dev → prints a local URL
- *   astrale instance install <url> # mount the dev URL on an instance
- *   pnpm prod                      # managed deploy → prints a URL + installs
+ *   astrale domain install <url> --direct # mount the dev URL on an instance
+ *   pnpm prod                      # deploy to your Cloudflare account
  */
-import { astrale } from '@astrale-os/adapter-cloudflare'
-import { defineDomain } from '@astrale-os/devkit'
-// Have your own Cloudflare account and prefer deploying there directly? Swap
-// the adapter — same bundle, shipped with wrangler under YOUR account (then
-// mount it yourself: `astrale instance install <url>`). Extra bindings (KV,
-// R2, D1, queues, …) ride a `wrangler` block on any env (deep-merged):
+import { cloudflare } from '@astrale-os/adapter-cloudflare'
+import { deploy } from '@astrale-os/sdk'
+// No Cloudflare account? Swap the adapter for the Astrale-managed one — it
+// publishes the same bundle THROUGH the platform and installs it on your
+// instance (auth = your `astrale auth login` session):
 //
-//   import { cloudflare } from '@astrale-os/adapter-cloudflare'
-//   adapter: cloudflare({
-//     dev: { secrets: '.env.dev' },              // local wrangler dev, unchanged
-//     prod: { route: 'astrale-domain.example.dev', secrets: '.env.prod' },
-//   }),
+//   import { astrale } from '@astrale-os/adapter-astrale'
+//   export default deploy(domain, astrale({
+//     dev: { secrets: '.env.dev' },               // local wrangler dev, unchanged
+//     prod: { instance: '<your-instance-slug>' }, // pnpm prod → managed deploy
+//   }))
 
-import { schema } from './schema'
+import { domain } from './domain'
 
-export default defineDomain({
-  schema,
-  // origin defaults to `schema.domain`. Set it to another domain's origin to
-  // deliberately alias that identity (you'll get a DANGER prompt at install).
-  postInstall: `/:${schema.domain}:class.Note:seed`,
-  adapter: astrale({
+export default deploy(
+  domain,
+  cloudflare({
     // Local dev: `wrangler dev`. No route → URL is http://localhost:8787.
     dev: { secrets: '.env.dev' },
-    // Managed deploy: `pnpm prod` publishes the bundle through the platform and
-    // installs the domain on this instance — no Cloudflare account needed
-    // (auth = your `astrale auth login` session). The slug comes from
-    // `astrale instance create <slug>` / `astrale instance status`.
-    prod: { instance: 'my-instance-slug' },
-    // Author secrets ship via `secrets: '.env.prod'` on any env (encrypted at
-    // rest platform-side, re-applied on redeploys; omit = keep, `{}` = clear).
+    // Custom-domain prod. Drop `route` to ship to *.workers.dev instead.
+    prod: { route: 'astrale-domain.example.dev', secrets: '.env.prod' },
+    // Author secrets ship via `secrets: '.env.prod'` on any env. Extra bindings
+    // (KV, R2, D1, queues, …) ride a `wrangler` block on any env (deep-merged).
   }),
-})
+)

package/template/client/README.md

@@ -3,7 +3,7 @@
 A small React + Vite SPA that renders the domain's `ui-note` View. It is loaded
 inside an iframe mounted by the Astrale shell, runs the shell handshake to learn
 its target node id and a delegation token, fetches that Note from the kernel,
-and renders its title/body. Built into `../dist-client/` and served by the
+and renders its title/body. Built into `../.dist/` and served by the
 generated worker (`.astrale/`) under `/ui/*` via its `ASSETS` binding.
 
 ## Self-contained on purpose
@@ -38,7 +38,7 @@ __tests__/
 ## Dev loops
 
 ```bash
-pnpm dev       # vite build --watch → ../dist-client/ (worker auto-reloads, no HMR)
+pnpm dev       # vite build --watch → ../.dist/ (worker auto-reloads, no HMR)
 pnpm dev:hmr   # vite dev on http://127.0.0.1:5173/ (React fast-refresh)
 pnpm test      # vitest run (happy-dom; fake parent + fake kernel, JSON-only)
 ```

package/template/client/tsconfig.json

@@ -21,5 +21,5 @@
     "vite.config.ts",
     "vitest.config.ts"
   ],
-  "exclude": ["node_modules", "../dist-client"]
+  "exclude": ["node_modules", "../.dist"]
 }

package/template/client/vite.config.ts

@@ -2,10 +2,10 @@ import viteReact from '@vitejs/plugin-react'
 import { defineConfig } from 'vite'
 
 /**
- * Client SPA for the domain's `ui-note` View. Built into `../dist-client/`,
+ * Client SPA for the domain's `ui-note` View. Built into `../.dist/`,
  * served by the generated worker via its `ASSETS` binding (`.astrale/`).
  *
- * `base: '/ui/'` + `outDir: '../dist-client'`: Vite emits asset refs as
+ * `base: '/ui/'` + `outDir: '../.dist'`: Vite emits asset refs as
  * `/ui/assets/<hash>.js`; the worker strips the `/ui` prefix before delegating
  * to `ASSETS`, so files resolve from the directory root. `index.html` is the
  * SPA fallback for `/ui/<anything>`.
@@ -26,7 +26,7 @@ export default defineConfig({
   base: '/ui/',
   plugins: [viteReact()],
   build: {
-    outDir: '../dist-client',
+    outDir: '../.dist',
     emptyOutDir: true,
     sourcemap: false,
   },

package/template/client/vitest.config.ts

@@ -5,7 +5,7 @@ import { defineConfig } from 'vitest/config'
  * Vitest config for the self-contained client. A DOM env (`happy-dom`) backs
  * the React render + `window.postMessage`/`MessageChannel` used by the fake
  * shell-parent harness. Kept separate from `vite.config.ts` (which sets the
- * `/ui/` base + `../dist-client` build) so tests don't inherit the SPA build
+ * `/ui/` base + `../.dist` build) so tests don't inherit the SPA build
  * options.
  */
 export default defineConfig({

package/template/core/keys.ts

@@ -0,0 +1,28 @@
+/**
+ * Compiled-schema accessors — the ONE place class paths, method paths, and
+ * qualified prop keys come from. Pure (schema-derived); never hand-write key
+ * strings. `D` (the compiled domain) is the public `schema/compiled` entry,
+ * re-exported here so `core/` and `runtime/` read it — plus the named keys —
+ * from one place.
+ */
+import { K } from '@astrale-os/kernel-core'
+
+import { D } from '../schema/compiled'
+
+export { D, K }
+
+/** Kernel ops/classes the logic addresses. */
+export const NODE_CREATE = K.Node.createNode.path.method.raw
+export const FOLDER_CLASS = K.Folder.path.class.raw
+export const NAME_KEY = K.Named.name.key
+
+/** Domain class paths. */
+export const NOTE_CLASS = D.Note.path.class.raw
+export const REFERENCES_EDGE = D.references.path.class.raw
+
+/** Qualified storage keys for Note node props. */
+export const NOTE_KEYS = {
+  title: D.Note.title.key,
+  body: D.Note.body.key,
+  summary: D.Note.summary.key,
+} as const

package/template/{methods → core}/note.ts

@@ -1,26 +1,27 @@
 /**
- * Note context — method LOGIC, written once, transport-agnostic.
+ * Note context — method LOGIC, written once, transport-agnostic and testable.
  *
  * Each handler touches the kernel ONLY through `kernel.call(...)` (the universal
- * syscalls) plus its `params` and, for instance methods, the source node's
- * `path.raw`. Address callables/edges with layout-independent forms — a
- * `ClassPath` for the edge class, the `<id>::link` instance form, and an
- * `@<id>` id-form target. Reserve an absolute path string for a node *location*.
+ * syscalls) plus its `params`, the resolved `Summarizer` PORT, and — for
+ * instance methods — the source node's `path.raw`. It never names `fetch`, the
+ * worker `env`, or a concrete provider: the port arrives ready-to-use from
+ * `runtime/` (which built it from `deps`). Address callables/edges with
+ * layout-independent forms — a `ClassPath` for the edge class, the `<id>::link`
+ * instance form, and an `@<id>` id-form target.
  */
-import { K } from '@astrale-os/kernel-core'
-
-import { D } from '../schema/compiled'
+import type { Summarizer } from '../integrations/summary/port'
+import {
+  FOLDER_CLASS,
+  NAME_KEY,
+  NODE_CREATE,
+  NOTE_CLASS,
+  NOTE_KEYS,
+  REFERENCES_EDGE,
+} from './keys'
 
 /** The minimal kernel surface the worker runtime exposes to a handler. */
 export type CallableKernel = { call(path: string, params: unknown): Promise<unknown> }
 
-const NODE_CREATE = K.Node.createNode.path.method.raw
-const NAME_KEY = K.Named.name.key
-const NOTE_CLASS = D.Note.path.class.raw
-const REFERENCES_EDGE = D.references.path.class.raw
-const TITLE_KEY = D.Note.title.key
-const BODY_KEY = D.Note.body.key
-
 /** Notes live under a `/notes` folder at the graph root (created by `seed`). */
 const NOTES_PARENT = '/notes'
 
@@ -37,16 +38,26 @@ function slugify(text: string): string {
   return `${stem}-${Date.now().toString(36).slice(-4)}${Math.random().toString(36).slice(2, 6)}`
 }
 
-/** `NoteOps.createNote` (static) — create a Note under `/notes`. */
+/**
+ * `NoteOps.createNote` (static) — create a Note under `/notes`, stamping a
+ * one-line `summary` from the resolved summarizer port (the external-API seam).
+ */
 export async function createNote(
   kernel: CallableKernel,
+  summarizer: Summarizer,
   params: { title: string; body: string },
 ): Promise<{ id: string; path: string }> {
+  const summary = await summarizer.summarize(params.body)
   const path = `${NOTES_PARENT}/${slugify(params.title)}`
   const created = (await kernel.call(NODE_CREATE, {
     class: NOTE_CLASS,
     path,
-    props: { [NAME_KEY]: params.title, [TITLE_KEY]: params.title, [BODY_KEY]: params.body },
+    props: {
+      [NAME_KEY]: params.title,
+      [NOTE_KEYS.title]: params.title,
+      [NOTE_KEYS.body]: params.body,
+      [NOTE_KEYS.summary]: summary,
+    },
   })) as { id: string }
   return { id: created.id, path }
 }
@@ -64,8 +75,6 @@ export async function reference(
   return { linked: params.target }
 }
 
-const FOLDER_CLASS = K.Folder.path.class.raw
-
 const STARTERS: ReadonlyArray<{ slug: string; title: string; body: string }> = [
   {
     slug: 'welcome',
@@ -81,12 +90,15 @@ function isPathConflict(e: unknown): boolean {
 
 /**
  * `Note.seed` (static) — the domain's post-install bootstrap. The kernel calls
- * it ONCE after install, as __SYSTEM__ (see `postInstall` in
- * `astrale.config.ts`), so the domain can lay down its initial state and
- * grants: the `/notes` folder, a couple of starter Notes, and a `references`
- * edge between them. Idempotent: a re-run swallows `PATH_CONFLICT` per node.
+ * it ONCE after install, as __SYSTEM__ (see `postInstall` in `domain.ts`), so
+ * the domain can lay down its initial state: the `/notes` folder, a couple of
+ * starter Notes (each summarized through the port), and a `references` edge
+ * between them. Idempotent: a re-run swallows `PATH_CONFLICT` per node.
  */
-export async function seed(kernel: CallableKernel): Promise<{ seeded: number }> {
+export async function seed(
+  kernel: CallableKernel,
+  summarizer: Summarizer,
+): Promise<{ seeded: number }> {
   // 1. The `/notes` folder at the graph root.
   try {
     await kernel.call(NODE_CREATE, {
@@ -106,7 +118,12 @@ export async function seed(kernel: CallableKernel): Promise<{ seeded: number }>
       const created = (await kernel.call(NODE_CREATE, {
         class: NOTE_CLASS,
         path: `${NOTES_PARENT}/${s.slug}`,
-        props: { [NAME_KEY]: s.title, [TITLE_KEY]: s.title, [BODY_KEY]: s.body },
+        props: {
+          [NAME_KEY]: s.title,
+          [NOTE_KEYS.title]: s.title,
+          [NOTE_KEYS.body]: s.body,
+          [NOTE_KEYS.summary]: await summarizer.summarize(s.body),
+        },
       })) as { id: string }
       ids[s.slug] = created.id
       seeded++