@astrale-os/sdk 0.1.10 → 0.2.0

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

package/src/domain/extend-core.ts

@@ -1,301 +0,0 @@
-/**
- * Build an augmented `Core<S>` that includes auto-materialized View and
- * standalone-function nodes (one per entry in `defineRemoteDomain`'s `views` /
- * `remoteFunctions` config), plus their parent Folder + optional `view_for`
- * edges. Returns the resolved effective bindings alongside so callers don't
- * recompute them.
- *
- * Standalone callables (the former `RemoteFunction` class) are materialized as
- * the canonical kernel `Function` node class — "remote" is just a `binding`,
- * not a distinct kind, so there is no per-domain class to configure.
- *
- * Conflicts: if the user core already declares a top-level node at
- * `<viewsFolder>` or `<functionsFolder>`, throws — the auto-materialization
- * reserves those slugs.
- */
-
-import type { FunctionBinding } from '@astrale-os/kernel-api/routed'
-import type {
-  AnyEdgeDef,
-  AnyNodeDef,
-  Core,
-  CoreEdgeEntry,
-  CoreNodeEntry,
-  Schema,
-} from '@astrale-os/kernel-dsl'
-
-import { Folder, K, KernelSchema } from '@astrale-os/kernel-core'
-import { buildCorePath } from '@astrale-os/kernel-dsl'
-
-/** Canonical node class for standalone callables (the former `RemoteFunction`). */
-const FUNCTION_CLASS = KernelSchema.classes.Function as unknown as AnyNodeDef
-/** Canonical node class for GUI views. */
-const VIEW_CLASS = KernelSchema.classes.View as unknown as AnyNodeDef
-/** Canonical edge class linking a View to its target. */
-const VIEW_FOR_EDGE_CLASS = KernelSchema.classes.view_for as unknown as AnyEdgeDef
-
-import type { AnyRemoteFunctionDef } from '../define/remote-function'
-import type { ViewDef } from '../define/view'
-
-export const DEFAULT_VIEWS_FOLDER = 'views'
-export const DEFAULT_FUNCTIONS_FOLDER = 'functions'
-const SLUG_RE = /^[a-z][a-z0-9-]*$/
-
-export type ExtendCoreConfig = {
-  schema: Schema
-  origin: string
-  userCore?: Core
-  /**
-   * The worker's serving URL — the base every auto-materialized binding
-   * resolves against. OMITTED at define time (the URL is known only to the
-   * spec producers): the aux nodes then materialize structure-only (paths,
-   * names, refs — what identity/subs resolution needs) with no `binding`
-   * stamped and empty binding maps. Every install graph comes from a
-   * `materializeRemoteDomain(domain, url)` call where it is present.
-   */
-  url?: string
-
-  viewClass?: AnyNodeDef
-  viewForEdgeClass?: AnyEdgeDef
-  viewsFolder?: string
-  // oxlint-disable-next-line no-explicit-any
-  views?: Record<string, ViewDef<any>>
-
-  functionsFolder?: string
-  remoteFunctions?: Record<string, AnyRemoteFunctionDef>
-}
-
-export type ExtendCoreResult = {
-  core: Core
-  viewBindings: Record<string, FunctionBinding>
-  remoteFunctionBindings: Record<string, FunctionBinding>
-}
-
-export function extendCore(config: ExtendCoreConfig): ExtendCoreResult {
-  const {
-    schema,
-    origin,
-    userCore,
-    url,
-    viewClass = VIEW_CLASS,
-    viewForEdgeClass = VIEW_FOR_EDGE_CLASS,
-    viewsFolder = DEFAULT_VIEWS_FOLDER,
-    views,
-    functionsFolder = DEFAULT_FUNCTIONS_FOLDER,
-    remoteFunctions,
-  } = config
-
-  validateInputs(config)
-
-  const nodes: CoreNodeEntry[] = userCore ? [...userCore.__nodes] : []
-  const edges: CoreEdgeEntry[] = userCore ? [...userCore.__edges] : []
-  const viewBindings: Record<string, FunctionBinding> = {}
-  const remoteFunctionBindings: Record<string, FunctionBinding> = {}
-  const enableUiHandshake = viewClass === VIEW_CLASS
-
-  if (views && viewClass) {
-    // Enforce ViewDef's documented exclusivity: `mount` (SPA route) cannot be
-    // combined with `render` (inline HTML handler) or an explicit `binding` —
-    // silently ignoring one of them would deploy a view that behaves
-    // differently than its definition reads.
-    for (const [slug, def] of Object.entries(views)) {
-      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.`,
-        )
-      }
-    }
-    assertNoConflict(nodes, origin, viewsFolder)
-    addFolderAndEntries({
-      origin,
-      folderSlug: viewsFolder,
-      nodes,
-      entries: Object.entries(views).map(([slug, def]) => {
-        const binding = url
-          ? def.mount
-            ? { remoteUrl: joinWorkerPath(url, def.mount) }
-            : resolveBinding(def.binding, url, viewsFolder, slug)
-          : undefined
-        if (binding) viewBindings[slug] = binding
-        return {
-          slug,
-          nodeClass: viewClass,
-          data: buildViewData(slug, binding, def, enableUiHandshake),
-          edges: buildViewForEdges(slug, def, viewForEdgeClass, viewsFolder, origin),
-        }
-      }),
-      edges,
-    })
-  }
-
-  if (remoteFunctions) {
-    assertNoConflict(nodes, origin, functionsFolder)
-    addFolderAndEntries({
-      origin,
-      folderSlug: functionsFolder,
-      nodes,
-      entries: Object.entries(remoteFunctions).map(([slug, def]) => {
-        const binding = url ? resolveBinding(def.binding, url, functionsFolder, slug) : undefined
-        if (binding) remoteFunctionBindings[slug] = binding
-        return {
-          slug,
-          // Standalone callables materialize as the canonical kernel Function class.
-          nodeClass: FUNCTION_CLASS,
-          data: {
-            ...buildFunctionData(slug, binding),
-            [K.$.i('Function').ref.key]: def.ref ?? `function.${slug}`,
-          },
-          edges: [],
-        }
-      }),
-      edges,
-    })
-  }
-
-  return {
-    core: { schema, domain: origin, __nodes: nodes, __edges: edges },
-    viewBindings,
-    remoteFunctionBindings,
-  }
-}
-
-/** Join a worker-relative mount path onto the serving url (single slash). */
-function joinWorkerPath(url: string, mount: string): string {
-  const base = url.replace(/\/+$/, '')
-  return `${base}/${mount.replace(/^\/+/, '')}`
-}
-
-export function resolveBinding(
-  override: FunctionBinding | undefined,
-  url: string,
-  folderSlug: string,
-  slug: string,
-): FunctionBinding {
-  // Same trailing-slash discipline as `joinWorkerPath` — a `url` ending in `/`
-  // must not produce `//` in the binding (the kernel pins iss by exact string).
-  const base = url.replace(/\/+$/, '')
-  if (override) {
-    return {
-      ...override,
-      remoteUrl: override.remoteUrl ?? `${base}/${folderSlug}/${slug}`,
-    }
-  }
-  return { remoteUrl: `${base}/${folderSlug}/${slug}` }
-}
-
-// ── Internal ───────────────────────────────────────────────────────────────
-
-function validateInputs(config: ExtendCoreConfig): void {
-  if (config.views) {
-    for (const slug of Object.keys(config.views)) {
-      if (!SLUG_RE.test(slug)) {
-        throw new Error(`defineRemoteDomain: invalid view slug "${slug}" — must match ${SLUG_RE}.`)
-      }
-    }
-  }
-  if (config.remoteFunctions) {
-    for (const slug of Object.keys(config.remoteFunctions)) {
-      if (!SLUG_RE.test(slug)) {
-        throw new Error(
-          `defineRemoteDomain: invalid remote-function slug "${slug}" — must match ${SLUG_RE}.`,
-        )
-      }
-    }
-  }
-}
-
-function assertNoConflict(
-  nodes: readonly CoreNodeEntry[],
-  origin: string,
-  folderSlug: string,
-): void {
-  const folderPath = buildCorePath(origin, [folderSlug])
-  if (nodes.some((n) => n.path === folderPath)) {
-    throw new Error(
-      `defineRemoteDomain: top-level core slug "${folderSlug}" is reserved by ` +
-        'SDK auto-materialization. Move the conflicting node or rename the ' +
-        '`viewsFolder` / `functionsFolder` config.',
-    )
-  }
-}
-
-type EntryDescriptor = {
-  slug: string
-  nodeClass: AnyNodeDef
-  data: Record<string, unknown>
-  edges: CoreEdgeEntry[]
-}
-
-function addFolderAndEntries(args: {
-  origin: string
-  folderSlug: string
-  entries: EntryDescriptor[]
-  nodes: CoreNodeEntry[]
-  edges: CoreEdgeEntry[]
-}): void {
-  const { origin, folderSlug, entries, nodes, edges } = args
-
-  const folderPath = buildCorePath(origin, [folderSlug])
-  nodes.push({
-    path: folderPath,
-    def: Folder as unknown as AnyNodeDef,
-    data: { [K.Named.name.key]: folderSlug },
-  })
-
-  for (const entry of entries) {
-    nodes.push({
-      path: buildCorePath(origin, [folderSlug, entry.slug]),
-      def: entry.nodeClass,
-      data: entry.data,
-      parent: folderPath,
-    })
-    for (const e of entry.edges) edges.push(e)
-  }
-}
-
-function buildFunctionData(
-  slug: string,
-  binding: FunctionBinding | undefined,
-): Record<string, unknown> {
-  // Match the kernel-core schema serializer which JSON-stringifies the
-  // `Function.binding` value on Function nodes (see
-  // kernel/core/domain/serialize/schema.ts). The kernel install validator
-  // checks `typeof binding === 'string'` then parses; storing a raw object
-  // trips the validator with "missing remote binding" even when the object IS
-  // the binding. No binding at all (define-time, no url) → no prop stamped.
-  return {
-    [K.Named.name.key]: slug,
-    ...(binding ? { [K.$.i('Function').binding.key]: JSON.stringify(binding) } : {}),
-  }
-}
-
-function buildViewData(
-  slug: string,
-  binding: FunctionBinding | undefined,
-  def: ViewDef,
-  enableUiHandshake: boolean,
-): Record<string, unknown> {
-  const handshake = def.handshake ?? (def.render ? 'none' : undefined)
-  return {
-    ...buildFunctionData(slug, binding),
-    ...(enableUiHandshake && handshake ? { [K.UI.handshake.key]: handshake } : {}),
-  }
-}
-
-function buildViewForEdges(
-  slug: string,
-  def: ViewDef,
-  edgeClass: AnyEdgeDef | undefined,
-  viewsFolder: string,
-  origin: string,
-): CoreEdgeEntry[] {
-  if (!def.viewFor || !edgeClass) return []
-  const targets = Array.isArray(def.viewFor) ? def.viewFor : [def.viewFor]
-  const from = buildCorePath(origin, [viewsFolder, slug])
-  return targets.map((target) => ({
-    from,
-    edge: edgeClass,
-    to: target as CoreEdgeEntry['to'],
-  }))
-}