@astrale-os/sdk 0.1.0

package/src/dispatch/dispatcher.ts

@@ -0,0 +1,257 @@
+/**
+ * `SdkDispatcher` — implements `KernelAPI` by running the SDK's pipeline.
+ *
+ * Built once at server startup from the domain's `CompiledDomain` plus a typed
+ * deps container and a private JWK. Per-method identity configs are
+ * pre-resolved into a Map so dispatch is O(1) per call.
+ *
+ * Pipeline per call:
+ *   resolve method → authenticate → validate → resolve self → execute
+ */
+
+import type { AuthedKernelAPI, DispatchResult, KernelAPI } from '@astrale-os/kernel-api'
+import type { AuthPolicy } from '@astrale-os/kernel-api/routed'
+import type { CredentialInput, Path } from '@astrale-os/kernel-core'
+import type { BoundMethod, CompiledDomain } from '@astrale-os/kernel-core/domain'
+
+import type { RemoteIdentityConfig } from '../auth/identity'
+import type { AnyRemoteHandler } from '../method/single'
+import type { MethodIndex } from './resolve'
+
+import { resolveInboundAuth } from '../auth/resolve'
+import { runAuthorize } from './authorize'
+import { makeCallRemote } from './call-remote'
+import { MethodNotFoundError, SdkResultValidationError, SdkValidationError } from './errors'
+import { executeHandler } from './execute'
+import { buildIdentityMap } from './identity'
+import { resolveMethod } from './resolve'
+import { resolveSelf, type SelfResult } from './self'
+import { validateParams, validateResult } from './validate'
+
+export type SdkDispatcherConfig<TDeps> = {
+  /** The compiled domain — source of the method layout and origin-addressed subs. */
+  compiled: CompiledDomain
+  /** Pre-built method map: ref → BoundMethod. */
+  methods: MethodIndex
+  /** Dependency container injected into every handler. */
+  deps: TDeps
+  /** Private key for signing outbound per-function credentials. */
+  privateKey: JsonWebKey
+  /**
+   * The worker's identity (`iss`) for outbound per-function credentials — its
+   * serving URL (e.g. `https://crm.test.com`), DECOUPLED from the domain's
+   * addressing `origin`. Matches the `iss` the kernel pins on each node at
+   * install (the URL it fetched the domain at).
+   */
+  issuer: string
+  /** The worker's serving URL (`config.url`) — exposed to handlers as `ctx.url`. */
+  url: string
+}
+
+export class SdkDispatcher<TDeps = unknown> implements KernelAPI {
+  private readonly methods: MethodIndex
+  private readonly deps: TDeps
+  private readonly identities: Map<BoundMethod<AnyRemoteHandler>, RemoteIdentityConfig>
+  private readonly issuer: string
+  private readonly url: string
+  private readonly privateKey: JsonWebKey
+
+  constructor(config: SdkDispatcherConfig<TDeps>) {
+    this.methods = config.methods
+    this.deps = config.deps
+    this.issuer = config.issuer
+    this.url = config.url
+    this.privateKey = config.privateKey
+    const methodList = Array.from(new Set(config.methods.values()))
+    const identityMethods = methodList.filter((bound) => methodAuthPolicy(bound) !== 'public')
+    this.identities =
+      identityMethods.length > 0
+        ? buildIdentityMap(config.compiled, identityMethods, config.privateKey, config.issuer)
+        : new Map()
+  }
+
+  async call(
+    path: Path | string,
+    credential: CredentialInput,
+    params: unknown,
+    opts?: { self?: string },
+  ): Promise<unknown> {
+    return this.run(path, credential, params, opts?.self)
+  }
+
+  async stream(
+    path: Path | string,
+    credential: CredentialInput,
+    params: unknown,
+    opts?: { self?: string },
+  ): Promise<AsyncGenerator<unknown>> {
+    const result = await this.run(path, credential, params, opts?.self)
+    if (!isAsyncGenerator(result)) {
+      throw new Error(`Method "${pathToString(path)}" did not return an async generator`)
+    }
+    return result
+  }
+
+  /**
+   * SDK dispatch never redirects — the SDK server IS the remote destination.
+   * Every call resolves locally; we just classify the return as value or stream
+   * and hand it back to the kernel-api orchestrator.
+   */
+  async dispatch(
+    path: Path | string,
+    credential: CredentialInput,
+    params: unknown,
+    opts?: { self?: string },
+  ): Promise<DispatchResult> {
+    const result = await this.run(path, credential, params, opts?.self)
+    return isAsyncGenerator(result)
+      ? { kind: 'stream', generator: result }
+      : { kind: 'value', value: result }
+  }
+
+  as(credential: CredentialInput): AuthedKernelAPI {
+    return {
+      call: (path, params) => this.call(path, credential, params),
+      stream: (path, params) => this.stream(path, credential, params),
+    }
+  }
+
+  private async run(
+    path: Path | string,
+    credential: CredentialInput,
+    params: unknown,
+    selfRef?: string,
+  ): Promise<unknown> {
+    const bound = resolveMethod(this.methods, path)
+    if (!bound) throw new MethodNotFoundError(pathToString(path))
+
+    const authPolicy: AuthPolicy = (bound.handler as { auth?: AuthPolicy }).auth ?? 'required'
+    const fnIdentity = this.identityFor(bound)
+    const { auth, kernel } = await resolveInboundAuth(credential, authPolicy, fnIdentity)
+
+    if (typeof params !== 'object' || params === null || Array.isArray(params)) {
+      throw new SdkValidationError([{ path: [], message: 'Params must be a plain object' }])
+    }
+    const validation = validateParams(bound.inputSchema, params)
+    if (!validation.ok) {
+      throw new SdkValidationError(validation.issues as SdkValidationError['issues'])
+    }
+
+    // `undefined` (not `null`) for static methods — matches the `self` type on
+    // `RemoteContext` / `MethodImpl`, which is `undefined` for static methods.
+    let resolvedSelf: SelfResult | undefined
+    if (!bound.isStatic) {
+      if (selfRef === undefined || selfRef === null || selfRef === '') {
+        throw new SdkValidationError(
+          [{ path: ['self'], message: 'Required for non-static method' }],
+          `"${bound.owner}.${bound.method}" is an instance method — it needs a target node. ` +
+            `Either call it via instance dispatch (e.g. "@<nodeId>::${bound.method}" ` +
+            `or "/path/to/node::${bound.method}"), or pass "self" in dispatch opts ` +
+            `(e.g. { self: "@<nodeId>" }).`,
+        )
+      }
+      try {
+        resolvedSelf = 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
+        // missing-self branch above, instead of INTERNAL_ERROR (500).
+        throw new SdkValidationError(
+          [
+            {
+              path: ['self'],
+              message: err instanceof Error ? err.message : 'Failed to resolve self',
+            },
+          ],
+          `Invalid "self" target "${selfRef}": ${err instanceof Error ? err.message : 'unparseable path'}`,
+        )
+      }
+    }
+
+    const handler = bound.handler as {
+      execute: (...args: unknown[]) => unknown
+      authorize?: (ctx: unknown) => void | Promise<void>
+    }
+    const handlerParams = validation.data
+    const callRemote = makeCallRemote(kernel)
+    const ctx = {
+      params: handlerParams,
+      auth,
+      self: resolvedSelf,
+      deps: this.deps,
+      url: this.url,
+      kernel,
+      callRemote,
+    }
+
+    if (handler.authorize) await runAuthorize(handler.authorize, ctx)
+
+    const result = await executeHandler({ handler, ref: bound.ref, ...ctx })
+    return validateOutput(bound, result)
+  }
+
+  private identityFor(bound: BoundMethod<AnyRemoteHandler>): RemoteIdentityConfig {
+    const identity = this.identities.get(bound)
+    if (!identity) {
+      if (methodAuthPolicy(bound) === 'public') {
+        return { issuer: this.issuer, subject: bound.ref, privateKey: this.privateKey }
+      }
+      throw new Error(
+        `SdkDispatcher: no identity config for "${bound.owner}.${bound.method}" — ` +
+          `method is registered in the index but missing from the identity map.`,
+      )
+    }
+    return identity
+  }
+}
+
+function methodAuthPolicy(bound: BoundMethod<AnyRemoteHandler>): AuthPolicy {
+  return (bound.handler as { auth?: AuthPolicy }).auth ?? 'required'
+}
+
+function pathToString(path: Path | string): string {
+  return typeof path === 'string' ? path : path.raw
+}
+
+/**
+ * Validate a handler's output against `bound.outputSchema`, mirroring the
+ * kernel's dispatcher (`runtime/.../dispatcher.ts` + `events.ts`):
+ *   - `binary` outputs skip validation (no schema applies).
+ *   - async-generator outputs (`output: 'stream'`) are wrapped so each chunk
+ *     is validated as it is yielded.
+ *   - all other (`value`) outputs are validated once and returned parsed.
+ * Returns the synchronous shape (value or generator) so the caller's
+ * `dispatch()` can classify it without awaiting a stream to completion.
+ */
+function validateOutput(bound: BoundMethod<AnyRemoteHandler>, result: unknown): unknown {
+  if (bound.output === 'binary') return result
+  if (isAsyncGenerator(result)) return validateOutputStream(bound, result)
+  return validateChunk(bound, result)
+}
+
+async function* validateOutputStream(
+  bound: BoundMethod<AnyRemoteHandler>,
+  gen: AsyncGenerator<unknown>,
+): AsyncGenerator<unknown> {
+  for await (const chunk of gen) {
+    yield validateChunk(bound, chunk)
+  }
+}
+
+/** Parse one output value against `bound.outputSchema` or throw a 500-class error. */
+function validateChunk(bound: BoundMethod<AnyRemoteHandler>, value: unknown): unknown {
+  const out = validateResult(bound.outputSchema, value)
+  if (!out.ok) {
+    throw new SdkResultValidationError(out.issues as SdkResultValidationError['issues'], bound.ref)
+  }
+  return out.data
+}
+
+function isAsyncGenerator(value: unknown): value is AsyncGenerator<unknown> {
+  return (
+    value !== null &&
+    value !== undefined &&
+    typeof value === 'object' &&
+    Symbol.asyncIterator in value
+  )
+}

