@astrale-os/sdk 0.1.5 → 0.1.7

package/src/cli/spec.ts

@@ -0,0 +1,42 @@
+/**
+ * Build a diagnostic spec (wire graph + schema hash) from the project's
+ * `defineDomain` definition. This mirrors what the codegen'd worker assembles —
+ * but only for inspection / `/meta` provenance. The live install bundle is
+ * always produced by the worker at request time, so a failure here is non-fatal
+ * for dev/deploy (the CLI logs and continues) and fatal only for
+ * `astrale-domain build`, where the spec IS the product.
+ *
+ * The modules (`schema` / `methods` / `views` / `functions`) come straight off
+ * the definition — the SAME values the author wired into `defineDomain`, which
+ * the adapter codegen also assembles. One source, no second filesystem probe to
+ * drift from it.
+ */
+
+import type { Schema } from '@astrale-os/kernel-dsl'
+
+import { hashInstallGraph } from '@astrale-os/kernel-core/domain'
+
+import type { DomainDefinition } from '../config/define-domain'
+import type { RemoteDomainConfig } from '../domain'
+
+import { buildInstallGraph, defineRemoteDomain } from '../domain'
+
+export async function buildProjectSpec(
+  def: DomainDefinition,
+  url: string,
+): Promise<{ wire: Record<string, unknown>; schemaHash: string }> {
+  // The definition's module values are untyped against `RemoteDomainConfig` by
+  // nature (deps/schema generics erased on `DomainDefinition`); funnel them
+  // through ONE cast into the config shape `defineRemoteDomain` validates.
+  const config = {
+    schema: def.schema,
+    methods: def.methods,
+    ...(def.views ? { views: def.views } : {}),
+    ...(def.functions ? { remoteFunctions: def.functions } : {}),
+  } as RemoteDomainConfig<Schema, unknown>
+
+  const domain = defineRemoteDomain<unknown>()(config)
+  const wire = buildInstallGraph(domain, url)
+  const schemaHash = await hashInstallGraph(wire)
+  return { wire: wire as unknown as Record<string, unknown>, schemaHash }
+}

package/src/config/adapter.ts

