@astrale-os/sdk 0.1.10 → 0.3.0

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,16 +11,16 @@
  * 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 { AnyRemoteFunctionDef, ViewDef } from '../define'
 import type { SchemaMethodsImpl } from '../method'
 
 // A registry holds views / functions of every deps + param/result shape. Their
@@ -28,19 +28,69 @@ import type { SchemaMethodsImpl } from '../method'
 // site; here they're held loosely and, crucially, kept OUT of `TDeps` inference
 // — so `TDeps` is fixed by `methods` alone (the authoritative deps source) and a
 // view authored with the default `unknown` deps can't fight `methods`'s `Env`.
-// oxlint-disable no-explicit-any
+// oxlint-disable-next-line no-explicit-any
 type AnyViewDef = ViewDef<any>
-type AnyFunctionDef = RemoteFunctionDef<any, any, any>
-// oxlint-enable no-explicit-any
+// The function bag is the canonical, variance-correct one from `../define` (it
+// must accept functions of any auth policy — see the note there). Aliased to
+// keep the local usages below terse.
+type AnyFunctionDef = AnyRemoteFunctionDef
 
 /**
- * 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.
+ * Optional presentation metadata for the domain, served verbatim on the
+ * worker's `/meta` endpoint (see `../deploy/meta`) so a host UI can brand a
+ * freshly-installed domain. Both the block and every field are optional.
  */
-export type ClientBinding = { dir: string }
+export interface DomainManifest {
+  /** Domain logo — an inline SVG string or a `data:` URL (no extra validation). */
+  logo?: string
+  /**
+   * Slug of one of THIS domain's own views to open first — the domain's entry
+   * surface. This is the SERVED form: a plain slug, stamped verbatim onto
+   * `/meta`. Authors don't write the slug directly — they pass the view OBJECT
+   * to `defineDomain` (see {@link DomainManifestConfig.entrypoint}), which
+   * resolves it to this slug. Pinned at app install to the `View` node at
+   * `/<origin>/views/<slug>` via the app's `entrypoint` edge.
+   */
+  entrypoint?: string
+  /**
+   * The ROLES this domain declares — named capability identities a workspace
+   * registers when an app for this domain is installed, then assigns to users
+   * (`default: true` roles are auto-assigned to the installing user). The
+   * domain itself grants each role its resource permissions (typically in its
+   * `postInstall`); declaring a role here only names it. Slugs are validated
+   * (lowercase slug charset, unique) at `defineDomain`.
+   */
+  roles?: readonly DomainRoleDecl[]
+}
+
+/** One declared role of the domain (see {@link DomainManifest.roles}). */
+export interface DomainRoleDecl {
+  /** Stable role slug, unique within the domain (e.g. `"editor"`). */
+  slug: string
+  /** Display name; defaults to the slug. */
+  name?: string
+  /** What holding this role means — shown in permission UIs. */
+  description?: string
+  /** Auto-assign this role to the user installing an app for this domain. */
+  default?: boolean
+}
+
+/**
+ * The author-facing manifest accepted by {@link defineDomain} — identical to the
+ * served {@link DomainManifest} except `entrypoint` is the view OBJECT (a value
+ * of the `views` map) rather than its slug. `defineDomain` resolves it to the
+ * slug by identity, so a renamed or dropped view is a compile error at the
+ * reference site, never a stale string (the same guarantee `postInstall` gives
+ * for functions).
+ */
+export interface DomainManifestConfig extends Omit<DomainManifest, 'entrypoint'> {
+  /**
+   * The view to open first — the domain's entry surface. Pass the view OBJECT
+   * from this domain's own `views` map (e.g. `entrypoint: views.welcome`).
+   * Resolved to its slug here and served as {@link DomainManifest.entrypoint}.
+   */
+  entrypoint?: AnyViewDef
+}
 
 export interface DefineDomainConfig<S extends Schema, TDeps, TEnv = unknown> {
   /** The domain schema (from `schema/`). Its `.domain` seeds the default origin. */
@@ -77,11 +127,14 @@ export interface DefineDomainConfig<S extends Schema, TDeps, TEnv = unknown> {
    */
   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.
+   * Optional presentation metadata stamped onto `/meta`. When `manifest.entrypoint`
+   * is set it MUST be a view from this domain's own `views` map — passed as the
+   * OBJECT (`entrypoint: views.welcome`), resolved to its slug here. A view that
+   * isn't in `views` is a compile error at the reference site, and the
+   * resolution throws loudly if it's somehow absent — so a typo can never dangle
+   * to a NOT_FOUND view path at install.
    */
-  client?: ClientBinding
+  manifest?: DomainManifestConfig
   /**
    * 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 +147,25 @@ 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.
+   * Where the Domain node physically lives in the graph TREE — an absolute tree
+   * path whose LAST segment is the origin (e.g. `'/domains/crm.acme.dev'`).
+   * Optional; defaults to `/domains/<origin>`. This moves ONLY the physical
+   * `has_parent` position: the domain's `installed_in` edge and EVERY typed
+   * address (`/:<origin>`, `/:<origin>:Class`, …) stay ROOT-mounted, so
+   * addressing is unchanged. A platform domain that must stay top-level sets its
+   * own origin path (e.g. `'/workspace.astrale.ai'`).
    */
-  postInstall?: string
+  path?: string
+  /**
+   * 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?: AnyFunctionDef
 }
 
 export interface DomainDefinition {
@@ -114,11 +181,13 @@ 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 }
+  /** Presentation metadata for `/meta`, validated at definition time. */
+  manifest?: DomainManifest
   origin: string
   requires: readonly string[]
   postInstall?: string
+  /** Physical tree path for the Domain node; default `/domains/<origin>`. */
+  path?: string
 }
 
 export function defineDomain<S extends Schema, TDeps, TEnv = unknown>(
@@ -159,57 +228,119 @@ export function defineDomain<S extends Schema, TDeps, TEnv = unknown>(
     } catch {
       throw new Error(
         `defineDomain: invalid \`requires\` entry "${dep}". Use the dependency's origin slug ` +
-          '(lowercase FQDN-like, e.g. "dist.astrale.ai"), not a URL.',
+          '(lowercase FQDN-like, e.g. "example.astrale.ai"), not a URL.',
       )
     }
   })
 
