@astrale-os/sdk 0.1.9 → 0.2.0

package/src/domain/define.ts

@@ -1,14 +1,14 @@
 /**
  * `defineRemoteDomain` — turn a typed schema + methods map into a mountable domain.
  *
- * When `views` and/or `remoteFunctions` entries are provided, the SDK
- * auto-materializes graph nodes
- * under reserved folders (`viewsFolder` / `functionsFolder`, defaults `'views'`
- * / `'functions'`). Views and standalone functions materialize as canonical
- * kernel `View` / `Function` classes by default (no per-domain class to
- * configure). The same entries'
+ * `views` and `functions` entries become first-class DOMAIN MEMBERS: a `View` /
+ * `Function` node attached to the Domain via an `of_domain` edge (slug
+ * `view.<slug>` / `function.<slug>`), laid out at `/<origin>/{views,functions}/<slug>`.
+ * Their contract half (the member ref) threads through `compileDomain`; their
+ * impl/binding half threads through `serialize`. The same entries'
  * `render` / `execute` handlers are mounted as Hono routes by
- * `createRemoteServer`. Slug = map key.
+ * `createRemoteServer` at `<url>/<viewsFolder|functionsFolder>/<slug>` (the route
+ * URL is decoupled from the graph layout). Slug = map key.
  *
  * The domain definition is deployment-agnostic: it carries NO serving url. The
  * url is supplied late by the spec producer (`createRemoteServer({ url })` at
@@ -18,8 +18,13 @@
  */
 
 import type { FunctionBinding } from '@astrale-os/kernel-api/routed'
-import type { BoundMethod, CompiledDomain } from '@astrale-os/kernel-core/domain'
-import type { AnyEdgeDef, AnyNodeDef, Core, Schema } from '@astrale-os/kernel-dsl'
+import type {
+  BoundMethod,
+  CompiledDomain,
+  FunctionSchema,
+  ViewSchema,
+} from '@astrale-os/kernel-core/domain'
+import type { Core, Schema } from '@astrale-os/kernel-dsl'
 
 import { bindMethods, compileDomain } from '@astrale-os/kernel-core/domain'
 
@@ -27,7 +32,12 @@ import type { AnyRemoteFunctionDef, ViewDef } from '../define'
 import type { SchemaMethodsImpl } from '../method/class'
 import type { AnyRemoteHandler } from '../method/single'
 