@@ -0,0 +1,172 @@
+/**
+ * The deployment-adapter contract.
+ *
+ * A deployment target = one npm package implementing `DomainAdapter<Params>`.
+ * The adapter is GENERIC over its own `Params` so envs AND provider settings
+ * stay 100% adapter-specific (a Cloudflare adapter's `{ route, secrets }` is
+ * nothing like a Node adapter's `{ port }`). The CLI resolves
+ * `envs[<env>] → Params` via `adapter.params(env)` and then drives the adapter
+ * with the resolved params — install of the resulting URL and the `requires`
+ * check are generic and live in the CLI, never in the adapter.
+ *
+ * The central guarantee: `watch()` and `deploy()` both return a `url` — that's
+ * what the CLI prints, what `astrale domain install <url>` consumes, and
+ * the worker's `iss` identity. The URL is an OUTPUT of watch/deploy; nothing
+ * in the contract asks an adapter to predict it ahead of time.
+ */
+
+/**
+ * Generic, target-independent domain metadata the CLI hands every adapter so
+ * it can codegen the worker entry. (Extends the bare `WatchCtx`/`DeployCtx` of
+ * the spec with the fields a real codegen needs.)
+ */
+export interface DomainInfo {
+  /**
+   * The domain's addressing name — the graph slug it mounts under (e.g.
+   * `'crm.acme.dev'`). NOT the cryptographic identity: the JWT `iss` is the
+   * worker's serving URL, pinned by the kernel at install time.
+   */
+  origin: string
+  /** Cross-domain deps by origin — verified at install (CLI/kernel), not here. */
+  requires: readonly string[]
+  /** Optional Astrale Path called by the kernel after install (as __SYSTEM__). */
+  postInstall?: string
+  /**
+   * Whether the domain declares any Views / standalone Functions / a client SPA
+   * — read from the `defineDomain` definition, NOT probed from the filesystem.
+   * The adapter codegen imports the corresponding module / mounts the SPA hook
+   * only when true. `hasClient` governs the WORKER's `/ui` hook specifically
+   * (present whenever the domain has a client, even on managed deploys that ship
+   * the built assets separately and pass no `clientDir`); the wrangler
+   * `assets.directory` binding tracks `clientDir` instead.
+   */
+  hasViews: boolean
+  hasFunctions: boolean
+  hasClient: boolean
+  /**
+   * Whether the domain declares a `deps` mapper (`defineDomain({ deps })`).
+   * When true the adapter codegen imports it from the domain's fixed `deps`
+   * module and passes it to the worker entry; when false the worker passes the
+   * raw env straight through as `ctx.deps`. Read from the definition, never
+   * probed from the filesystem.
+   */
+  hasDeps: boolean
+}
+
+export interface WatchCtx {
+  /** Absolute path to the domain project root. */
+  projectDir: string
+  /** Absolute path where the CLI writes the diagnostic `spec.json`. */
+  specPath: string
+  /** Absolute path to the client SPA dir, when the domain declares a `client`. */
+  clientDir?: string
+  /** Flat secret map loaded from the env's `secrets` file — injected locally in dev. */
+  secrets: Record<string, string>
+  /** Domain metadata for codegen. */
+  domain: DomainInfo
+  /** The env key being watched (e.g. 'dev'). */
+  env: string
+  /** Invoked by the adapter on every hot-reload so the CLI can re-log. */
+  onReload(): void
+}
+
+export interface DeployCtx {
+  projectDir: string
+  specPath: string
+  /** Flat secret map loaded from the env's `secrets` file (gitignored). */
+  secrets: Record<string, string>
+  clientDir?: string
+  domain: DomainInfo
+  /** The env key being deployed (e.g. 'dev' | 'prod' | 'canary'). */
+  env: string
+}
+
+/** A running local watch — exposes its URL and a stop handle. */
+export interface WatchHandle {
+  /** Local URL the worker is reachable at (e.g. http://localhost:8787). */
+  url: string
+  stop(): Promise<void>
+}
+
+/** A completed deploy — the authoritative public URL. */
+export interface DeployResult {
+  url: string
+  /**
+   * Adapter-specific next-steps block printed INSTEAD of the CLI's default
+   * "install on an instance" footer — managed deploys already installed the
+   * domain, so the default hint is wrong there. Pre-indented plain lines.
+   */
+  nextSteps?: string
+}
+
+export interface DomainAdapter<Params> {
+  /** 'astrale-host' | 'cloudflare' | 'node' | … */
+  name: string
+
+  /** Resolve an env key to this adapter's typed params. Throws on unknown key. */
+  params(env: string): Params
+
+  /** Local + hot-reload (watch) → controllable handle. Orthogonal to env. */
+  watch(params: Params, ctx: WatchCtx): Promise<WatchHandle>
+
+  /**
+   * Optional: re-run codegen for an ALREADY-RUNNING `watch` after
+   * `astrale.config.ts` changed — same shape as `watch` but it must NOT spawn
+   * anything: it only rewrites the generated files, and the running dev server
+   * (which watches them, e.g. `wrangler dev` on its `--config`) picks them up.
+   * Adapters without it fall back to "restart to apply config changes".
+   */
+  regenerate?(params: Params, ctx: WatchCtx): Promise<void>
+
+  /** Build + bundle + ship (the adapter owns ITS build) → authoritative URL. */
+  deploy(params: Params, ctx: DeployCtx): Promise<DeployResult>
+
+  /**
+   * Optional: the path (relative to the project root) of the gitignored secrets
+   * file for these params. The CLI loads it and passes the parsed map as
+   * `ctx.secrets` — keeping secret-file loading generic while the path stays
+   * provider-typed. Return `undefined` for "no secrets file".
+   */
+  secretsFile?(params: Params): string | undefined
+}
+
+/**
+ * Spec passed to `defineAdapter` — identical to `DomainAdapter` minus the
+ * `params(env)` resolver, which the helper attaches from `envs`. Custom adapter
+ * authors use this so they never re-implement env→params resolution.
+ */
+export interface AdapterSpec<Params> {
+  name: string
+  /** The provider-typed env map (`{ dev: {...}, prod: {...}, … }`). */
+  envs: Record<string, Params>
+  watch(params: Params, ctx: WatchCtx): Promise<WatchHandle>
+  regenerate?(params: Params, ctx: WatchCtx): Promise<void>
+  deploy(params: Params, ctx: DeployCtx): Promise<DeployResult>
+  secretsFile?(params: Params): string | undefined
+}
+
+/**
+ * Build a `DomainAdapter` from a spec + an env map, attaching a `params(env)`
+ * resolver that throws a clear error on an unknown key (listing the valid ones).
+ */
+export function defineAdapter<Params>(spec: AdapterSpec<Params>): DomainAdapter<Params> {
+  const keys = Object.keys(spec.envs)
+  return {
+    name: spec.name,
+    params(env: string): Params {
+      const params = spec.envs[env]
+      if (params === undefined) {
+        const known = keys.length ? keys.join(', ') : '(none)'
+        throw new Error(
+          `Adapter "${spec.name}": unknown env "${env}". Known envs: ${known}. ` +
+            `Add it to the adapter's env map in astrale.config.ts.`,
+        )
+      }
+      return params
+    },
+    watch: spec.watch,
+    deploy: spec.deploy,
+    ...(spec.regenerate ? { regenerate: spec.regenerate } : {}),
+    ...(spec.secretsFile ? { secretsFile: spec.secretsFile } : {}),
+  }
+}