package/src/dispatch/errors.ts

@@ -0,0 +1,94 @@
+/**
+ * Errors thrown by the dispatch pipeline.
+ *
+ * Each implements `KernelErrorClassifiable` so `kernel-api/dispatch` can
+ * convert them into typed `KernelErrorPayload` values automatically.
+ */
+
+import type { KernelErrorPayload, KernelErrorClassifiable } from '@astrale-os/kernel-api'
+
+import { KERNEL_ERROR_CODES } from '@astrale-os/kernel-api'
+
+/** A single Zod issue, normalized to the path/message the payload carries. */
+type ValidationIssue = { path: (string | number)[]; message: string }
+
+/** Shape Zod issues into the `data.errors` array of a `KernelErrorPayload`. */
+function toPayloadErrors(issues: ValidationIssue[]): Array<{
+  path: (string | number)[]
+  code: 'INVALID'
+  message: string
+}> {
+  return issues.map((i) => ({ path: i.path, code: 'INVALID', message: i.message }))
+}
+
+export class MethodNotFoundError extends Error implements KernelErrorClassifiable {
+  constructor(method: string) {
+    super(`Method not found: ${method}`)
+    this.name = 'MethodNotFoundError'
+  }
+
+  toKernelErrorPayload(): KernelErrorPayload {
+    return { code: KERNEL_ERROR_CODES.METHOD_NOT_FOUND, message: this.message }
+  }
+}
+
+export class SdkValidationError extends Error implements KernelErrorClassifiable {
+  constructor(
+    readonly issues: ValidationIssue[],
+    message?: string,
+  ) {
+    super(message ?? 'Invalid params')
+    this.name = 'SdkValidationError'
+  }
+
+  toKernelErrorPayload(): KernelErrorPayload {
+    return {
+      code: KERNEL_ERROR_CODES.VALIDATION_ERROR,
+      message: this.message,
+      data: { errors: toPayloadErrors(this.issues) },
+    }
+  }
+}
+
+/**
+ * Thrown when a handler's return value (or a stream chunk) fails validation
+ * against its `outputSchema`. This is a server/handler fault — the author's
+ * code produced data that violates its own declared contract — so it maps to
+ * `INTERNAL_ERROR` (→ HTTP 500), NOT the `VALIDATION_ERROR` (422) used for
+ * bad caller input. Mirrors the kernel's `ResultValidationError`.
+ */
+export class SdkResultValidationError extends Error implements KernelErrorClassifiable {
+  constructor(
+    readonly issues: ValidationIssue[],
+    readonly ref?: string,
+  ) {
+    super(`Function${ref ? ` "${ref}"` : ''} returned an invalid result`)
+    this.name = 'SdkResultValidationError'
+  }
+
+  toKernelErrorPayload(): KernelErrorPayload {
+    return {
+      code: KERNEL_ERROR_CODES.INTERNAL_ERROR,
+      message: this.message,
+      data: { errors: toPayloadErrors(this.issues) },
+    }
+  }
+}
+
+/**
+ * Thrown by a `RemoteHandler.authorize` hook to deny a call.
+ *
+ * Wraps any error the hook throws — handlers can throw a plain `Error` and
+ * the dispatcher converts it. Already-typed `AuthorizationDeniedError`
+ * instances are passed through unchanged so callers can attach hints.
+ */
+export class AuthorizationDeniedError extends Error implements KernelErrorClassifiable {
+  constructor(message: string, cause?: unknown) {
+    super(message, { cause })
+    this.name = 'AuthorizationDeniedError'
+  }
+
+  toKernelErrorPayload(): KernelErrorPayload {
+    return { code: KERNEL_ERROR_CODES.PERMISSION_DENIED, message: this.message }
+  }
+}