-import { DEFAULT_FUNCTIONS_FOLDER, DEFAULT_VIEWS_FOLDER, extendCore } from './extend-core'
+import {
+  buildFunctionDeclarations,
+  buildFunctionSchemas,
+  DEFAULT_FUNCTIONS_FOLDER,
+} from './extend-functions'
+import { buildViewDeclarations, buildViewSchemas, DEFAULT_VIEWS_FOLDER } from './extend-views'
 
 export type RemoteDomainConfig<S extends Schema, TDeps> = {
   schema: S
@@ -35,27 +45,29 @@ export type RemoteDomainConfig<S extends Schema, TDeps> = {
   core?: Core<S>
 
   views?: Record<string, ViewDef<TDeps>>
-  viewClass?: AnyNodeDef
-  viewForEdgeClass?: AnyEdgeDef
   viewsFolder?: string
 
   remoteFunctions?: Record<string, AnyRemoteFunctionDef>
   functionsFolder?: string
 }
 
-/** Effective bindings + folder layout for auxiliary routes, resolved against `url`. */
+/** Effective bindings + folder layout + member schemas for auxiliary routes, resolved against `url`. */
 export type AuxiliaryMetadata = {
   url: string
   viewsFolder: string
   functionsFolder: string
   viewBindings: Record<string, FunctionBinding>
   remoteFunctionBindings: Record<string, FunctionBinding>
+  /** Function members' impl/binding half (`function.<slug>`) for `serialize`. */
+  functionSchemas: FunctionSchema[]
+  /** View members' impl/binding half (`view.<slug>`) for `serialize`. */
+  viewSchemas: ViewSchema[]
 }
 
 export type RemoteDomain<S extends Schema = Schema> = {
   /**
-   * Define-time compile: full domain STRUCTURE (classes, methods, and the aux
-   * View/Function nodes' paths/names/refs — what identity, subs, and contract
+   * Define-time compile: full domain STRUCTURE (classes, methods, and the
+   * view/function members' paths/names/refs — what identity, subs, and contract
    * resolution need). It carries NO `binding` values: bindings derive from the
    * serving url, which only the spec producers know — they call
    * `materializeRemoteDomain(domain, url)` for the install-ready compile.
@@ -65,42 +77,32 @@ export type RemoteDomain<S extends Schema = Schema> = {
   // oxlint-disable-next-line no-explicit-any
   views?: Record<string, ViewDef<any>>
   remoteFunctions?: Record<string, AnyRemoteFunctionDef>
-  /** The original config, so `materializeRemoteDomain` re-extends from source. */
-  config: ExtendInputs
+  /** The original config, so `materializeRemoteDomain` re-materializes from source. */
+  config: MaterializeInputs
 }
 
-/** The defineRemoteDomain inputs `materializeRemoteDomain` needs to re-extend. */
-type ExtendInputs = {
+/** The defineRemoteDomain inputs `materializeRemoteDomain` needs to re-materialize. */
+type MaterializeInputs = {
   userCore?: Core
-  viewClass?: AnyNodeDef
-  viewForEdgeClass?: AnyEdgeDef
   viewsFolder: string
   functionsFolder: string
 }
 
 export function defineRemoteDomain<TDeps>() {
   return function <S extends Schema>(config: RemoteDomainConfig<S, TDeps>): RemoteDomain<S> {
-    const hasAux = Boolean(config.views || config.remoteFunctions)
     const viewsFolder = config.viewsFolder ?? DEFAULT_VIEWS_FOLDER
     const functionsFolder = config.functionsFolder ?? DEFAULT_FUNCTIONS_FOLDER
 
-    // Structure-only extension (no url → no bindings stamped): the aux nodes
-    // exist with their paths so subs/identity/contract resolution see them.
-    const effectiveCore: Core | undefined = hasAux
-      ? extendCore({
-          schema: config.schema,
-          origin: config.schema.domain,
-          userCore: config.core,
-          viewClass: config.viewClass,
-          viewForEdgeClass: config.viewForEdgeClass,
-          viewsFolder,
-          views: config.views,
-          functionsFolder,
-          remoteFunctions: config.remoteFunctions,
-        }).core
-      : config.core
-
-    const compiled = compileDomain(config.schema, effectiveCore as Core<S> | undefined)
+    // Views + functions are domain MEMBERS — their contract enters compile via
+    // the `functions` / `views` args (no Core involvement). `config.core` is the
+    // author's own genuine genesis instance data, untouched.
+    const compiled = compileDomain(
+      config.schema,
+      config.core,
+      undefined,
+      config.remoteFunctions ? buildFunctionDeclarations(config.remoteFunctions) : undefined,
+      config.views ? buildViewDeclarations(config.views) : undefined,
+    )
     const methods = bindMethods<AnyRemoteHandler>(
       compiled.$.schema,
       compiled.$.methods,
@@ -115,8 +117,6 @@ export function defineRemoteDomain<TDeps>() {
       ...(config.remoteFunctions ? { remoteFunctions: config.remoteFunctions } : {}),
       config: {
         userCore: config.core,
-        viewClass: config.viewClass,
-        viewForEdgeClass: config.viewForEdgeClass,
         viewsFolder,
         functionsFolder,
       },
@@ -125,13 +125,13 @@ export function defineRemoteDomain<TDeps>() {
 }
 
 /**
- * Materialize a `RemoteDomain` at its real serving `url`: re-runs `extendCore`
- * so every aux View/Function `binding.remoteUrl` points at the actual host,
- * and returns the binding maps the auxiliary routes mount from. Called by the
- * only two spec producers — `createRemoteServer` (`config.url`) and the
- * `astrale-domain` CLI. Returns the define-time `compiled` untouched when there is no aux to
- * stamp. `extendCore`/`compileDomain` are pure, so this is safe to call
- * repeatedly (and is memoized per cold isolate by the callers).
+ * Materialize a `RemoteDomain` at its real serving `url`: re-compiles the domain
+ * and builds every member's url-stamped impl schema + binding, returning the
+ * binding maps the auxiliary routes mount from and the member schemas `serialize`
+ * emits from. Called by the only two spec producers — `createRemoteServer`
+ * (`config.url`) and the `astrale-domain` CLI. Returns the define-time `compiled`
+ * untouched when there is no aux to stamp. Pure, so safe to call repeatedly (and
+ * memoized per cold isolate by the callers).
  */
 export function materializeRemoteDomain<S extends Schema>(
   domain: RemoteDomain<S>,
@@ -142,27 +142,32 @@ export function materializeRemoteDomain<S extends Schema>(
 
   const { config } = domain
   const schema = domain.compiled.$.schema as S
-  const result = extendCore({
+
+  const compiled = compileDomain(
     schema,
-    origin: schema.domain,
-    userCore: config.userCore,
-    url,
-    viewClass: config.viewClass,
-    viewForEdgeClass: config.viewForEdgeClass,
-    viewsFolder: config.viewsFolder,
-    views: domain.views,
-    functionsFolder: config.functionsFolder,
-    remoteFunctions: domain.remoteFunctions,
-  })
-  const compiled = compileDomain(schema, result.core as Core<S>)
+    config.userCore as Core<S> | undefined,
+    undefined,
+    domain.remoteFunctions ? buildFunctionDeclarations(domain.remoteFunctions) : undefined,
+    domain.views ? buildViewDeclarations(domain.views) : undefined,
+  )
+
+  const fns = domain.remoteFunctions
+    ? buildFunctionSchemas(domain.remoteFunctions, url, config.functionsFolder)
+    : { schemas: [], bindings: {} }
+  const vws = domain.views
+    ? buildViewSchemas(domain.views, url, config.viewsFolder, schema)
+    : { schemas: [], bindings: {} }
+
   return {
     compiled,
     auxiliary: {
       url,
       viewsFolder: config.viewsFolder,
       functionsFolder: config.functionsFolder,
-      viewBindings: result.viewBindings,
-      remoteFunctionBindings: result.remoteFunctionBindings,
+      viewBindings: vws.bindings,
+      remoteFunctionBindings: fns.bindings,
+      functionSchemas: fns.schemas,
+      viewSchemas: vws.schemas,
     },
   }
 }

package/src/domain/extend-functions.ts

@@ -0,0 +1,86 @@
+/**
+ * Materialize the `functions` map (`defineRemoteFunction` entries) into the two
+ * halves a standalone-function DOMAIN MEMBER contributes — mirroring how a class
+ * method splits across compile + serialize:
+ *
+ *   - `FunctionDeclarations` — the CONTRACT half, fed to `compileDomain`'s 4th
+ *     arg. The member ref (`function.<slug>`), the layout
+ *     (`/<origin>/functions/<slug>`), and the `of_domain` edge slug all derive
+ *     from the map key; the kernel owns that mapping.
+ *   - `FunctionSchema[]` + per-slug `FunctionBinding` — the IMPL/BINDING half,
+ *     fed to `serialize` (url-stamped). The worker route is
+ *     `<url>/<functionsFolder>/<slug>`, DECOUPLED from the graph layout — so
+ *     `functionsFolder` only names the URL segment, not the node position.
+ *
+ * A standalone function is NOT a core/instance node: it is attached directly to
+ * the Domain via `of_domain` by the kernel-core serializer, so this module never
+ * touches `Core`.
+ */
+
+import type { FunctionBinding } from '@astrale-os/kernel-api/routed'
+import type { FunctionDeclarations, FunctionSchema } from '@astrale-os/kernel-core/domain'
+
+import { zodToJsonSchema } from '@astrale-os/kernel-core/domain'
+
+import type { AnyRemoteFunctionDef } from '../define/remote-function'
+
+import { resolveBinding } from './binding'
+
+/**
+ * Default URL segment for a function's worker route (`<url>/functions/<slug>`).
+ * Names the HTTP route only — the graph layout (`/<origin>/functions/<slug>`) is
+ * a fixed kernel convention, independent of this.
+ */
+export const DEFAULT_FUNCTIONS_FOLDER = 'functions'
+const SLUG_RE = /^[a-z][a-z0-9-]*$/
+
+function assertValidSlugs(functions: Record<string, AnyRemoteFunctionDef>): void {
+  for (const slug of Object.keys(functions)) {
+    if (!SLUG_RE.test(slug)) {
+      throw new Error(
+        `defineRemoteDomain: invalid function slug "${slug}" — must match ${SLUG_RE}.`,
+      )
+    }
+  }
+}
+
+/**
+ * Contract half — one declaration per `functions` map key, for `compileDomain`'s
+ * `functions` arg. The slug drives ref/path/of_domain; impl/binding arrive at
+ * serialize.
+ */
+export function buildFunctionDeclarations(
+  functions: Record<string, AnyRemoteFunctionDef>,
+): FunctionDeclarations {
+  assertValidSlugs(functions)
+  const out: Record<string, { slug: string }> = {}
+  for (const slug of Object.keys(functions)) out[slug] = { slug }
+  return out
+}
+
+/**
+ * Impl/binding half — `FunctionSchema[]` for `serialize` plus the per-slug
+ * `FunctionBinding` map the worker mounts routes from. `ref` is the canonical
+ * `function.<slug>` member ref (matching `compiled.$.refs.functions`), so the
+ * serializer's per-member impl lookup finds it.
+ */
+export function buildFunctionSchemas(
+  functions: Record<string, AnyRemoteFunctionDef>,
+  url: string,
+  functionsFolder: string,
+): { schemas: FunctionSchema[]; bindings: Record<string, FunctionBinding> } {
+  const schemas: FunctionSchema[] = []
+  const bindings: Record<string, FunctionBinding> = {}
+  for (const [slug, def] of Object.entries(functions)) {
+    const binding = resolveBinding(def.binding, url, functionsFolder, slug)
+    bindings[slug] = binding
+    schemas.push({
+      ref: `function.${slug}`,
+      inputSchema: zodToJsonSchema(def.inputSchema),
+      outputSchema: zodToJsonSchema(def.outputSchema),
+      output: 'value',
+      binding,
+    })
+  }
+  return { schemas, bindings }
+}

package/src/domain/extend-views.ts

@@ -0,0 +1,151 @@
+/**
+ * Materialize the `views` map (`defineView` entries) into the two halves a view
+ * DOMAIN MEMBER contributes — mirroring `extend-functions.ts`:
+ *
+ *   - `ViewDeclarations` — the CONTRACT half, fed to `compileDomain`'s members
+ *     arg. The member ref (`view.<slug>`), the layout (`/<origin>/views/<slug>`),
+ *     and the `of_domain` edge slug all derive from the map key.
+ *   - `ViewSchema[]` + per-slug `FunctionBinding` — the IMPL half, fed to
+ *     `serialize`. A view carries more than a function: a `UI.handshake` mode and
+ *     `view_for` target edges (resolved here to graph paths). The worker route is
+ *     `<url>/<viewsFolder>/<slug>`, DECOUPLED from the graph layout.
+ *
+ * A view is NOT a core/instance node: the kernel-core serializer attaches it to
+ * the Domain via `of_domain` (slug `view.<slug>`) and emits its `view_for` edges,
+ * so this module never touches `Core`.
+ */
+
+import type { FunctionBinding } from '@astrale-os/kernel-api/routed'
+import type { ViewDeclarations, ViewSchema } from '@astrale-os/kernel-core/domain'
+import type { Schema } from '@astrale-os/kernel-dsl'
+
+import { DomainPaths } from '@astrale-os/kernel-core/domain'
+import { buildDefOriginMap, scanImportedDefs } from '@astrale-os/kernel-core/domain'
+import {
+  buildDefDescriptorMap,
+  isAbstract,
+  isCorePath,
+  isSelfMarker,
+  type EdgeEndpoint,
+} from '@astrale-os/kernel-dsl'
+
+import type { ViewDef } from '../define/view'
+
+import { joinWorkerPath, resolveBinding } from './binding'
+
+/**
+ * Default URL segment for a view's worker route (`<url>/views/<slug>`). Names the
+ * HTTP route only — the graph layout (`/<origin>/views/<slug>`) is a fixed kernel
+ * convention, independent of this.
+ */
+export const DEFAULT_VIEWS_FOLDER = 'views'
+const SLUG_RE = /^[a-z][a-z0-9-]*$/
+
+// oxlint-disable-next-line no-explicit-any
+type AnyViewDef = ViewDef<any>
+
+function assertValidSlugs(views: Record<string, AnyViewDef>): void {
+  for (const slug of Object.keys(views)) {
+    if (!SLUG_RE.test(slug)) {
+      throw new Error(`defineRemoteDomain: invalid view slug "${slug}" — must match ${SLUG_RE}.`)
+    }
+  }
+}
+
+/** Enforce ViewDef's documented exclusivity: `mount` cannot combine with `render`/`binding`. */
+function assertExclusivity(slug: string, def: AnyViewDef): void {
+  if (def.mount && (def.render || def.binding)) {
+    throw new Error(
+      `defineRemoteDomain: view "${slug}" sets \`mount\` together with ` +
+        `${def.render ? '`render`' : '`binding`'} — they are mutually exclusive.`,
+    )
+  }
+}
+
+/**
+ * Contract half — one declaration per `views` map key, for `compileDomain`'s
+ * `views` arg. The slug drives ref/path/of_domain; impl/binding/view_for arrive
+ * at serialize.
+ */
+export function buildViewDeclarations(views: Record<string, AnyViewDef>): ViewDeclarations {
+  assertValidSlugs(views)
+  const out: Record<string, { slug: string }> = {}
+  for (const slug of Object.keys(views)) out[slug] = { slug }
+  return out
+}
+
+/**
+ * Impl half — `ViewSchema[]` for `serialize` plus the per-slug `FunctionBinding`
+ * map the worker mounts routes from. `viewFor` markers are resolved here to
+ * concrete target paths (class meta-nodes) because the kernel-core serializer is
+ * pure and does not resolve `defineCore` endpoints.
+ */
+export function buildViewSchemas(
+  views: Record<string, AnyViewDef>,
+  url: string,
+  viewsFolder: string,
+  schema: Schema,
+): { schemas: ViewSchema[]; bindings: Record<string, FunctionBinding> } {
+  const schemas: ViewSchema[] = []
+  const bindings: Record<string, FunctionBinding> = {}
+  for (const [slug, def] of Object.entries(views)) {
+    assertExclusivity(slug, def)
+    // `mount` is a worker-relative SPA path → `<url><mount>`; otherwise the
+    // default/overridden `<url>/<viewsFolder>/<slug>`.
+    const binding = def.mount
+      ? { remoteUrl: joinWorkerPath(url, def.mount) }
+      : resolveBinding(def.binding, url, viewsFolder, slug)
+    bindings[slug] = binding
+    // Inline `render` views ship no shell client → default handshake 'none'.
+    const handshake = def.handshake ?? (def.render ? 'none' : undefined)
+    schemas.push({
+      ref: `view.${slug}`,
+      name: slug,
+      binding,
+      ...(handshake ? { handshake } : {}),
+      viewFor: resolveViewForTargets(def.viewFor, schema),
+    })
+  }
+  return { schemas, bindings }
+}
+
+/**
+ * Resolve `defineView`'s `viewFor` endpoints to concrete graph path raws.
+ * Mirrors kernel-core `compileCore`'s endpoint resolution (the old channel that
+ * carried view_for as core edges): `selfOf(Def)` → the def's class/interface
+ * meta-node `/<declaringDomain>/{class,interface}.<Name>/self`; a `CorePath`
+ * string → its anchored graph path. Empty when the view targets nothing.
+ */
+function resolveViewForTargets(
+  viewFor: EdgeEndpoint | readonly EdgeEndpoint[] | undefined,
+  schema: Schema,
+): string[] {
+  if (!viewFor) return []
+  const targets = Array.isArray(viewFor) ? viewFor : [viewFor]
+  if (targets.length === 0) return []
+
+  const descriptorMap = buildDefDescriptorMap(schema)
+  const defOrigins = buildDefOriginMap(schema, scanImportedDefs(schema))
+
+  return targets.map((target) => {
+    if (isSelfMarker(target)) {
+      const def = target.__def
+      const desc = descriptorMap.get(def)
+      if (!desc) {
+        throw new Error(
+          'defineView: `viewFor: selfOf(...)` references a def that is neither in this ' +
+            "schema nor any of its `imports`. Add the def's schema to `imports`.",
+        )
+      }
+      const origin = defOrigins.get(def) ?? schema.domain
+      const dp = DomainPaths.of(origin)
+      return isAbstract(def) ? dp.interface(desc.name).raw : dp.class(desc.name).raw
+    }
+    if (isCorePath(target)) {
+      return DomainPaths.of(schema.domain).corePath(target).raw
+    }
+    throw new Error(
+      'defineView: unsupported `viewFor` endpoint — use `selfOf(Class)` or a CorePath.',
+    )
+  })
+}

package/src/index.ts

@@ -19,7 +19,6 @@ export { remoteMethod, remoteClassMethods, remoteInterfaceMethods } from './meth
 // (preferred) use `domainWorkerEntry` from `@astrale-os/sdk/server`.
 export { defineDomain, deploy, defineAdapter } from './config'
 export type {
-  ClientBinding,
   DefineDomainConfig,
   DomainDefinition,
   DeployConfig,
@@ -75,7 +74,13 @@ export type {
 
 // ─── Auth ────────────────────────────────────────────────────────────────
 export type { RemoteIdentityConfig, AuthenticateResult } from './auth'
-export { authenticateRequest, buildComposedGrant, signCredential } from './auth'
+export {
+  authenticateRequest,
+  bindSelfKernel,
+  buildComposedGrant,
+  makeSelfKernel,
+  signCredential,
+} from './auth'
 export { AuthMissingError, AuthInvalidError } from './auth'
 export { assertPerm, requireOwnership, READ, EDIT, USE, SHARE, ALL } from './auth'
 export type {

package/src/server/auxiliary-routes.ts

@@ -143,7 +143,7 @@ export function mountAuxiliaryRoutes<TDeps>(config: AuxiliaryRoutesConfig<TDeps>
           if (!outValidation.ok) {
             throw new SdkResultValidationError(
               outValidation.issues as SdkResultValidationError['issues'],
-              def.ref,
+              `function.${slug}`,
             )
           }
           return c.json({ result: outValidation.data })

package/src/server/worker-entry.ts

@@ -154,9 +154,9 @@ export function clientOrigin(url: URL, request: Request): string {
 
 /**
  * Build a `before` hook that serves a static-asset `binding` (e.g. a Workers
- * Assets binding) mounted under `base` (default `/ui`) — the runtime half of a
- * domain's `client` binding. Returns `undefined` for non-matching paths (and
- * when no binding is present) so the request falls through to domain dispatch.
+ * Assets binding) mounted under `base` (default `/ui`) — the runtime half of an
+ * adapter env's client-asset config. Returns `undefined` for non-matching paths
+ * (and when no binding is present) so the request falls through to domain dispatch.
  *
  * Asset URLs are rooted at `base` (a client bundler sets `base: '<base>/'`);
  * this hook strips that prefix before delegating to the binding, so