+  // `path`, when set, is the Domain's physical tree path. Validate the
+  // two invariants the serializer/kernel rely on, string-only (no AbsolutePath
+  // import — this module must stay worker-safe): it is absolute with at least one
+  // segment, and its LAST segment equals the origin (the kernel derives origin
+  // from the mount basename in a few places, e.g. has_parent slug + get-access-
+  // token origin recovery). Full structural parse happens at build time.
+  if (config.path !== undefined) {
+    const loc = config.path
+    if (!loc.startsWith('/') || loc === '/') {
+      throw new Error(
+        `defineDomain: \`path\` must be an absolute graph path with at least ` +
+          `one segment (e.g. "/domains/${origin}"), not "${loc}".`,
+      )
+    }
+    if (loc.split('/').pop() !== origin) {
+      throw new Error(
+        `defineDomain: \`path\` last segment must equal the origin "${origin}" ` +
+          `(e.g. "/domains/${origin}" or "/${origin}"), got "${loc}".`,
+      )
+    }
+  }
+
+  // A `manifest.entrypoint` view is resolved to its slug below (in the return),
+  // where a view absent from `views` throws — see `resolveManifest`.
+
+  // Declared roles must carry valid, unique slugs — a role slug becomes a graph
+  // path segment and an identity subject, so the kernel's reserved separators
+  // (`/`, `:`, `@`) can never appear in one. Fail at authoring time.
+  if (config.manifest?.roles !== undefined) {
+    const seen = new Set<string>()
+    for (const role of config.manifest.roles) {
+      if (!/^[a-z0-9][a-z0-9_-]*$/.test(role.slug)) {
+        throw new Error(
+          `defineDomain: invalid \`manifest.roles\` slug "${role.slug}". ` +
+            'Use a lowercase slug (letters, digits, "_", "-"), e.g. "editor".',
+        )
+      }
+      if (seen.has(role.slug)) {
+        throw new Error(`defineDomain: duplicate \`manifest.roles\` slug "${role.slug}".`)
+      }
+      seen.add(role.slug)
+    }
+  }
+
   return {
     schema: config.schema,
     methods: config.methods as DomainDefinition['methods'],
     ...(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 } : {}),
+    ...(config.manifest ? { manifest: resolveManifest(config.manifest, config.views) } : {}),
     origin,
     requires,