package/src/dispatch/execute.ts

@@ -0,0 +1,51 @@
+/**
+ * Handler execution — pipeline step 4.
+ *
+ * Calls the resolved handler's `execute` with a fully assembled
+ * `RemoteContext`: validated params, auth context, optional bound self,
+ * typed deps, and a kernel `BoundClientSessionView`. The handler may return a
+ * value, a Promise, or an async generator (for `output: 'stream'`).
+ */
+
+import type { FnMap } from '@astrale-os/kernel-client'
+import type { BoundClientSessionView } from '@astrale-os/kernel-client/session'
+import type { AuthContext } from '@astrale-os/kernel-core'
+
+import type { CallRemoteFn } from './call-remote'
+import type { SelfResult } from './self'
+
+// oxlint-disable-next-line no-explicit-any
+type HandlerFn = (...args: any[]) => any
+
+export type ExecuteParams = {
+  /** Handler may omit `execute` when authored as a stub (spec-only binding). */
+  handler: { execute?: HandlerFn }
+  /** Namespaced ref of the dispatched method — names the offending method in the
+   *  stub-leak diagnostic below (the dispatcher passes `bound.ref`). */
+  ref?: string
+  params: Record<string, unknown>
+  auth: AuthContext | null
+  self: SelfResult | undefined
+  deps: unknown
+  url: string
+  kernel: BoundClientSessionView<FnMap> | null
+  callRemote: CallRemoteFn
+}
+
+export async function executeHandler(ctx: ExecuteParams): Promise<unknown> {
+  if (typeof ctx.handler.execute !== 'function') {
+    throw new Error(
+      `executeHandler: handler${ctx.ref ? ` for "${ctx.ref}"` : ''} has no \`execute\` body — ` +
+        `this is a binding stub that should have been resolved to a remote redirect upstream.`,
+    )
+  }
+  return ctx.handler.execute({
+    params: ctx.params,
+    auth: ctx.auth,
+    self: ctx.self,
+    deps: ctx.deps,
+    url: ctx.url,
+    kernel: ctx.kernel,
+    callRemote: ctx.callRemote,
+  })
+}

