@astrale-os/sdk 0.4.19 → 0.5.0-beta.2

package/src/dispatch/resolve.ts

@@ -1,78 +0,0 @@
-/**
- * Method resolution — the index the dispatcher queries on every call.
- *
- * Owns both the index's construction and its lookup contract:
- * - `buildMethodIndex` is called once at server startup.
- * - `resolveMethod` is called once per inbound call.
- *
- * Each method is indexed under its `BoundMethod.ref`
- * (`namespace.Owner.method.name`) and under a short alias `Owner.name`.
- * The short alias is only registered when it is unambiguous — two methods
- * whose owners live in different namespaces (e.g. class vs interface) and
- * share the same local name would collide, and we refuse to register the
- * ambiguous key rather than silently overwriting.
- *
- * Inbound names may arrive as `Path`, full `ref`, short alias, a tree path
- * `/<domain>/<namespace.Owner>/<method>`, or the typed colon-form MethodPath
- * `/:<domain>:<namespace.Owner>:<method>` (what the kernel forwards when a
- * caller addresses the method in `:`-delimited form). All shapes normalize to
- * the same lookup key.
- */
-
-import type { Path } from '@astrale-os/kernel-core'
-import type { BoundMethod } from '@astrale-os/kernel-core/domain'
-
-import type { AnyRemoteHandler } from '../method/single.js'
-
-export type MethodIndex = Map<string, BoundMethod<AnyRemoteHandler>>
-
-const NAMESPACE_PREFIXES = ['class.', 'interface.'] as const
-const METHOD_INFIX = 'method'
-
-export function buildMethodIndex(methods: BoundMethod<AnyRemoteHandler>[]): MethodIndex {
-  const index: MethodIndex = new Map()
-  const shortFormAmbiguous = new Set<string>()
-
-  for (const m of methods) {
-    index.set(m.ref, m)
-
-    const shortForm = `${m.owner}.${m.method}`
-    if (shortFormAmbiguous.has(shortForm)) continue
-    const existing = index.get(shortForm)
-    if (existing && existing !== m) {
-      index.delete(shortForm)
-      shortFormAmbiguous.add(shortForm)
-      continue
-    }
-    index.set(shortForm, m)
-  }
-
-  return index
-}
-
-export function resolveMethod(
-  index: MethodIndex,
-  name: Path | string,
-): BoundMethod<AnyRemoteHandler> | null {
-  return index.get(normalizeMethod(name)) ?? null
-}
-
-function normalizeMethod(name: Path | string): string {
-  const raw = typeof name === 'string' ? name : name.raw
-  if (!raw.startsWith('/')) return raw
-  // Typed colon-form MethodPath (`/:<domain>:<owner>:<method>`) vs. tree
-  // slash-form (`/<domain>/<owner>/<method>`). The owner segment carries its own
-  // `.` (e.g. `interface.NoteOps`), so the path separator is unambiguous.
-  const separator = raw.startsWith('/:') ? ':' : '/'
-  const segments = raw
-    .replace(/^\/+/, '')
-    .split(separator)
-    .filter((s) => s.length > 0)
-  if (segments.length < 3) return raw
-  const owner = segments[segments.length - 2]!
-  const method = segments[segments.length - 1]!
-  if (NAMESPACE_PREFIXES.some((p) => owner.startsWith(p))) {
-    return `${owner}.${METHOD_INFIX}.${method}`
-  }
-  return `${owner}.${method}`
-}

package/src/dispatch/self.ts