-    ...(config.postInstall
-      ? { postInstall: normalizePostInstall(config.postInstall, origin) }
+    ...(config.path ? { path: config.path } : {}),
+    ...(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).
+ * Lower the author-facing manifest (view OBJECT for `entrypoint`) to the served
+ * {@link DomainManifest} (slug for `entrypoint`). The entrypoint view is matched
+ * to its `views`-map key by IDENTITY — the same mechanism `normalizePostInstall`
+ * uses for functions — so a view absent from `views` (one from another domain,
+ * or dropped) throws here instead of dangling to a NOT_FOUND view path at install.
  */
-function normalizePostInstall(postInstall: string, origin: string): string {
-  const slug = extractDomainSlug(postInstall)
-  if (slug === null) {
+function resolveManifest(
+  manifest: DomainManifestConfig,
+  views: Record<string, AnyViewDef> | undefined,
+): DomainManifest {
+  const { entrypoint, ...rest } = manifest
+  if (entrypoint === undefined) return rest
+  const slug = views ? Object.entries(views).find(([, def]) => def === entrypoint)?.[0] : undefined
+  if (slug === undefined) {
+    const viewKeys = Object.keys(views ?? {})
     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}".`,
+      "defineDomain: `manifest.entrypoint` must be one of this domain's own views " +
+        '(pass the view object, e.g. `entrypoint: views.welcome`). ' +
+        `Available views: ${viewKeys.length > 0 ? viewKeys.map((k) => `"${k}"`).join(', ') : '(none)'}.`,
     )
   }
-  if (slug.toLowerCase() !== origin) {
+  return { ...rest, entrypoint: slug }
+}
+
+/**
+ * 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: 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, DomainManifest } from './define-domain'
 
 export { deploy } from './deploy'
 export type { DeployConfig } from './deploy'

package/src/define/remote-function.ts

@@ -1,19 +1,20 @@
 /**
  * Authoring a standalone remote function — a callable not bound to a class.
  * (The verb keeps the `defineRemoteFunction` name; the node it materializes is
- * the canonical kernel `Function` class, the former distribution `RemoteFunction`.)
+ * the canonical kernel `Function` class, replacing the former remote-function wrapper.)
  *
  * 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'
@@ -22,6 +23,7 @@ import type { BoundClientSessionView } from '@astrale-os/kernel-client/session'
 import type { Context } from 'hono'
 import type { z } from 'zod'
 
+import type { DomainIssuer } from '../auth/issuer-mint'
 import type { CallRemoteFn } from '../dispatch/call-remote'
 import type { AuthForPolicy, KernelForAuth } from '../method/context'
 
@@ -46,12 +48,20 @@ export type RemoteFunctionContext<
   /**
    * `BoundClientSessionView` to the parent kernel, bound to the composed
    * credential `union(delegation, self)` — same shape as `RemoteContext.kernel`
-   * for `remoteMethod`. Nullability follows {@link KernelForAuth} of the
+   * for `remoteMethod`, including the typed graph read/write sugar flattened onto
+   * it (`kernel.get` / `kernel.children` / `kernel.query`,
+   * `kernel.createNode` / `kernel.mutate(patch)`, …) over the `function.get` /
+   * `function.mutate` syscalls. Nullability follows {@link KernelForAuth} of the
    * function's `auth`: non-null for the default `'required'`, `… | null` for
    * `'optional'`, `null` for `'public'` (use {@link RemoteFunctionContext.selfKernel}
    * there, after verifying the upstream).
    */
   kernel: TKernel
+  /**
+   * Mint seam for identities THIS DOMAIN issues — same contract as
+   * {@link RemoteContext.issuer}.
+   */
+  issuer: DomainIssuer
   /**
    * Call another worker's remote method, re-minting the credential for the
    * target's audience. Same contract as {@link RemoteContext.callRemote}: throws
@@ -77,12 +87,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. */
@@ -118,11 +122,42 @@ export type RemoteFunctionDef<
   description?: string
 }
 
-// `TAuth = AuthPolicy` (the full union, not the `'required'` default) keeps this
-// permissive across any declared policy; `ctx.kernel` widens to
-// `BoundClientSessionView<FnMap> | null`. Used where the concrete policy is erased.
-// oxlint-disable-next-line no-explicit-any
-export type AnyRemoteFunctionDef = RemoteFunctionDef<any, any, any, AuthPolicy>
+// Loosely-typed "bag" for the per-domain function maps. The PRECISE typing is
+// enforced at each `defineRemoteFunction` call site; this only has to HOLD defs
+// of ANY auth policy. We deliberately do NOT pin a single concrete `TAuth`:
+// `RemoteFunctionContext` carries `kernel: KernelForAuth<TAuth>` (an
+// auth-dependent type that resolves to a concrete union), so any single concrete
+// policy — `'required'` OR the full `AuthPolicy` union — rejects the others when
+// a handler is assigned into the bag under parameter contravariance (a public
+// handler wants `kernel: null`, a required one `kernel: Kernel`; neither fits a
+// fixed bag). Relaxing the `authorize`/`execute` PARAMS to `any` is what makes
+// the bag accept every policy; soundness is unchanged — the bag was already
+// `any, any, any`, and the real contract is checked at the call site.
+// oxlint-disable no-explicit-any
+export type AnyRemoteFunctionDef = Omit<
+  RemoteFunctionDef<any, any, any, AuthPolicy>,
+  'authorize' | 'execute'
+> & {
+  authorize?: (ctx: any) => void | Promise<void>
+  execute: (ctx: any) => any
+}
+// oxlint-enable no-explicit-any
+
+// Compile-time regression guards (pure `type` aliases — zero runtime emit, but
+// checked by `pnpm typecheck` since this file is under `src/`). Each asserts a
+// function of the given auth policy still FITS the bag. If `AnyRemoteFunctionDef`
+// ever narrows back and rejects a policy, the matching `_Assert<false>` errors.
+type _AssertTrue<T extends true> = T
+type _FnFitsBag<D> = D extends AnyRemoteFunctionDef ? true : false
+// Exported only so `noUnusedLocals` treats the assertions as used — it is NOT
+// re-exported by `../define`, so it never reaches the package's public surface.
+// A regression that makes the bag reject a policy turns the matching
+// `_AssertTrue<false>` into a compile error here.
+export type _AuthPolicyBagGuards = [
+  _AssertTrue<_FnFitsBag<RemoteFunctionDef<unknown, unknown, unknown, 'public'>>>,
+  _AssertTrue<_FnFitsBag<RemoteFunctionDef<unknown, unknown, unknown, 'optional'>>>,
+  _AssertTrue<_FnFitsBag<RemoteFunctionDef<unknown, unknown, unknown, 'required'>>>,
+]
 
 /**
  * Identity helper for authoring a RemoteFunction. Returns its argument

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

package/src/deploy/check.ts

@@ -6,14 +6,14 @@ import type { Meta } from './meta'
 import { MetaSchema } from './meta'
 
 export type DeployCheckOptions = {
-  /** Deployed worker URL (e.g. `https://dist.astrale.ai`). */
+  /** Deployed worker URL (e.g. `https://example.astrale.ai`). */
   url: string
   /**
-   * Expected `meta.schemaHash` — the hash of the locally-built `spec.json`
-   * (via `hashSpecFile`). REQUIRED to verify schema drift: when the worker
-   * advertises a `schemaHash` but this is absent, the check fails loudly rather
-   * than silently "passing" an unverified deploy. Per-domain deploy scripts
-   * compute it (`hashSpecFile('./spec.json')`) and pass it.
+   * Expected `meta.schemaHash` — the hash of the domain's install graph (via
+   * `buildInstallGraphHash(domain, url)`). REQUIRED to verify schema drift: when
+   * the worker advertises a `schemaHash` but this is absent, the check fails
+   * loudly rather than silently "passing" an unverified deploy. Per-domain
+   * deploy scripts compute it (`buildInstallGraphHash(...)`) and pass it.
    */
   expectedSchemaHash?: string
   /**
@@ -96,7 +96,7 @@ async function checkSchemaHash(
   if (!opts.expectedSchemaHash) {
     throw new Error(
       `worker advertises schemaHash=${meta.schemaHash} but no expectedSchemaHash was provided — ` +
-        `cannot verify schema drift (pass expectedSchemaHash, e.g. hashSpecFile('./spec.json'))`,
+        `cannot verify schema drift (pass expectedSchemaHash, e.g. buildInstallGraphHash(domain, url))`,
     )
   }
   if (meta.schemaHash !== opts.expectedSchemaHash) {

package/src/deploy/index.ts

@@ -1,3 +1,2 @@
 export { MetaSchema, type Meta } from './meta'
-export { hashSpecFile } from './hash-spec'
 export { deployCheck, type DeployCheckOptions } from './check'

package/src/deploy/meta.ts

@@ -11,6 +11,8 @@
 import { z } from 'zod'
 
 export const MetaSchema = z.object({
+  // The version of the meta payload. Incremented on any change to the payload
+  version: z.number().int().min(1).default(1),
   /** Base URL where JWKS is published. Always stamped by `createRemoteServer`
    *  and required by `deployCheck` to verify JWKS reachability. */
   iss: z.string().min(1),
@@ -20,6 +22,29 @@ export const MetaSchema = z.object({
   schemaHash: z.string().optional(),
   /** Local directory name under `kernel/domains/<...>/` — used to auto-resolve the local spec. */
   domainName: z.string().optional(),
+  /**
+   * Optional presentation metadata declared on the domain (`defineDomain`):
+   * `logo` (inline SVG / `data:` URL), `entrypoint` (a view slug — the domain's
+   * entry surface), and the domain's declared `roles` (registered by a workspace
+   * at app install). Served verbatim so a host UI can brand a freshly-installed
+   * domain.
+   */
+  manifest: z
+    .object({
+      logo: z.string().optional(),
+      entrypoint: z.string().optional(),
+      roles: z
+        .array(
+          z.object({
+            slug: z.string().min(1),
+            name: z.string().optional(),
+            description: z.string().optional(),
+            default: z.boolean().optional(),
+          }),
+        )
+        .optional(),
+    })
+    .optional(),
 })
 
 export type Meta = z.infer<typeof MetaSchema>