package/src/dispatch/identity.ts

@@ -0,0 +1,148 @@
+/**
+ * Per-callable identity — dispatcher runtime + install-time wiring.
+ *
+ * Two flavors of callable get an identity per the install-time identity
+ * binding: Methods on classes/interfaces (sub = MethodPath) and auto-
+ * materialized core function nodes — RemoteFunctions and Views (sub =
+ * AbsolutePath of the node under `core/{functions,views}/<slug>`).
+ *
+ * At server startup the method dispatcher and the View / RemoteFunction
+ * route mounter pre-compute, for every materialized callable, the
+ * `RemoteIdentityConfig` they sign outbound kernel calls with. The kernel
+ * then matches an existing function identity instead of provisioning a
+ * generic one.
+ *
+ * **Single source of truth:** every helper here is a thin lens over the
+ * canonical `resolveCallables` from `@astrale-os/kernel-core/domain`. The
+ * kernel validates install subs against the SAME function — drift = 0
+ * by construction. This closes the previous SDK-side gap where
+ * `collectMethodPaths` filtered to `own|override` and silently dropped
+ * `sealed`/`default` interface methods (which DO materialize as nodes).
+ */
+
+import type { BoundMethod, CompiledDomain } from '@astrale-os/kernel-core/domain'
+
+import { resolveCallables } from '@astrale-os/kernel-core/domain'
+
+import type { RemoteIdentityConfig } from '../auth/identity'
+import type { AnyRemoteHandler } from '../method/single'
+
+/**
+ * For each materialized method node, emit its `MethodPath` (semantic,
+ * layout-independent) keyed by the method's namespaced ref. Used to
+ * build the install `subs` claim and to look up runtime per-method
+ * subjects in `buildIdentityMap`.
+ *
+ * Includes every method node the kernel materializes — class own/override
+ * AND interface own (sealed/default/override). Inherited (non-overriding)
+ * class methods reuse the interface's node via a `method_of` edge and
+ * are correctly absent here.
+ */
+export function collectMethodPaths(compiled: CompiledDomain): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const c of resolveCallables(compiled)) {
+    if (c.kind === 'method') out[c.ref] = c.sub
+  }
+  return out
+}
+
+/** `{ views, remoteFunctions }` buckets keyed by slug — the shared shape
+ *  for every per-aux-callable map (paths, identity configs). */
+export type AuxBuckets<T> = {
+  views: Record<string, T>
+  remoteFunctions: Record<string, T>
+}
+
+/**
+ * slug → `AbsolutePath.raw` for each auto-materialized aux node
+ * (RemoteFunction / View). These nodes live at
+ * `/<origin>/core/{functions,views}/<slug>` and have no class+method
+ * decomposition that would justify a MethodPath — their identity is their
+ * graph position.
+ */
+export type AuxIdentityPaths = AuxBuckets<string>
+
+export function collectAuxIdentityPaths(compiled: CompiledDomain): AuxIdentityPaths {
+  const views: Record<string, string> = {}
+  const remoteFunctions: Record<string, string> = {}
+  for (const c of resolveCallables(compiled)) {
+    if (c.kind !== 'core' || !c.slug) continue
+    if (c.className === 'View') {
+      views[c.slug] = c.sub
+    } else if (c.className === 'Function') {
+      // Standalone callables (the former `RemoteFunction`) materialize as the
+      // canonical kernel `Function` class.
+      remoteFunctions[c.slug] = c.sub
+    } else {
+      throw new Error(
+        `collectAuxIdentityPaths: unrecognised aux callable className "${c.className}" ` +
+          `at ${c.ref}. If you've added a new auto-materialized Function class to extendCore, ` +
+          `extend this collector + the kernel walker (resolveCallables) to handle it.`,
+      )
+    }
+  }
+  return { views, remoteFunctions }
+}
+
+/**
+ * slug → `RemoteIdentityConfig` for each auto-materialized View /
+ * RemoteFunction. Built once at server startup; consumed by
+ * `mountAuxiliaryRoutes` so each handler signs outbound `kernel.call(...)`
+ * with its own `sub` (the node's AbsolutePath). Mirrors `buildIdentityMap`.
+ */
+export type AuxIdentityMap = AuxBuckets<RemoteIdentityConfig>
+
+export function buildAuxIdentityMap(
+  compiled: CompiledDomain,
+  privateKey: JsonWebKey,
+  issuer: string,
+): AuxIdentityMap {
+  const paths = collectAuxIdentityPaths(compiled)
+  const views: Record<string, RemoteIdentityConfig> = {}
+  for (const [slug, subject] of Object.entries(paths.views)) {
+    views[slug] = { issuer, subject, privateKey }
+  }
+  const remoteFunctions: Record<string, RemoteIdentityConfig> = {}
+  for (const [slug, subject] of Object.entries(paths.remoteFunctions)) {
+    remoteFunctions[slug] = { issuer, subject, privateKey }
+  }
+  return { views, remoteFunctions }
+}
+
+/**
+ * Pre-resolve per-method identity configs. Lookup is by BoundMethod instance,
+ * so the dispatcher pays O(1) per call instead of re-constructing the config.
+ *
+ * `iss` = the worker's own **serving URL** (`issuer` arg, e.g.
+ * `https://crm.test.com`) — its cryptographic identity, DECOUPLED from the
+ * domain's addressing `origin` (a graph slug). The kernel stamps the same
+ * value on each function node at install (it pins `iss` to the URL it fetched
+ * the domain at) and verifies inbound credentials against that issuer's JWKS
+ * (OIDC discovery). The function `sub` stays the origin-addressed MethodPath —
+ * `sub` = which function, `iss` = who signs.
+ */
+export function buildIdentityMap(
+  compiled: CompiledDomain,
+  methods: BoundMethod<AnyRemoteHandler>[],
+  privateKey: JsonWebKey,
+  issuer: string,
+): Map<BoundMethod<AnyRemoteHandler>, RemoteIdentityConfig> {
+  const paths = collectMethodPaths(compiled)
+  const out = new Map<BoundMethod<AnyRemoteHandler>, RemoteIdentityConfig>()
+  for (const bound of methods) {
+    const subject = paths[bound.ref]
+    if (!subject) {
+      // Under the "drift = 0" invariant every dispatched method's ref is a key
+      // in `paths`. A miss means an install/index drift — fail loudly at boot
+      // rather than signing with `bound.ref` (a namespaced ref, NOT a
+      // MethodPath sub), which would silently fail kernel identity matching at
+      // call time. Mirrors `identityFor` / `requireAuxIdentity`.
+      throw new Error(
+        `buildIdentityMap: method "${bound.ref}" is in the dispatch index but absent ` +
+          `from resolveCallables(compiled) — no identity subject to sign with.`,
+      )
+    }
+    out.set(bound, { issuer, subject, privateKey })
+  }
+  return out
+}