package/src/config/define-domain.ts

@@ -0,0 +1,218 @@
+/**
+ * `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
+ * 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
+ * imports directly, then attaches the adapter separately with `deploy(domain,
+ * adapter)` in `astrale.config.ts` (see `./deploy`).
+ *
+ * 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.
+ */
+
+import type { Schema } from '@astrale-os/kernel-dsl'
+
+import { DomainOrigin, extractDomainSlug } from '@astrale-os/kernel-core/domain'
+
+import type { RemoteFunctionDef, ViewDef } from '../define'
+import type { SchemaMethodsImpl } from '../method'
+
+// A registry holds views / functions of every deps + param/result shape. Their
+// per-entry typing is enforced at the `defineView` / `defineRemoteFunction` call
+// 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
+type AnyViewDef = ViewDef<any>
+type AnyFunctionDef = RemoteFunctionDef<any, any, any>
+// oxlint-enable no-explicit-any
+
+/**
+ * The domain's client SPA binding. Its presence is the whole signal — there is
+ * no `existsSync('client/')` probe. `dir` is the project-relative source folder
+ * (e.g. `'client'`); the worker serves its built SPA under `/ui` via its Assets
+ * binding. Always written out explicitly (`client: { dir: 'client' }`) — there
+ * is no boolean shorthand, so the source folder is never implicit.
+ */
+export type ClientBinding = { dir: string }
+
+export interface DefineDomainConfig<S extends Schema, TDeps, TEnv = unknown> {
+  /** The domain schema (from `schema/`). Its `.domain` seeds the default origin. */
+  schema: S
+  /**
+   * The domain's method implementations (from `methods/`), one per schema
+   * method. Typed against `schema` — an unimplemented or misnamed method is a
+   * compile error here.
+   */
+  methods: SchemaMethodsImpl<S, TDeps>
+  /**
+   * Map the worker `env` to the handler dependency container (`ctx.deps`).
+   * Run ONCE per cold isolate per serving URL (the built app is cached), NOT
+   * per request — so it's the place to construct ports/clients once instead of
+   * re-deriving them in every handler. Its return type IS `TDeps`: type it the
+   * shape your `methods` read (e.g. `(env) => ({ platform: buildPlatform(env) })`)
+   * and the methods get the rich container, not raw env. The same value reaches
+   * view/function handlers and the `install.authorize` hook.
+   *
+   * Omit for the common case: `env` is passed straight through (`TDeps = TEnv`),
+   * so existing domains are unaffected. The function itself is imported by the
+   * generated worker from a fixed `deps` module, mirroring `methods` — wire it
+   * here so the type check binds `env → TDeps` and the adapter knows to emit it.
+   */
+  deps?: (env: TEnv, url: string) => TDeps
+  /**
+   * The domain's Views (iframe-mountable UIs), keyed by slug. Omit when the
+   * domain has none. Each becomes a `View` node + a worker route.
+   */
+  views?: Record<string, AnyViewDef>
+  /**
+   * The domain's standalone Functions (callables not bound to a class), keyed
+   * by slug. Omit when the domain has none.
+   */
+  functions?: Record<string, AnyFunctionDef>
+  /**
+   * The domain's client SPA, e.g. `{ dir: 'client' }`. Its presence enables it
+   * (no folder probing); `dir` is the project-relative source folder, built and
+   * served under `/ui`. Omit for a domain with no SPA.
+   */
+  client?: ClientBinding
+  /**
+   * The domain's **addressing name** (the graph slug it mounts under, e.g.
+   * `'crm.acme.dev'`). Defaults to `schema.domain`. Must be a name, never a
+   * URL. This is **NOT** the cryptographic identity: the `iss` is the worker's
+   * **serving URL**, pinned by the kernel to the URL it fetched the domain at
+   * during install (and verified against that URL's JWKS). `origin` is a free
+   * addressing label, only required to be unique in the graph.
+   */
+  origin?: string
+  /** 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.
+   */
+  postInstall?: string
+}
+
+export interface DomainDefinition {
+  schema: Schema
+  // oxlint-disable-next-line no-explicit-any -- erased at the consumption casts in spec/codegen
+  methods: SchemaMethodsImpl<Schema, any>
+  /**
+   * env → deps mapper, when the author supplied one. Held loosely (the worker
+   * imports the real function from its own `deps` module); the CLI reads only
+   * its PRESENCE to set `DomainInfo.hasDeps`, the codegen signal.
+   */
+  // oxlint-disable-next-line no-explicit-any -- presence is what the CLI consumes; the typed binding lives at the call site
+  deps?: (env: any, url: string) => any
+  views?: Record<string, ViewDef>
+  functions?: Record<string, AnyFunctionDef>
+  /** Normalized client binding (resolved `dir`), or absent when the domain has no SPA. */
+  client?: { dir: string }
+  origin: string
+  requires: readonly string[]
+  postInstall?: string
+}
+
+export function defineDomain<S extends Schema, TDeps, TEnv = unknown>(
+  config: DefineDomainConfig<S, TDeps, TEnv>,
+): DomainDefinition {
+  const rawOrigin = config.origin ?? schemaDomain(config.schema)
+  if (!rawOrigin) {
+    throw new Error(
+      'defineDomain: could not resolve `origin`. Set it explicitly or give the ' +
+        'schema a base domain (`defineSchema("crm.acme.dev", …)`).',
+    )
+  }
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(rawOrigin)) {
+    throw new Error(
+      `defineDomain: \`origin\` must be a stable name (e.g. "crm.acme.dev"), not a URL — got "${rawOrigin}". ` +
+        'The deployment URL is an output of deploy, not the identity.',
+    )
+  }
+  // Canonicalize + validate the origin exactly as the kernel does (lowercased,
+  // FQDN-like, matches DOMAIN_ORIGIN_RE). Failing HERE gives a clear authoring-
+  // time error instead of a cryptic failure deep in codegen / install, and makes
+  // `origin` the same lowercased form the kernel stores graph nodes under.
+  let origin: string
+  try {
+    origin = DomainOrigin(rawOrigin)
+  } catch {
+    throw new Error(
+      `defineDomain: invalid \`origin\` "${rawOrigin}". Use a lowercase FQDN-like slug ` +
+        '(letters, digits, ".", "_", "-"), e.g. "crm.acme.dev".',
+    )
+  }
+
+  // `requires` entries are domain origins — validate them with the same rule as
+  // `origin` so a URL or mixed-case entry fails at authoring time, not install.
+  const requires = (config.requires ?? []).map((dep) => {
+    try {
+      return DomainOrigin(dep)
+    } 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.',
+      )
+    }
+  })
+
+  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 } : {}),
+    origin,
+    requires,
+    ...(config.postInstall
+      ? { postInstall: normalizePostInstall(config.postInstall, origin) }
+      : {}),
+  }
+}
+
+/**
+ * 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).
+ */
+function normalizePostInstall(postInstall: string, origin: string): string {
+  const slug = extractDomainSlug(postInstall)
+  if (slug === null) {
+    throw new Error(
+      `defineDomain: \`postInstall\` must be a typed colon-path under "/:${origin}" ` +
+        `(e.g. "/:${origin}:class.Note:seed" or "/:${origin}:interface.Ops:seed"); ` +
+        `absolute tree paths are not accepted — got "${postInstall}".`,
+    )
+  }
+  if (slug.toLowerCase() !== origin) {
+    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.`,
+    )
+  }
+  // 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)}`
+}
+
+function schemaDomain(schema: Schema): string | undefined {
+  const value = (schema as unknown as { domain?: unknown }).domain
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}

package/src/config/deploy.ts

@@ -0,0 +1,35 @@
+/**
+ * `deploy` — bind a worker-safe `DomainDefinition` to a deployment adapter,
+ * producing the value `astrale.config.ts` default-exports for the CLI.
+ *
+ * The split exists to keep the worker bundle clean: `defineDomain` (in the
+ * author's `domain.ts`) carries only worker-safe modules and is what the
+ * generated worker imports; the adapter (`cloudflare(...)` / `astrale(...)`) is
+ * node-only code that the worker must never pull in. `deploy(domain, adapter)`
+ * 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 })
+ *
+ *   import { domain } from './domain'
+ *   export default deploy(domain, cloudflare({ dev, prod }))
+ *
+ * The returned shape is just the definition with `adapter` attached — exactly
+ * what the CLI already reads (`def.adapter`, `def.origin`, `def.schema`, …), so
+ * the loader is unchanged.
+ */
+
+import type { DomainAdapter } from './adapter'
+import type { DomainDefinition } from './define-domain'
+
+/** A domain definition bound to its deployment adapter — the CLI's input. */
+export interface DeployConfig<Params = unknown> extends DomainDefinition {
+  adapter: DomainAdapter<Params>
+}
+
+export function deploy<Params>(
+  domain: DomainDefinition,
+  adapter: DomainAdapter<Params>,
+): DeployConfig<Params> {
+  return { ...domain, adapter }
+}

package/src/config/index.ts

@@ -0,0 +1,31 @@
+/**
+ * `@astrale-os/sdk` config surface — the author-facing declaration of a
+ * standalone domain (`astrale.config.ts`) and the deployment-adapter contract.
+ *
+ *   import { defineDomain, deploy } from '@astrale-os/sdk'
+ *   import { cloudflare } from '@astrale-os/adapter-cloudflare'
+ *
+ * `defineDomain` (in `domain.ts`) declares the WORKER-SAFE domain — what it is +
+ * its identity, no adapter. `deploy(domain, adapter)` (in `astrale.config.ts`)
+ * binds it to a deployment target; the `astrale-domain` bin (folded into this
+ * package — see `../cli`) reads that default export and drives the adapter.
+ * Neither builds a server nor boots a kernel — they validate and package the
+ * declaration.
+ */
+
+export { defineDomain } from './define-domain'
+export type { ClientBinding, DefineDomainConfig, DomainDefinition } from './define-domain'
+
+export { deploy } from './deploy'
+export type { DeployConfig } from './deploy'
+
+export { defineAdapter } from './adapter'
+export type {
+  AdapterSpec,
+  DeployCtx,
+  DeployResult,
+  DomainAdapter,
+  DomainInfo,
+  WatchCtx,
+  WatchHandle,
+} from './adapter'

package/src/define/remote-function.ts

@@ -24,8 +24,13 @@ import type { Context } from 'hono'
 import type { z } from 'zod'
 
 import type { CallRemoteFn } from '../dispatch/call-remote'
+import type { KernelForAuth } from '../method/context'
 
-export type RemoteFunctionContext<TParams, TDeps = unknown> = {
+export type RemoteFunctionContext<
+  TParams,
+  TDeps = unknown,
+  TKernel = BoundClientSessionView<FnMap> | null,
+> = {
   /** Validated params (Zod-checked against `inputSchema`). */
   params: TParams
   /** Hono request context — escape hatch for headers, raw body, etc. */
@@ -37,10 +42,12 @@ export type RemoteFunctionContext<TParams, TDeps = unknown> = {
   /**
    * `BoundClientSessionView` to the parent kernel, bound to the composed
    * credential `union(delegation, self)` — same shape as `RemoteContext.kernel`
-   * for `remoteMethod`. `null` when `auth: 'public'`, or `auth: 'optional'`
-   * with no inbound credential.
+   * for `remoteMethod`. 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: BoundClientSessionView<FnMap> | null
+  kernel: TKernel
   /**
    * Call another worker's remote method, re-minting the credential for the
    * target's audience. Same contract as {@link RemoteContext.callRemote}: throws
@@ -60,7 +67,12 @@ export type RemoteFunctionContext<TParams, TDeps = unknown> = {
   selfKernel: (kernelUrl?: string) => Promise<BoundClientSessionView<FnMap>>
 }
 
-export type RemoteFunctionDef<TParams = unknown, TResult = unknown, TDeps = unknown> = {
+export type RemoteFunctionDef<
+  TParams = unknown,
+  TResult = unknown,
+  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
@@ -82,25 +94,42 @@ export type RemoteFunctionDef<TParams = unknown, TResult = unknown, TDeps = unkn
    * placeholders both supported.
    */
   binding?: FunctionBinding
-  /** Authentication policy. Defaults to `'required'`. */
-  auth?: AuthPolicy
+  /**
+   * Authentication policy. Defaults to `'required'`. Captured as a literal type
+   * so it drives {@link KernelForAuth} on the `execute`/`authorize` context:
+   * omit it (or `'required'`) → `ctx.kernel` non-null; `'optional'` → `… | null`;
+   * `'public'` → `null` (webhooks reach the graph via `ctx.selfKernel`).
+   */
+  auth?: TAuth
   /** Optional pre-execute authorization. Throw to deny. */
-  authorize?: (ctx: RemoteFunctionContext<TParams, TDeps>) => void | Promise<void>
+  authorize?: (
+    ctx: RemoteFunctionContext<TParams, TDeps, KernelForAuth<TAuth>>,
+  ) => void | Promise<void>
   /** The function body. May be async. */
-  execute: (ctx: RemoteFunctionContext<TParams, TDeps>) => TResult | Promise<TResult>
+  execute: (
+    ctx: RemoteFunctionContext<TParams, TDeps, KernelForAuth<TAuth>>,
+  ) => TResult | Promise<TResult>
   /** Optional human-readable description. */
   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>
+export type AnyRemoteFunctionDef = RemoteFunctionDef<any, any, any, AuthPolicy>
 
 /**
  * Identity helper for authoring a RemoteFunction. Returns its argument
  * unchanged — `defineRemoteDomain` consumes the typed shape.
  */
-export function defineRemoteFunction<TParams, TResult, TDeps = unknown>(
-  def: RemoteFunctionDef<TParams, TResult, TDeps>,
-): RemoteFunctionDef<TParams, TResult, TDeps> {
+export function defineRemoteFunction<
+  TParams,
+  TResult,
+  TDeps = unknown,
+  TAuth extends AuthPolicy = 'required',
+>(
+  def: RemoteFunctionDef<TParams, TResult, TDeps, TAuth>,
+): RemoteFunctionDef<TParams, TResult, TDeps, TAuth> {
   return def
 }

package/src/dispatch/call-remote.ts

@@ -22,8 +22,13 @@
 
 import type { ClientSessionCallOptions } from '@astrale-os/kernel-client/session'
 
-/** Minimal kernel-call surface callRemote needs (the bound view satisfies it). */
-type KernelCaller = {
+/**
+ * The minimal kernel-call surface: dynamic method dispatch by path string. The
+ * bound kernel session view (`BoundClientSessionView`) satisfies it structurally,
+ * as does any test double. Exported as the public narrow caller contract so
+ * handlers can depend on it instead of the wide, generic session view.
+ */
+export type KernelCaller = {
   call: (method: string, params: unknown, opts?: ClientSessionCallOptions) => Promise<unknown>
 }
 

package/src/dispatch/dispatcher.ts

@@ -25,7 +25,7 @@ import { MethodNotFoundError, SdkResultValidationError, SdkValidationError } fro
 import { executeHandler } from './execute'
 import { buildIdentityMap } from './identity'
 import { resolveMethod } from './resolve'
-import { resolveSelf, type SelfResult } from './self'
+import { resolveSelf, withNode, type ParsedSelf } from './self'
 import { validateParams, validateResult } from './validate'
 
 export type SdkDispatcherConfig<TDeps> = {
@@ -139,7 +139,7 @@ export class SdkDispatcher<TDeps = unknown> implements KernelAPI {
 
     // `undefined` (not `null`) for static methods — matches the `self` type on
     // `RemoteContext` / `MethodImpl`, which is `undefined` for static methods.
-    let resolvedSelf: SelfResult | undefined
+    let parsedSelf: ParsedSelf | undefined
     if (!bound.isStatic) {
       if (selfRef === undefined || selfRef === null || selfRef === '') {
         throw new SdkValidationError(
@@ -151,7 +151,7 @@ export class SdkDispatcher<TDeps = unknown> implements KernelAPI {
         )
       }
       try {
-        resolvedSelf = resolveSelf(String(selfRef))
+        parsedSelf = resolveSelf(String(selfRef))
       } catch (err) {
         // A malformed caller-supplied `self` is bad client input, not a server
         // fault — surface it as VALIDATION_ERROR (422), matching the sibling
@@ -174,10 +174,14 @@ export class SdkDispatcher<TDeps = unknown> implements KernelAPI {
     }
     const handlerParams = validation.data
     const callRemote = makeCallRemote(kernel)
+    // Enrich the parsed self with the lazy `node()` accessor, bound to this
+    // request's kernel (null when the auth policy yields none — `node()` then
+    // rejects). Done here, not in `resolveSelf`, so the parse stays kernel-free.
+    const self = parsedSelf ? withNode(parsedSelf, kernel) : undefined
     const ctx = {
       params: handlerParams,
       auth,
-      self: resolvedSelf,
+      self,
       deps: this.deps,
       url: this.url,
       kernel,

package/src/dispatch/index.ts

@@ -8,7 +8,7 @@ export {
 } from './validate'
 export { resolveSelf, type SelfResult } from './self'
 export { executeHandler, type ExecuteParams } from './execute'
-export { makeCallRemote, type CallRemoteFn } from './call-remote'
+export { makeCallRemote, type CallRemoteFn, type KernelCaller } from './call-remote'
 export {
   AuthorizationDeniedError,
   MethodNotFoundError,