@astrale-os/sdk 0.4.0 → 0.4.2

package/src/server/auxiliary-routes.ts

@@ -36,16 +36,15 @@ import { buildCorsHeaders, type CorsConfig } from '@astrale-os/kernel-server'
 import type { RemoteIdentityConfig } from '../auth/identity'
 import type { AnyRemoteFunctionDef } from '../define/remote-function'
 import type { ViewDef } from '../define/view'
-import type { CallRemoteFn } from '../dispatch/call-remote'
 import type { AuxIdentityMap } from '../dispatch/identity'
 
-import { makeIssuerMint } from '../auth/issuer-mint'
-import { makeSelfKernel } from '../auth/kernel-client'
+import { makeFunctionContext } from '../auth/function-context'
+import { makeDomainAuthority } from '../auth/issuer-mint'
 import { resolveInboundAuth } from '../auth/resolve'
 import { runAuthorize } from '../dispatch/authorize'
-import { makeCallRemote } from '../dispatch/call-remote'
 import { SdkResultValidationError, SdkValidationError } from '../dispatch/errors'
 import { validateParams, validateResult } from '../dispatch/validate'
+import { createInlineStep } from '../step'
 
 export type AuxiliaryRoutesConfig<TDeps> = {
   app: Hono
@@ -100,16 +99,23 @@ export function mountAuxiliaryRoutes<TDeps>(config: AuxiliaryRoutesConfig<TDeps>
         auth: def.auth,
         identity,
         corsHeaders,
-        // Views are transport-only (iframe HTML/redirect) — the kernel client
-        // built by `resolveInboundAuth` is intentionally NOT forwarded. Code
-        // inside the loaded iframe talks back to the kernel via the shell
-        // (WebSocket), not via this worker route. SERVER-rendered views that
-        // read the graph use `selfKernel` instead: the view's OWN identity,
-        // narrow grants (the cold-agent gate run had to deep-import SDK
-        // internals for exactly this — now it's the supported seam).
-        run: async ({ c, params, auth }) => {
-          const selfKernel = makeSelfKernel(identity, deps)
-          const ctx = { c, params, auth, deps, selfKernel }
+        // Views are transport-only (iframe HTML/redirect). SERVER-rendered
+        // views that read the graph use `ctx.fn.kernel()`: the view's own
+        // identity, with narrow grants.
+        run: async ({ c, params, auth, kernel }) => {
+          const inboundIss = auth?.credential?.verified?.iss as string | undefined
+          const kernelUrl = kernel?.default ?? inboundIss
+          const ctx = {
+            c,
+            params,
+            auth,
+            deps,
+            env: { url },
+            fn: makeFunctionContext(identity, deps, {
+              ref: `view.${slug}`,
+              ...(kernelUrl !== undefined ? { defaultKernelUrl: kernelUrl } : {}),
+            }),
+          }
           if (def.authorize) await runAuthorize(def.authorize, ctx)
           return def.render!(ctx)
         },
@@ -130,26 +136,40 @@ export function mountAuxiliaryRoutes<TDeps>(config: AuxiliaryRoutesConfig<TDeps>
         auth: def.auth,
         identity,
         corsHeaders,
-        run: async ({ c, auth, kernel, callRemote }) => {
-          const selfKernel = makeSelfKernel(identity, deps)
+        run: async ({ c, auth, kernel }) => {
           const rawBody: unknown = await c.req.json().catch(() => ({}))
           const validation = validateParams(def.inputSchema, rawBody)
           if (!validation.ok) {
             throw new SdkValidationError(validation.issues as SdkValidationError['issues'])
           }
-          const issuer = makeIssuerMint(identity)
+          const inboundIss = auth?.credential?.verified?.iss as string | undefined
+          const kernelUrl = kernel?.default ?? inboundIss
+          const caller =
+            auth && inboundIss
+              ? {
+                  iss: inboundIss,
+                  url: kernelUrl ?? inboundIss,
+                }
+              : undefined
           const ctx = {
             params: validation.data,
             c,
             auth,
             deps,
+            env: { url },
             kernel,
-            issuer,
-            callRemote,
-            selfKernel,
+            ...(caller !== undefined ? { caller } : {}),
+            domain: makeDomainAuthority(identity),
+            fn: makeFunctionContext(identity, deps, {
+              ref: `function.${slug}`,
+              ...(kernelUrl !== undefined ? { defaultKernelUrl: kernelUrl } : {}),
+            }),
           }
           if (def.authorize) await runAuthorize(def.authorize, ctx)
-          const result = await def.execute(ctx)
+          const result = await def.execute({
+            ...ctx,
+            step: createInlineStep({ scope: { kind: 'function', ref: `function.${slug}`, slug } }),
+          })
           const outValidation = validateResult(def.outputSchema, result)
           if (!outValidation.ok) {
             throw new SdkResultValidationError(
@@ -188,7 +208,6 @@ type RunArgs = {
   params: Record<string, string>
   auth: AuthContext | null
   kernel: BoundClientSessionView<FnMap> | null
-  callRemote: CallRemoteFn
 }
 
 type MountEntryArgs = {
@@ -264,7 +283,6 @@ function mountEntry(args: MountEntryArgs): void {
         params: { ...hostParams, ...pathParams },
         auth: resolvedAuth,
         kernel,
-        callRemote: makeCallRemote(kernel),
       })
       return applyCorsToResponse(response, corsHeaders)
     } catch (err) {

package/src/server/create.ts

@@ -47,7 +47,7 @@ export function createRemoteServer<TDeps>(config: RemoteServerConfig<TDeps>): Re
     deps: config.deps,
     privateKey: config.privateKey,
     issuer: iss,
-    // The canonicalized serving URL, NOT the raw config.url: `ctx.url` is
+    // The canonicalized serving URL, NOT the raw config.url: `ctx.env.url` is
     // documented as the worker's `iss` identity, so the two must be one value.
     url: iss,
   })

package/src/step/index.ts

@@ -0,0 +1,4 @@
+export { createInlineStep } from './inline'
+export type { InlineStepOptions, StepExecutor } from './inline'
+export { buildStepRun } from './step'
+export type { FunctionStepScope, MethodStepScope, Step, StepRun, StepScope } from './step'

package/src/step/inline.ts

@@ -0,0 +1,38 @@
+import type { Step, StepRun, StepScope } from './step'
+
+import { buildStepRun, roundTripStepResult } from './step'
+
+export type StepExecutor = <T>(run: StepRun, handler: () => T | Promise<T>) => Promise<T>
+
+export type InlineStepOptions = {
+  scope?: StepScope
+  execute?: StepExecutor
+}
+
+export function createInlineStep(options: InlineStepOptions = {}): Step {
+  const occurrences = new Map<string, number>()
+  const execute = options.execute ?? inlineExecute
+
+  return {
+    async run(id, handler) {
+      const run = buildStepRun(id, options.scope, nextOccurrence(id, options.scope, occurrences))
+      return execute(run, handler)
+    },
+  }
+}
+
+async function inlineExecute<T>(run: StepRun, handler: () => T | Promise<T>): Promise<T> {
+  const result = await handler()
+  return roundTripStepResult(run.key, result)
+}
+
+function nextOccurrence(
+  id: string,
+  scope: StepScope | undefined,
+  occurrences: Map<string, number>,
+): number {
+  const run = buildStepRun(id, scope, 0)
+  const occurrence = occurrences.get(run.key) ?? 0
+  occurrences.set(run.key, occurrence + 1)
+  return occurrence
+}

package/src/step/step.ts

@@ -0,0 +1,95 @@
+export type Step = {
+  run<T>(id: string, handler: () => T | Promise<T>): Promise<T>
+}
+
+export type MethodStepScope = {
+  kind: 'method'
+  ref: string
+  owner: string
+  method: string
+}
+
+export type FunctionStepScope = {
+  kind: 'function'
+  ref: string
+  slug: string
+}
+
+export type StepScope = MethodStepScope | FunctionStepScope
+
+export type StepRun = {
+  /** The author-provided id, normalized to the local id inside this scope. */
+  id: string
+  /** Backend-facing durable key, qualified by the method/function scope. */
+  key: string
+  /** Zero-based occurrence for repeated ids in one execution. */
+  occurrence: number
+  scope?: StepScope
+}
+
+export function requireStepId(id: string): string {
+  if (typeof id !== 'string' || id.trim() === '') {
+    throw new TypeError('step.run: id must be a non-empty string')
+  }
+  return id
+}
+
+export function buildStepRun(
+  id: string,
+  scope: StepScope | undefined,
+  occurrence: number,
+): StepRun {
+  const stepId = requireStepId(localStepId(id, scope))
+  const key = scope ? `${canonicalScope(scope)}.${stepId}` : stepId
+  return {
+    id: stepId,
+    key,
+    occurrence,
+    ...(scope ? { scope } : {}),
+  }
+}
+
+export function roundTripStepResult<T>(id: string, value: T): T {
+  if (value === undefined) return value
+
+  let serialized: string | undefined
+  try {
+    serialized = JSON.stringify(value)
+  } catch (err) {
+    throw new TypeError(
+      `step.run("${id}"): result must be JSON-serializable: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    )
+  }
+
+  if (serialized === undefined) {
+    throw new TypeError(`step.run("${id}"): result must be JSON-serializable`)
+  }
+
+  return JSON.parse(serialized) as T
+}
+
+function localStepId(id: string, scope: StepScope | undefined): string {
+  if (!scope) return id
+
+  for (const prefix of scopePrefixes(scope)) {
+    const scoped = `${prefix}.`
+    if (id.startsWith(scoped) && id.length > scoped.length) return id.slice(scoped.length)
+  }
+
+  return id
+}
+
+function scopePrefixes(scope: StepScope): string[] {
+  switch (scope.kind) {
+    case 'method':
+      return [scope.ref, `${scope.owner}.${scope.method}`]
+    case 'function':
+      return [scope.ref, `function.${scope.slug}`]
+  }
+}
+
+function canonicalScope(scope: StepScope): string {
+  return scope.ref
+}

package/dist/dispatch/call-remote.d.ts

@@ -1,39 +0,0 @@
-/**
- * `ctx.callRemote` — call ANOTHER worker's remote method from a handler.
- *
- * A worker's `kernel.call('/dom/class.X/method', …)` signs `aud = <kernel>`,
- * which is correct for a **kernel syscall** (it runs in the kernel) but is
- * rejected by a **remote method** (a Function with `binding.remoteUrl`, i.e.
- * another worker) — the target worker verifies `aud` against its own identity
- * and throws `Credential audience mismatch` at authentication.
- *
- * `callRemote` is now a thin wrapper over the bound kernel session: the kernel
- * resolves a remote-bound path to a redirect carrying the worker's URL and its
- * `iss`, and the session (configured in `bindKernel`) follows it reactively —
- * minting a kernel-signed delegation envelope scoped to that `iss` via the
- * caller's own `@<subject>::mintDelegationCredential`, then dialing the worker.
- * Instance-method `self` is injected by the kernel resolver into the redirect,
- * so a bare `kernel.call(path, params)` is all that's needed here.
- *
- * Prerequisite (authorization, unchanged): the calling Function's identity must
- * hold `USE` on `Identity.mintDelegationCredential` AND the target method's own
- * grants — the session only fixes the audience (authentication), not grants.
- */
-import type { ClientSessionCallOptions } from '@astrale-os/kernel-client/session';
-/**
- * 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>;
-};
-export type CallRemoteFn = (path: string, params?: Record<string, unknown>) => Promise<unknown>;
-/**
- * Build the `callRemote` helper for one handler invocation. `kernel` is the
- * handler's bound kernel view (or `null` for a public/unauthenticated request,
- * where `callRemote` cannot mint and throws on use).
- */
-export declare function makeCallRemote(kernel: KernelCaller | null): CallRemoteFn;
-//# sourceMappingURL=call-remote.d.ts.map

package/dist/dispatch/call-remote.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"call-remote.d.ts","sourceRoot":"","sources":["../../src/dispatch/call-remote.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mCAAmC,CAAA;AAEjF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,wBAAwB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAC7F,CAAA;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;AAE/F;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,GAAG,YAAY,CAWxE"}

package/dist/dispatch/call-remote.js

@@ -1,37 +0,0 @@
-/**
- * `ctx.callRemote` — call ANOTHER worker's remote method from a handler.
- *
- * A worker's `kernel.call('/dom/class.X/method', …)` signs `aud = <kernel>`,
- * which is correct for a **kernel syscall** (it runs in the kernel) but is
- * rejected by a **remote method** (a Function with `binding.remoteUrl`, i.e.
- * another worker) — the target worker verifies `aud` against its own identity
- * and throws `Credential audience mismatch` at authentication.
- *
- * `callRemote` is now a thin wrapper over the bound kernel session: the kernel
- * resolves a remote-bound path to a redirect carrying the worker's URL and its
- * `iss`, and the session (configured in `bindKernel`) follows it reactively —
- * minting a kernel-signed delegation envelope scoped to that `iss` via the
- * caller's own `@<subject>::mintDelegationCredential`, then dialing the worker.
- * Instance-method `self` is injected by the kernel resolver into the redirect,
- * so a bare `kernel.call(path, params)` is all that's needed here.
- *
- * Prerequisite (authorization, unchanged): the calling Function's identity must
- * hold `USE` on `Identity.mintDelegationCredential` AND the target method's own
- * grants — the session only fixes the audience (authentication), not grants.
- */
-/**
- * Build the `callRemote` helper for one handler invocation. `kernel` is the
- * handler's bound kernel view (or `null` for a public/unauthenticated request,
- * where `callRemote` cannot mint and throws on use).
- */
-export function makeCallRemote(kernel) {
-    return async (path, params = {}) => {
-        if (!kernel) {
-            throw new Error('callRemote requires an authenticated request — no kernel credential (public method?)');
-        }
-        // The bound session auto-follows the kernel's redirect and mints for the
-        // worker's `iss`; a remote-bound path therefore just works as a kernel.call.
-        return kernel.call(path, params);
-    };
-}
-//# sourceMappingURL=call-remote.js.map

package/dist/dispatch/call-remote.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"call-remote.js","sourceRoot":"","sources":["../../src/dispatch/call-remote.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAgBH;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,MAA2B;IACxD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,EAAE,EAAE,EAAE;QACjC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,sFAAsF,CACvF,CAAA;QACH,CAAC;QACD,yEAAyE;QACzE,6EAA6E;QAC7E,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAClC,CAAC,CAAA;AACH,CAAC"}

package/src/dispatch/call-remote.ts

@@ -1,53 +0,0 @@
-/**
- * `ctx.callRemote` — call ANOTHER worker's remote method from a handler.
- *
- * A worker's `kernel.call('/dom/class.X/method', …)` signs `aud = <kernel>`,
- * which is correct for a **kernel syscall** (it runs in the kernel) but is
- * rejected by a **remote method** (a Function with `binding.remoteUrl`, i.e.
- * another worker) — the target worker verifies `aud` against its own identity
- * and throws `Credential audience mismatch` at authentication.
- *
- * `callRemote` is now a thin wrapper over the bound kernel session: the kernel
- * resolves a remote-bound path to a redirect carrying the worker's URL and its
- * `iss`, and the session (configured in `bindKernel`) follows it reactively —
- * minting a kernel-signed delegation envelope scoped to that `iss` via the
- * caller's own `@<subject>::mintDelegationCredential`, then dialing the worker.
- * Instance-method `self` is injected by the kernel resolver into the redirect,
- * so a bare `kernel.call(path, params)` is all that's needed here.
- *
- * Prerequisite (authorization, unchanged): the calling Function's identity must
- * hold `USE` on `Identity.mintDelegationCredential` AND the target method's own
- * grants — the session only fixes the audience (authentication), not grants.
- */
-
-import type { ClientSessionCallOptions } from '@astrale-os/kernel-client/session'
-
-/**
- * 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>
-}
-
-export type CallRemoteFn = (path: string, params?: Record<string, unknown>) => Promise<unknown>
-
-/**
- * Build the `callRemote` helper for one handler invocation. `kernel` is the
- * handler's bound kernel view (or `null` for a public/unauthenticated request,
- * where `callRemote` cannot mint and throws on use).
- */
-export function makeCallRemote(kernel: KernelCaller | null): CallRemoteFn {
-  return async (path, params = {}) => {
-    if (!kernel) {
-      throw new Error(
-        'callRemote requires an authenticated request — no kernel credential (public method?)',
-      )
-    }
-    // The bound session auto-follows the kernel's redirect and mints for the
-    // worker's `iss`; a remote-bound path therefore just works as a kernel.call.
-    return kernel.call(path, params)
-  }
-}