@@ -1,198 +0,0 @@
-/**
- * Self resolution stays parse-only: `_self` becomes a Path/IdPath with no graph
- * read. The dispatcher later attaches lazy node()/call helpers once it has a kernel.
- */
-
-import type {
-  BindCtx,
-  BoundNode,
-  InstanceDispatch,
-  NodeBinder,
-  ProxyCaller,
-  TypeMethods,
-  TypeNames,
-} from '@astrale-os/kernel-client/schema'
-import type { Node } from '@astrale-os/kernel-core/graph'
-import type { Schema } from '@astrale-os/kernel-dsl'
-
-import {
-  createKnownInstanceDispatch,
-  defaultCaller,
-  extractMethodsByType,
-} from '@astrale-os/kernel-client/schema'
-import { IdPath, K, Path, type NodeId } from '@astrale-os/kernel-core'
-import { classPathSchema } from '@astrale-os/kernel-core/domain'
-import { absolutePathSchema } from '@astrale-os/kernel-core/tree'
-import { z } from 'zod'
-
-import type { Kernel } from '../method/context.js'
-
-/** The node a non-static method runs on — its full record, id guaranteed. */
-export type ResolvedSelfNode = Node & { id: NodeId }
-
-/** The bare parse of a self target — no kernel, no fetch. */
-export type ParsedSelf = {
-  path: Path
-  /** Set when `path` is an `IdPath` (i.e. `@<id>::method` calls). */
-  id?: NodeId
-}
-
-export type SelfResult = ParsedSelf & {
-  /**
-   * Lazy point-in-time self read. Memoized per dispatch; `{ reload: true }`
-   * forces a fresh `function.get`.
-   */
-  node(opts?: { reload?: boolean }): Promise<ResolvedSelfNode>
-}
-
-/** Schema-typed self: short-keyed props and typed same-instance call proxy. */
-export type TypedSelf<D, S extends Schema = Schema> = ParsedSelf & {
-  /**
-   * Fetch THIS node as a typed `BoundNode<D>`. Memoized exactly like
-   * {@link SelfResult.node} — one in-flight `function.get`, rejection-clearing,
-   * `{ reload: true }` refetches — so the zero-extra-graph-read dispatch
-   * invariant holds: nothing is read until called, then at most once.
-   */
-  node(opts?: { reload?: boolean }): Promise<BoundNode<D, S>>
-  /** Own instance methods — typed, address-only (`<selfPath>::method`), no read. */
-  readonly call: InstanceDispatch<D>
-}
-
-export function resolveSelf(ref: string): ParsedSelf {
-  const path = Path.parse(ref)
-  return path instanceof IdPath ? { path, id: path.id } : { path }
-}
-
-/** Attach memoized node(); unauthenticated contexts reject instead of reading. */
-export function withNode(parsed: ParsedSelf, kernel: Kernel | null): SelfResult {
-  let cached: Promise<ResolvedSelfNode> | undefined
-  const node = (opts?: { reload?: boolean }): Promise<ResolvedSelfNode> => {
-    if (opts?.reload) cached = undefined
-    if (!cached) {
-      cached = fetchSelfNode(parsed.path, kernel).catch((err: unknown) => {
-        cached = undefined // never cache a rejection — a later call may succeed
-        throw err
-      })
-    }
-    return cached
-  }
-  return { ...parsed, node }
-}
-
-const EMPTY_METHODS: TypeMethods = {
-  kind: 'class',
-  methods: new Set(),
-  staticMethods: new Set(),
-}
-const methodMapCache = new WeakMap<object, Map<string, TypeMethods>>()
-
-/** The type's method allow-list + kind, computed once per binder. */
-function methodsFor<S extends Schema>(binder: NodeBinder<S>, typeName: string): TypeMethods {
-  let map = methodMapCache.get(binder)
-  if (!map) {
-    map = extractMethodsByType(binder.schema)
-    methodMapCache.set(binder, map)
-  }
-  return map.get(typeName) ?? EMPTY_METHODS
-}
-
-function noKernelCaller(ref: string): ProxyCaller {
-  return () =>
-    Promise.reject(
-      new Error(
-        `self.call needs an authenticated kernel to dispatch on "${ref}", but this method ran ` +
-          `without one (its auth policy yields no kernel — e.g. 'public').`,
-      ),
-    )
-}
-
-/**
- * Schema-typed self helper: lazy BoundNode plus address-only call proxy. With no
- * kernel, both node() and call thunks fail loudly.
- */
-export function withBoundNode<S extends Schema>(
-  parsed: ParsedSelf,
-  kernel: Kernel | null,
-  binder: NodeBinder<S>,
-  typeName: string,
-): TypedSelf<unknown, S> {
-  const ctx: BindCtx = kernel
-    ? { caller: defaultCaller(kernel), read: kernel }
-    : { caller: null, read: null }
-
-  let cached: Promise<BoundNode<unknown, S>> | undefined
-  const node = (opts?: { reload?: boolean }): Promise<BoundNode<unknown, S>> => {
-    if (opts?.reload) cached = undefined
-    if (!cached) {
-      cached = fetchSelfNode(parsed.path, kernel)
-        .then(
-          (record) =>
-            binder.bind(typeName as TypeNames<S>, record, ctx, {
-              validate: 'warn',
-            }) as unknown as BoundNode<unknown, S>,
-        )
-        .catch((err: unknown) => {
-          cached = undefined // never cache a rejection — a later call may succeed
-          throw err
-        })
-    }
-    return cached
-  }
-
-  const info = methodsFor(binder, typeName)
-  const call = createKnownInstanceDispatch(
-    ctx.caller ?? noKernelCaller(parsed.path.raw),
-    parsed.path.raw,
-    info.methods,
-    info.kind === 'class' ? typeName : undefined,
-  ) as InstanceDispatch<unknown>
-
-  return { ...parsed, node, call }
-}
-
-/**
- * Boundary schema for a node record off the wire. Structurally identical to
- * kernel-core's `nodeSchema`, re-declared here from its public coercers
- * (`classPathSchema` from `/domain`, `absolutePathSchema` from `/tree`) on
- * purpose: importing the schema from `#graph` would pull zod into the graph
- * barrel and cycle with `AbsolutePath` init (see `kernel/core/graph/index.ts`).
- * Coercing through the canonical schemas yields a real `ClassPath` / `AbsolutePath`.
- */
-const nodeRecordSchema = z.object({
-  class: classPathSchema(),
-  path: absolutePathSchema(),
-  props: z.record(z.string(), z.unknown()),
-  id: z.string().optional(),
-  __labels: z.array(z.string()).optional(),
-})
-
-async function fetchSelfNode(path: Path, kernel: Kernel | null): Promise<ResolvedSelfNode> {
-  if (!kernel) {
-    throw new Error(
-      `self.node() needs an authenticated kernel to read "${path.raw}", but this method ran ` +
-        `without one (its auth policy yields no kernel — e.g. 'public'). Read the node from a ` +
-        `method whose auth is 'required', or supply a credential.`,
-    )
-  }
-  // function.get soft-masks missing/unreadable roots; empty page means no self node.
-  const result = (await kernel.call(K.$.f('get').path.domain.raw, {
-    roots: [path.raw],
-    depth: 0,
-  })) as {
-    nodes?: unknown[]
-  }
-  const first = result?.nodes?.[0]
-  if (first === undefined) {
-    throw new Error(
-      `self.node(): "${path.raw}" was not found or is not visible to the caller ` +
-        `(function.get returned no node).`,
-    )
-  }
-  const record = nodeRecordSchema.parse(first)
-  if (record.id === undefined) {
-    throw new Error(`self.node(): "${path.raw}" returned a record with no id`)
-  }
-  // Validated at the wire boundary: id is now known-present, props are
-  // structurally checked. Bridge the parse output to the canonical `Node`.
-  return { ...record, id: record.id as NodeId } as ResolvedSelfNode
-}