package/src/dispatch/index.ts

@@ -0,0 +1,17 @@
+export { SdkDispatcher, type SdkDispatcherConfig } from './dispatcher'
+export { resolveMethod, buildMethodIndex, type MethodIndex } from './resolve'
+export {
+  validateParams,
+  validateResult,
+  type ValidationResult,
+  type ResultValidationResult,
+} from './validate'
+export { resolveSelf, type SelfResult } from './self'
+export { executeHandler, type ExecuteParams } from './execute'
+export { makeCallRemote, type CallRemoteFn } from './call-remote'
+export {
+  AuthorizationDeniedError,
+  MethodNotFoundError,
+  SdkValidationError,
+  SdkResultValidationError,
+} from './errors'

package/src/dispatch/resolve.ts

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

@@ -0,0 +1,32 @@
+/**
+ * Self resolution — pipeline step 3.
+ *
+ * `_self` is a path reference to the node the non-static method runs on.
+ * Currently a thin parse: the caller's string becomes a `Path`, and handlers
+ * build recursive paths as `${self.path}::method` (the `Path`'s `toString`
+ * yields its raw form, so template literals work unchanged).
+ *
+ * `resolveSelf` receives the bare self target (`@<id>` or a tree path) — the
+ * method ref travels in a separate dispatch channel, so `::method` never
+ * reaches here. For the `@<id>` form the parsed `Path` is an `IdPath` which
+ * already carries the node id; surfacing it on `SelfResult.id` saves every
+ * worker handler from either parsing `self.path.raw` by hand or doing a
+ * `Node::get` round-trip just to recover the id of the node it's already
+ * operating on.
+ *
+ * Kept as a distinct step so a future implementation can do a real
+ * resolution here (e.g. hydrate a node/accessor) without touching callers.
+ */
+
+import { IdPath, Path, type NodeId } from '@astrale-os/kernel-core'
+
+export type SelfResult = {
+  path: Path
+  /** Set when `path` is an `IdPath` (i.e. `@<id>::method` calls). */
+  id?: NodeId
+}
+
+export function resolveSelf(ref: string): SelfResult {
+  const path = Path.parse(ref)
+  return path instanceof IdPath ? { path, id: path.id } : { path }
+}