@astrale-os/sdk 0.1.9 → 0.2.0

package/src/config/adapter.ts

@@ -32,17 +32,18 @@ export interface DomainInfo {
   /** Optional Astrale Path called by the kernel after install (as __SYSTEM__). */
   postInstall?: string
   /**
-   * Whether the domain declares any Views / standalone Functions / a client SPA
-   * — read from the `defineDomain` definition, NOT probed from the filesystem.
-   * The adapter codegen imports the corresponding module / mounts the SPA hook
-   * only when true. `hasClient` governs the WORKER's `/ui` hook specifically
-   * (present whenever the domain has a client, even on managed deploys that ship
-   * the built assets separately and pass no `clientDir`); the wrangler
-   * `assets.directory` binding tracks `clientDir` instead.
+   * Whether the domain declares Views / standalone Functions — read from the
+   * `defineDomain` definition, NOT probed from the filesystem. The adapter
+   * codegen imports the corresponding module only when true.
    */
   hasViews: boolean
   hasFunctions: boolean
-  hasClient: boolean
+  /**
+   * Views whose binding is backed by a worker-relative SPA mount. This is domain
+   * contract metadata (`defineView({ mount })`), not a frontend source folder:
+   * adapters decide, per env, which client assets serve these mounts.
+   */
+  mountedViews: Array<{ slug: string; mount: string }>
   /**
    * Whether the domain declares a `deps` mapper (`defineDomain({ deps })`).
    * When true the adapter codegen imports it from the domain's fixed `deps`
@@ -58,8 +59,6 @@ export interface WatchCtx {
   projectDir: string
   /** Absolute path where the CLI writes the diagnostic `spec.json`. */
   specPath: string
-  /** Absolute path to the client SPA dir, when the domain declares a `client`. */
-  clientDir?: string
   /** Flat secret map loaded from the env's `secrets` file — injected locally in dev. */
   secrets: Record<string, string>
   /** Domain metadata for codegen. */
@@ -75,10 +74,16 @@ export interface DeployCtx {
   specPath: string
   /** Flat secret map loaded from the env's `secrets` file (gitignored). */
   secrets: Record<string, string>
-  clientDir?: string
   domain: DomainInfo
   /** The env key being deployed (e.g. 'dev' | 'prod' | 'canary'). */
   env: string
+  /**
+   * Build the expected install-graph hash for a concrete serving URL from the
+   * current domain definition. Adapters that must verify live drift during
+   * deploy should use this instead of reading `.astrale/spec.json`, which is a
+   * post-deploy diagnostic artifact and may be stale.
+   */
+  schemaHashForUrl?(url: string): Promise<string | undefined>
 }
 
 /** A running local watch — exposes its URL and a stop handle. */

package/src/config/define-domain.ts

@@ -1,7 +1,7 @@
 /**
  * `defineDomain` — the WORKER-SAFE definition of a domain: what the domain *is*
- * (its `schema`, `methods`, `deps`, `views`, standalone `functions`, `client`
- * SPA) plus its addressing identity (`origin`, `requires`, `postInstall`). It
+ * (its `schema`, `methods`, `deps`, `views`, standalone `functions`) plus its
+ * addressing identity (`origin`, `requires`, `postInstall`). It
  * deliberately carries NO deployment adapter — the adapter (`cloudflare(...)`,
  * `astrale(...)`) is node-only code (filesystem, wrangler) that must never enter
  * the worker bundle. The author wires this in a `domain.ts` the generated worker
@@ -11,14 +11,14 @@
  * The modules are wired EXPLICITLY here — imported and passed in — not
  * discovered from magic folder names. A renamed or mistyped module is a compile
  * error at this call site, never a silently-missing worker route. The adapter
- * reads this one definition for everything it codegens; there is no second
- * filesystem probe to drift from it. `defineDomain` itself builds no server and
- * boots no kernel — it validates and packages the declaration.
+ * reads this one definition for domain-side codegen; frontend source folders
+ * live in adapter env config. `defineDomain` itself builds no server and boots
+ * no kernel — it validates and packages the declaration.
  */
 
 import type { Schema } from '@astrale-os/kernel-dsl'
 
-import { DomainOrigin, extractDomainSlug } from '@astrale-os/kernel-core/domain'
+import { DomainOrigin } from '@astrale-os/kernel-core/domain'
 
 import type { RemoteFunctionDef, ViewDef } from '../define'
 import type { SchemaMethodsImpl } from '../method'
@@ -33,15 +33,6 @@ type AnyViewDef = ViewDef<any>
 type AnyFunctionDef = RemoteFunctionDef<any, any, any>
 // oxlint-enable no-explicit-any
 
-/**
- * The domain's client SPA binding. Its presence is the whole signal — there is
- * no `existsSync('client/')` probe. `dir` is the project-relative source folder
- * (e.g. `'client'`); the worker serves its built SPA under `/ui` via its Assets
- * binding. Always written out explicitly (`client: { dir: 'client' }`) — there
- * is no boolean shorthand, so the source folder is never implicit.
- */
-export type ClientBinding = { dir: string }
-
 export interface DefineDomainConfig<S extends Schema, TDeps, TEnv = unknown> {
   /** The domain schema (from `schema/`). Its `.domain` seeds the default origin. */
   schema: S
@@ -76,12 +67,6 @@ export interface DefineDomainConfig<S extends Schema, TDeps, TEnv = unknown> {
    * by slug. Omit when the domain has none.
    */
   functions?: Record<string, AnyFunctionDef>
-  /**
-   * The domain's client SPA, e.g. `{ dir: 'client' }`. Its presence enables it
-   * (no folder probing); `dir` is the project-relative source folder, built and
-   * served under `/ui`. Omit for a domain with no SPA.
-   */
-  client?: ClientBinding
   /**
    * The domain's **addressing name** (the graph slug it mounts under, e.g.
    * `'crm.acme.dev'`). Defaults to `schema.domain`. Must be a name, never a
@@ -94,11 +79,15 @@ export interface DefineDomainConfig<S extends Schema, TDeps, TEnv = unknown> {
   /** Cross-domain deps, by origin. Verified present on the instance at install. */
   requires?: readonly string[]
   /**
-   * Astrale Path (usually an AbsolutePath to a `functions/` entry) the kernel
-   * calls once after install, as __SYSTEM__ — where the domain posts its own
-   * grants / seed.
+   * The function the kernel runs once after install, as __SYSTEM__ — where the
+   * domain seeds itself / posts its own grants. Reference it from the `functions`
+   * map: `postInstall: functions.seed`. The SDK derives its path by identity, so a
+   * typo or a renamed key is a compile error here, never a stale string. It is
+   * always a standalone function (a domain bootstrap belongs to the domain, not to
+   * a class) under THIS domain — you never write the origin, and the kernel
+   * resolves it relative to wherever the domain is installed.
    */
-  postInstall?: string
+  postInstall?: AnyFunctionDef
 }
 
 export interface DomainDefinition {
@@ -114,8 +103,6 @@ export interface DomainDefinition {
   deps?: (env: any, url: string) => any
   views?: Record<string, ViewDef>
   functions?: Record<string, AnyFunctionDef>
-  /** Normalized client binding (resolved `dir`), or absent when the domain has no SPA. */
-  client?: { dir: string }
   origin: string
   requires: readonly string[]
   postInstall?: string
@@ -170,46 +157,37 @@ export function defineDomain<S extends Schema, TDeps, TEnv = unknown>(
     ...(config.deps ? { deps: config.deps as DomainDefinition['deps'] } : {}),
     ...(config.views ? { views: config.views as Record<string, ViewDef> } : {}),
     ...(config.functions ? { functions: config.functions } : {}),
-    ...(config.client ? { client: config.client } : {}),
     origin,
     requires,
-    ...(config.postInstall
-      ? { postInstall: normalizePostInstall(config.postInstall, origin) }
+    ...(config.postInstall !== undefined
+      ? { postInstall: normalizePostInstall(config.postInstall, origin, config.functions) }
       : {}),
   }
 }
 
 /**
- * Validate a `postInstall` hook path and align its leading origin segment with
- * the canonical (lowercased) origin. Only the typed colon forms are accepted
- * (`/:<origin>:class.X:seed`, `/:<origin>:interface.Ops:seed`) — mirroring the
- * kernel's own origin guard, which refuses absolute tree paths because they
- * cannot prove their origin from the string alone. The hook is often authored
- * as `` `/:${schema.domain}:…` `` where `schema.domain` keeps its source
- * casing, but the kernel stores graph nodes (and runs its guard) under the
- * lowercased origin — so the origin segment is re-stamped canonical. Rejects a
- * tree path or one pointing at a different domain (the kernel calls the hook
- * as __SYSTEM__ and refuses a foreign target).
+ * Resolve a `postInstall` function reference to the colon-path the bundle carries.
+ * The slug is the `functions` map key the reference is registered under (found by
+ * identity), so a renamed key is a compile error at the reference site AND the
+ * derived path follows the rename. The origin is never the author's to supply
+ * (postInstall is always a standalone function of THIS domain) and the path is
+ * mount-agnostic — the kernel resolves it wherever the domain is installed.
  */
-function normalizePostInstall(postInstall: string, origin: string): string {
-  const slug = extractDomainSlug(postInstall)
-  if (slug === null) {
-    throw new Error(
-      `defineDomain: \`postInstall\` must be a typed colon-path under "/:${origin}" ` +
-        `(e.g. "/:${origin}:class.Note:seed" or "/:${origin}:interface.Ops:seed"); ` +
-        `absolute tree paths are not accepted — got "${postInstall}".`,
-    )
-  }
-  if (slug.toLowerCase() !== origin) {
+function normalizePostInstall(
+  postInstall: AnyFunctionDef,
+  origin: string,
+  functions: Record<string, AnyFunctionDef> | undefined,
+): string {
+  const slug = functions
+    ? Object.entries(functions).find(([, def]) => def === postInstall)?.[0]
+    : undefined
+  if (slug === undefined) {
     throw new Error(
-      `defineDomain: \`postInstall\` "${postInstall}" must resolve under the domain origin ` +
-        `"/${origin}" — the kernel calls it as __SYSTEM__ and refuses a hook pointing at another domain.`,
+      "defineDomain: `postInstall` must reference a function from this domain's `functions` map " +
+        '(e.g. `postInstall: functions.seed`).',
     )
   }
-  // Re-stamp the origin segment with its canonical (lowercased) form.
-  return postInstall.startsWith('/:')
-    ? `/:${origin}${postInstall.slice(2 + slug.length)}`
-    : `/${origin}${postInstall.slice(1 + slug.length)}`
+  return `/:${origin}:function.${slug}`
 }
 
 function schemaDomain(schema: Schema): string | undefined {

package/src/config/deploy.ts

@@ -9,7 +9,7 @@
  * is authored in `astrale.config.ts` — a Node-only module the CLI loads but the
  * worker never imports — so the adapter stays out of the bundle.
  *
- *   export const domain = defineDomain({ schema, methods, deps, views, client })
+ *   export const domain = defineDomain({ schema, methods, deps, views })
  *
  *   import { domain } from './domain'
  *   export default deploy(domain, cloudflare({ dev, prod }))

package/src/config/index.ts

@@ -14,7 +14,7 @@
  */
 
 export { defineDomain } from './define-domain'
-export type { ClientBinding, DefineDomainConfig, DomainDefinition } from './define-domain'
+export type { DefineDomainConfig, DomainDefinition } from './define-domain'
 
 export { deploy } from './deploy'
 export type { DeployConfig } from './deploy'

package/src/define/remote-function.ts

@@ -4,16 +4,17 @@
  * the canonical kernel `Function` class, the former distribution `RemoteFunction`.)
  *
  * Each entry in `defineRemoteDomain({ remoteFunctions: { ... } })` becomes:
- *   - a graph node at `/${origin}/core/<functionsFolder>/<slug>`, materialized
- *     as the kernel `Function` class by `buildCorePath` so kernel discovery /
- *     `View.resolve` can list it. The `core/` anchor appears in the GRAPH path only.
+ *   - a graph node at `/${origin}/functions/<slug>` — a first-class domain MEMBER,
+ *     materialized as the kernel `Function` class and attached to the Domain via an
+ *     `of_domain` edge (slug `function.<slug>`), so it is addressable by the
+ *     semantic path `/:${origin}:function.<slug>` (the form a `postInstall` uses).
  *   - a Hono route on the worker at the path implied by `binding`
- *     (`/<functionsFolder>/<slug>` POST by default — no `core/` in the URL).
+ *     (`/<functionsFolder>/<slug>` POST by default — the route URL is decoupled
+ *     from the graph layout).
  *
- * The slug = the map key (single source of truth, no duplication).
- *
- * `ref` is auto-derived as `function.<slug>` if omitted — used as
- * `Function.ref` on the graph node and as the dispatch key.
+ * The slug = the map key (single source of truth, no duplication). The member
+ * ref (`function.<slug>`), the layout (`/<origin>/functions/<slug>`), and the
+ * `of_domain` edge slug are all DERIVED from it — there is nothing else to name.
  */
 
 import type { AuthPolicy, FunctionBinding } from '@astrale-os/kernel-api/routed'
@@ -77,12 +78,6 @@ export type RemoteFunctionDef<
   TDeps = unknown,
   TAuth extends AuthPolicy = 'required',
 > = {
-  /**
-   * Canonical callable identity. Auto-derived as `function.<slug>` (where
-   * `<slug>` is the map key) when omitted. Stored as `Function.ref` on the
-   * graph node and used by the kernel dispatcher to route the call.
-   */
-  ref?: string
   /** Zod schema for the call's parameters. */
   inputSchema: z.ZodType<TParams>
   /** Zod schema for the call's result. */

package/src/define/view.ts

@@ -2,14 +2,16 @@
  * Authoring a `View` — iframe-mountable callable served by the domain worker.
  *
  * Each entry in `defineRemoteDomain({ views: { ... } })` becomes both:
- *   - a graph node at `/${origin}/core/<viewsFolder>/<slug>` (auto-materialized
- *     by the SDK; the `core/` segment is the universal anchor injected by
- *     `buildCorePath`. `<slug>` is the map key, so it lives in exactly one place)
+ *   - a first-class domain MEMBER: a `View` node at `/${origin}/views/<slug>`
+ *     attached to the Domain via an `of_domain` edge (slug `view.<slug>`),
+ *     addressable as `/:${origin}:view.<slug>`. `<slug>` is the map key, so it
+ *     lives in exactly one place.
  *   - a Hono route on the worker at the path implied by `binding`
- *     (`/<viewsFolder>/<slug>` by default — note: no `core/` in the URL).
+ *     (`/<viewsFolder>/<slug>` by default).
  *
- * The `core/` segment appears in the GRAPH path only; the URL path that
- * lands in `Function.binding.remoteUrl` is `${url}/<viewsFolder>/<slug>`.
+ * The graph layout (`/<origin>/views/<slug>`) is a fixed kernel convention; the
+ * URL path that lands in `Function.binding.remoteUrl` is
+ * `${url}/<viewsFolder>/<slug>` — DECOUPLED from the graph layout.
  *
  * The author can override the URL via `binding` — host and/or path
  * placeholders are supported (the kernel's `route` mechanism does the
@@ -72,6 +74,12 @@ export type ViewDef<TDeps = unknown, TAuth extends AuthPolicy = AuthPolicy> = {
    * with `render`; takes precedence over `binding`.
    */
   mount?: string
+  /**
+   * Shell handshake mode for the mounted iframe. Omit for the common case:
+   * SPA-mounted views (`mount`) use the shell handshake; inline `render` views
+   * default to `'none'` because they do not include the shell client.
+   */
+  handshake?: 'shell' | 'none'
   /** Authentication policy. Defaults to `'required'`. */
   auth?: TAuth
   /**

package/src/dispatch/identity.ts

@@ -1,10 +1,10 @@
 /**
  * Per-callable identity — dispatcher runtime + install-time wiring.
  *
- * Two flavors of callable get an identity per the install-time identity
- * binding: Methods on classes/interfaces (sub = MethodPath) and auto-
- * materialized core function nodes — RemoteFunctions and Views (sub =
- * AbsolutePath of the node under `core/{functions,views}/<slug>`).
+ * Three flavors of callable get an identity per the install-time identity
+ * binding: Methods on classes/interfaces (sub = MethodPath), standalone-function
+ * MEMBERS (sub = AbsolutePath at `/<origin>/functions/<slug>`), and view MEMBERS
+ * (sub = AbsolutePath at `/<origin>/views/<slug>`).
  *
  * At server startup the method dispatcher and the View / RemoteFunction
  * route mounter pre-compute, for every materialized callable, the
@@ -54,11 +54,12 @@ export type AuxBuckets<T> = {
 }
 
 /**
- * slug → `AbsolutePath.raw` for each auto-materialized aux node
- * (RemoteFunction / View). These nodes live at
- * `/<origin>/core/{functions,views}/<slug>` and have no class+method
- * decomposition that would justify a MethodPath — their identity is their
- * graph position.
+ * slug → `AbsolutePath.raw` for each aux callable MEMBER node:
+ *   - standalone-function members (`kind: 'function'`) at `/<origin>/functions/<slug>`;
+ *   - view members (`kind: 'view'`) at `/<origin>/views/<slug>` (plus any
+ *     hand-authored/legacy core `View` nodes, `kind: 'core'` className `View`).
+ * Neither has a class+method decomposition that would justify a MethodPath —
+ * their identity is their graph position.
  */
 export type AuxIdentityPaths = AuxBuckets<string>
 
@@ -66,20 +67,13 @@ export function collectAuxIdentityPaths(compiled: CompiledDomain): AuxIdentityPa
   const views: Record<string, string> = {}
   const remoteFunctions: Record<string, string> = {}
   for (const c of resolveCallables(compiled)) {
-    if (c.kind !== 'core' || !c.slug) continue
-    if (c.className === 'View') {
-      views[c.slug] = c.sub
-    } else if (c.className === 'Function') {
-      // Standalone callables (the former `RemoteFunction`) materialize as the
-      // canonical kernel `Function` class.
+    if (!c.slug) continue
+    if (c.kind === 'function') {
       remoteFunctions[c.slug] = c.sub
-    } else {
-      throw new Error(
-        `collectAuxIdentityPaths: unrecognised aux callable className "${c.className}" ` +
-          `at ${c.ref}. If you've added a new auto-materialized Function class to extendCore, ` +
-          `extend this collector + the kernel walker (resolveCallables) to handle it.`,
-      )
+    } else if (c.kind === 'view' || (c.kind === 'core' && c.className === 'View')) {
+      views[c.slug] = c.sub
     }
+    // Methods (`kind: 'method'`) get their identity via `collectMethodPaths`.
   }
   return { views, remoteFunctions }
 }

package/src/domain/binding.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared binding helpers for auto-materialized members (functions + views).
+ *
+ * The worker ROUTE URL a member is served at — `<url>/<folderSlug>/<slug>` — is
+ * decoupled from the member's GRAPH layout (`/<origin>/{functions,views}/<slug>`,
+ * a fixed kernel convention). `folderSlug` names only the URL segment.
+ */
+
+import type { FunctionBinding } from '@astrale-os/kernel-api/routed'
+
+/** Join a worker-relative mount path onto the serving url (single slash). */
+export function joinWorkerPath(url: string, mount: string): string {
+  const base = url.replace(/\/+$/, '')
+  return `${base}/${mount.replace(/^\/+/, '')}`
+}
+
+/**
+ * Resolve a member's effective binding against the serving `url`. An explicit
+ * `override.remoteUrl` wins; otherwise defaults to `<url>/<folderSlug>/<slug>`.
+ * Same trailing-slash discipline as {@link joinWorkerPath} — a `url` ending in
+ * `/` must not produce `//` (the kernel pins `iss` by exact string).
+ */
+export function resolveBinding(
+  override: FunctionBinding | undefined,
+  url: string,
+  folderSlug: string,
+  slug: string,
+): FunctionBinding {
+  const base = url.replace(/\/+$/, '')
+  if (override) {
+    return {
+      ...override,
+      remoteUrl: override.remoteUrl ?? `${base}/${folderSlug}/${slug}`,
+    }
+  }
+  return { remoteUrl: `${base}/${folderSlug}/${slug}` }
+}

package/src/domain/build-spec.ts

@@ -18,7 +18,7 @@
  */
 
 import type { Graph, WireGraph } from '@astrale-os/kernel-core'
-import type { BoundMethod, FunctionSchema } from '@astrale-os/kernel-core/domain'
+import type { BoundMethod, FunctionSchema, ViewSchema } from '@astrale-os/kernel-core/domain'
 import type { Schema } from '@astrale-os/kernel-dsl'
 
 import { hashInstallGraph, serialize, zodToJsonSchema } from '@astrale-os/kernel-core/domain'
@@ -41,8 +41,14 @@ export function buildInstallGraph<S extends Schema>(
   domain: RemoteDomain<S>,
   url: string,
 ): WireGraph {
-  const { compiled } = materializeRemoteDomain(domain, url)
-  return buildSpecInternal(compiled, domain.methods, url).toWire() as WireGraph
+  const { compiled, auxiliary } = materializeRemoteDomain(domain, url)
+  return buildSpecInternal(
+    compiled,
+    domain.methods,
+    url,
+    auxiliary?.functionSchemas ?? [],
+    auxiliary?.viewSchemas ?? [],
+  ).toWire() as WireGraph
 }
 
 /**
@@ -63,12 +69,17 @@ function buildSpecInternal(
   compiled: RemoteDomain['compiled'],
   methods: BoundMethod<AnyRemoteHandler>[],
   url: string,
+  functionSchemas: FunctionSchema[],
+  viewSchemas: ViewSchema[],
 ): Graph {
   const serialized = serializeMethodsWithStubs(compiled, methods, url)
-  const tree = serialize(compiled, serialized)
-  // Views / RemoteFunctions are auto-materialized into the Core BEFORE
-  // `compileDomain` runs (see `extend-core.ts`). By the time we reach
-  // `serialize` here the Tree already contains their nodes/edges.
+  // Method impls + standalone-function-member impls travel in the same callable
+  // array (distinct refs: `class.X.method.y` vs `function.<slug>`); view-member
+  // impls travel in `options.views` (a view differs structurally — handshake,
+  // view_for, View class). The serializer emits method nodes from the IR,
+  // function/view members from `compiled.$.refs.{functions,views}`, pulling each
+  // impl by ref.
+  const tree = serialize(compiled, [...serialized, ...functionSchemas], { views: viewSchemas })
   return tree.toGraph()
 }