package/src/dispatch/validate.ts

@@ -1,41 +0,0 @@
-/**
- * Param / result validation helpers — Zod `safeParse` wrappers returning a
- * tagged result. Callers convert a `false` outcome into a typed error:
- * `SdkValidationError` (input, → 422) or `SdkResultValidationError`
- * (output, → 500).
- */
-
-import type { z } from 'zod'
-
-export type ValidationResult =
-  | { ok: true; data: Record<string, unknown> }
-  | { ok: false; issues: unknown[] }
-
-export function validateParams(inputSchema: z.ZodType, params: unknown): ValidationResult {
-  const result = inputSchema.safeParse(params)
-  if (result.success) {
-    return { ok: true, data: result.data as Record<string, unknown> }
-  }
-  return { ok: false, issues: result.error.issues }
-}
-
-/**
- * Result of validating a handler's output against its `outputSchema`. Unlike
- * params, an output may be any shape (object, primitive, array), so `data` is
- * `unknown` rather than `Record<string, unknown>`.
- */
-export type ResultValidationResult = { ok: true; data: unknown } | { ok: false; issues: unknown[] }
-
-/**
- * Validate a handler's return value against its `outputSchema`. Mirrors the
- * kernel's `validateOutput` (`runtime/.../validation/output.ts`) so deployed
- * domains enforce the same output contract as in-process methods. Returns the
- * parsed `data` (applies Zod `default`/`transform`/coercions) on success.
- */
-export function validateResult(outputSchema: z.ZodType, result: unknown): ResultValidationResult {
-  const parsed = outputSchema.safeParse(result)
-  if (parsed.success) {
-    return { ok: true, data: parsed.data }
-  }
-  return { ok: false, issues: parsed.error.issues }
-}

package/src/domain/binding.ts

@@ -1,37 +0,0 @@
-/**
- * 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

@@ -1,156 +0,0 @@
-/**
- * SDK-side spec builder: CompiledDomain → serialize → Graph.
- *
- * Serializes BoundMethod[] into FunctionSchema[], generates entries for
- * inherited methods not covered by the domain's handlers, then delegates
- * to serialize() for graph blueprint generation.
- *
- * Domain-side Methods are remote-bound: dispatch routes through
- * `binding.remoteUrl` and never reaches the kernel sandbox. We therefore
- * do NOT stamp `code` on emitted FunctionSchema entries — there is no
- * sandbox-eval'able body. Only the kernel domain (compiled in-process)
- * carries `code` strings.
- *
- * The emitted graph is absolute — the Tree produced by `serialize()` is
- * already mounted at `/<origin>`, so `tree.toGraph()` lifts every internal
- * relative path into its host-graph absolute form. Wire serialization is the
- * caller's responsibility (`graph.toWire()`).
- */
-
-import type { Graph, WireGraph } from '@astrale-os/kernel-core'
-import type { BoundMethod, FunctionSchema, ViewSchema } from '@astrale-os/kernel-core/domain'
-import type { Schema } from '@astrale-os/kernel-dsl'
-
-import { AbsolutePath } from '@astrale-os/kernel-core'
-import { hashInstallGraph, serialize, zodToJsonSchema } from '@astrale-os/kernel-core/domain'
-
-import type { AnyRemoteHandler } from '../method/single.js'
-import type { RemoteDomain } from './define.js'
-
-import { extractBinding } from './contract.js'
-import { materializeRemoteDomain } from './define.js'
-
-/**
- * Build the install-ready wire graph for a domain served at `url`: materialize
- * the domain at its real serving URL (so every binding carries the live URL —
- * the define-time compile carries none), serialize, and emit the wire form.
- * This is the graph the kernel installs and re-hashes to verify. There is no
- * url-less variant: an install graph without bindings is uninstallable (the
- * kernel install guard rejects it).
- */
-export function buildInstallGraph<S extends Schema>(
-  domain: RemoteDomain<S>,
-  url: string,
-): WireGraph {
-  const { compiled, auxiliary } = materializeRemoteDomain(domain, url)
-  // Two-axis placement: `parent` = the folder the Domain node physically lives
-  // under. `path` names the FULL node path (basename === origin);
-  // unset defaults to /domains/<origin> — the "/domains" placement policy lives
-  // HERE (the kernel default is Root → /<origin>). `mount` is deliberately NOT
-  // passed: installed_in + typed addresses stay root-mounted (kernel default).
-  const parent = domain.path
-    ? AbsolutePath.parse(domain.path).parent()
-    : AbsolutePath.from('domains')
-  return buildSpecInternal(
-    compiled,
-    domain.methods,
-    url,
-    auxiliary?.functionSchemas ?? [],
-    auxiliary?.viewSchemas ?? [],
-    parent,
-  ).toWire() as WireGraph
-}
-
-/**
- * Content hash of the install graph. Delegates the canonical hash to kernel-core's
- * `hashInstallGraph` — the same algorithm the kernel re-runs on install to verify
- * the received graph against the signed hash.
- */
-export function buildInstallGraphHash<S extends Schema>(
-  domain: RemoteDomain<S>,
-  url: string,
-): Promise<string> {
-  return hashInstallGraph(buildInstallGraph(domain, url))
-}
-
-// ── Internal ────────────────────────────────────────────────
-
-function buildSpecInternal(
-  compiled: RemoteDomain['compiled'],
-  methods: BoundMethod<AnyRemoteHandler>[],
-  url: string,
-  functionSchemas: FunctionSchema[],
-  viewSchemas: ViewSchema[],
-  parent: AbsolutePath,
-): Graph {
-  const serialized = serializeMethodsWithStubs(compiled, methods, url)
-  // 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,
-    parent,
-    // An install graph is the domain's signed desired state. Reinstalling it
-    // must converge schema and core material exactly, including removing
-    // properties that disappeared from a newer domain version.
-    onConflict: 'replace',
-  })
-  return tree.toGraph()
-}
-
-/**
- * Serialize BoundMethod[] and generate stubs for methods in compiled.$.methods
- * that have no corresponding BoundMethod (inherited-sealed, inherited-default).
- *
- * Every Method's binding defaults its `remoteUrl` to the serving URL: domain
- * methods are remote-bound — the kernel dispatches them by redirecting to the
- * worker — so a method node without a remote binding is uninstallable (the
- * kernel install guard rejects it). An explicit per-method `remoteUrl` wins.
- */
-function serializeMethodsWithStubs(
-  compiled: RemoteDomain['compiled'],
-  methods: BoundMethod<AnyRemoteHandler>[],
-  url: string,
-): FunctionSchema[] {
-  const bound = new Set(methods.map((m) => m.ref))
-  const result = methods.map((m) => serializeFromBoundMethod(m, url))
-
-  // Generate entries for unbound methods (replaces fillMissingCallables).
-  // No `code` is stamped — domain-side Methods are binding-only. The `ref` MUST
-  // be the QUALIFIED `ResolvedMethod.ref` (`<ns>.<Type>.method.<m>`) — the exact
-  // form `serialize`'s method-node lookup uses; re-deriving a bare `Type.method`
-  // is the F11 bug (interface methods then never resolve → MISSING_HANDLER).
-  for (const classMethods of Object.values(compiled.$.methods)) {
-    for (const rm of Object.values(classMethods)) {
-      const ref = rm.ref
-      if (bound.has(ref)) continue
-      result.push({
-        ref,
-        inputSchema: { type: 'object' },
-        outputSchema: {},
-        output: 'value',
-        binding: { remoteUrl: url },
-      })
-    }
-  }
-
-  return result
-}
-
-function serializeFromBoundMethod(
-  method: BoundMethod<AnyRemoteHandler>,
-  url: string,
-): FunctionSchema {
-  const binding = extractBinding(method.handler)
-  return {
-    ref: method.ref,
-    inputSchema: zodToJsonSchema(method.inputSchema),
-    outputSchema: zodToJsonSchema(method.outputSchema),
-    isStatic: method.isStatic || undefined,
-    output: method.output,
-    binding: binding?.remoteUrl ? binding : { ...binding, remoteUrl: url },
-  }
-}

package/src/domain/contract.ts

@@ -1,41 +0,0 @@
-/**
- * BoundMethod → MountableContract translator.
- *
- * The narrow view carries only what the server's mount planner reads —
- * `ref` plus optional `binding` — because the SDK's SdkDispatcher
- * handles dispatch via KernelAPI.call, not via runtime contract hooks.
- */
-
-import type {
-  AuthPolicy,
-  FunctionBinding,
-  MountableContract,
-  RouteBinding,
-} from '@astrale-os/kernel-api/routed'
-import type { BoundMethod } from '@astrale-os/kernel-core/domain'
-
-import type { AnyRemoteHandler } from '../method/single.js'
-
-export function toSdkContract(method: BoundMethod<AnyRemoteHandler>): MountableContract {
-  const handler = method.handler as {
-    route?: RouteBinding
-    remoteUrl?: string
-    auth?: AuthPolicy
-  }
-  const binding = extractBinding(handler)
-  return binding === undefined ? { ref: method.ref } : { ref: method.ref, binding }
-}
-
-export function extractBinding(handler: {
-  route?: RouteBinding
-  remoteUrl?: string
-  auth?: AuthPolicy
-}): FunctionBinding | undefined {
-  const { route, remoteUrl, auth } = handler
-  if (route === undefined && remoteUrl === undefined && auth === undefined) return undefined
-  const binding: FunctionBinding = {}
-  if (remoteUrl !== undefined) binding.remoteUrl = remoteUrl
-  if (route !== undefined) binding.route = route
-  if (auth !== undefined) binding.auth = auth
-  return binding
-}