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

package/src/server/start.ts

@@ -1,42 +0,0 @@
-/**
- * Node HTTP convenience starter.
- *
- * Dynamically imports `@hono/node-server` so the SDK stays runtime-agnostic
- * — only Node consumers actually pull in the dep. For Bun / Deno /
- * Cloudflare, consumers go through `server.app.fetch` directly.
- */
-
-import type { serve as nodeServe } from '@hono/node-server'
-import type { Hono } from 'hono'
-
-import type { RemoteServerHandle } from './handle.js'
-
-export async function startNodeServer(app: Hono, port = 3000): Promise<RemoteServerHandle> {
-  // Opaque specifier: the `./server` barrel re-exports this module, so worker
-  // bundles (wrangler/esbuild) traverse it even though they never call it. A
-  // literal import() would make them resolve the optional peer and fail.
-  const nodeServerModule = '@hono/node-server'
-  const { serve } = (await import(nodeServerModule)) as { serve: typeof nodeServe }
-  // oxlint-disable-next-line no-explicit-any
-  const server = serve({ fetch: app.fetch, port }) as any
-
-  await new Promise<void>((resolve, reject) => {
-    if (server.listening) return resolve()
-    server.once('listening', () => resolve())
-    // Without this, a bind failure (e.g. EADDRINUSE on a busy port) emits
-    // `'error'` and never `'listening'`, leaving the Promise — and startup —
-    // hung forever with no diagnostic.
-    server.once('error', (err: Error) => reject(err))
-  })
-
-  const address = server.address() as { port: number; address: string } | null
-  const actualPort = address?.port ?? port
-
-  return {
-    port: actualPort,
-    close: () =>
-      new Promise<void>((resolve, reject) => {
-        server.close((err: Error | null) => (err ? reject(err) : resolve()))
-      }),
-  }
-}

package/src/server/worker-entry.ts

@@ -1,286 +0,0 @@
-/**
- * `createWorkerEntry` — the shared worker `fetch` plumbing every Astrale domain
- * worker (and the cloudflare adapter's codegen) needs, so it lives in ONE place
- * instead of being copy-pasted per worker:
- *
- *   • resolve the serving URL (== `iss`), canonicalize it (so the value matches
- *     what `createRemoteServer` signs with and the kernel pins), and cache the
- *     built app per distinct URL;
- *   • optional subrequest routing: a `globalThis.fetch` override (installed ONLY
- *     when `selfBinding` and/or `routeSubrequest` is configured) redirects
- *     certain outbound fetches through a caller-supplied binding — `selfBinding`
- *     for same-host fetches (a Worker can't fetch its own hostname), and the
- *     vendor-neutral `routeSubrequest` for any caller policy (e.g. instance
- *     hostnames a same-zone Worker→Worker fetch would 522 on). The SDK names no
- *     backend or topology; the caller owns the predicate + the fetcher;
- *   • optional SPA hook (e.g. `/ui/*` served from an `ASSETS` binding).
- *
- * The worker's OWN JWKS (`<url>/.well-known/jwks.json`) is served as a normal
- * route by `createRemoteServer`; the verifier resolves a self-issued credential
- * from the in-memory key (see `auth/verify.ts`), so no self-fetch shim is needed.
- *
- * The worker file is then just schema + methods + a `build(url, env)` callback.
- */
-
-import type { ExecutionContext } from 'hono'
-
-import type { RemoteServerConfig } from './config.js'
-
-import { createRemoteServer } from './create.js'
-import { requireEnv } from './require-env.js'
-import { canonicalizeServingUrl } from './serving-url.js'
-
-export type Fetcher = { fetch(request: Request): Response | Promise<Response> }
-export type WorkerApp = {
-  fetch(
-    request: Request,
-    env?: unknown,
-    executionCtx?: ExecutionContext,
-  ): Response | Promise<Response>
-}
-
-/** A built app cached by its serving URL: `origin` for same-origin matching,
- * `app` for in-process self-dispatch. */
-type CachedApp = { origin: string; app: WorkerApp }
-
-/**
- * Choose where an OUTBOUND subrequest to `u` is routed — or `null` to let the
- * real `fetch` handle it. Order matters and same-origin wins FIRST: a call to
- * this worker's OWN serving origin is a self-dispatch, not an edge fetch — and
- * the caller's `routeSubrequest` policy may itself match our own host (e.g. an
- * `isInstanceHost` predicate matches every `*.svc.astrale.ai`, ours included),
- * so it must never get first look at a same-origin call.
- *
- *   • same-origin + SELF binding present → the SELF fetcher: a fresh same-script
- *     invocation. The normal Cloudflare path — a Worker can't fetch its own
- *     hostname over the edge, so it re-enters itself through the binding.
- *   • same-origin + NO SELF binding → the cached app, dispatched IN-PROCESS. A
- *     Workers-for-Platforms dispatch-namespace tenant can't service-bind to
- *     itself (its script name is platform-renamed), so it has no SELF binding; an
- *     in-process dispatch reaches the same script with no edge hop and no binding.
- *     `App` and the SELF `Fetcher` share the `{ fetch(request) }` shape, so the
- *     caller drives both identically.
- *   • else, the caller's `routeSubrequest` policy matched → its fetcher.
- *   • else → `null`: passthrough to the real network fetch.
- *
- * Pure (no closure over instance state) so the routing decision is unit-testable
- * without standing up a real app.
- */
-export function selectSubrequestTarget<TDeps>(
-  u: URL,
-  ctx: {
-    self: Fetcher | null
-    apps: Iterable<CachedApp>
-    routeEnv: TDeps | null
-    routeSubrequest?: (url: URL, env: TDeps) => Fetcher | null | undefined
-  },
-): { fetch(request: Request): Response | Promise<Response> } | null {
-  // Same-origin self-subrequest → the same script (SELF binding, else in-process).
-  for (const cached of ctx.apps) {
-    if (cached.origin === u.origin) return ctx.self ?? cached.app
-  }
-  // Caller policy (e.g. a platform router on the same zone) → its fetcher.
-  if (ctx.routeSubrequest && ctx.routeEnv) {
-    const via = ctx.routeSubrequest(u, ctx.routeEnv)
-    if (via) return via
-  }
-  return null
-}
-
-export interface WorkerEntryConfig<TDeps> {
-  /**
-   * Build the `createRemoteServer` config for the resolved serving `url`. Called
-   * once per distinct URL (the resulting app is cached), with the same `env` the
-   * request carries — so it can read additional bindings (e.g. a base domain).
-   */
-  build: (url: string, env: TDeps) => RemoteServerConfig<TDeps>
-  /**
-   * Resolve the raw serving URL from `env` (+ the per-request origin, for workers
-   * that fall back to the request host). Defaults to the `WORKER_URL` env var.
-   * The result is always canonicalized before use.
-   *
-   * The `requestOrigin` honors an `X-Forwarded-Proto: https` upgrade (see
-   * `clientOrigin`), so a dev worker behind a TLS-terminating proxy (cloudflared
-   * tunnel, reverse proxy) resolves its public `https://` origin, not the raw
-   * `http://` one workerd sees.
-   */
-  resolveUrl?: (env: TDeps, requestOrigin: string) => string
-  /** Optional: the `SELF` service binding used to route same-host subrequests. */
-  selfBinding?: (env: TDeps) => Fetcher | null | undefined
-  /**
-   * Optional, vendor-neutral: route an OUTBOUND subrequest through a
-   * caller-supplied fetcher instead of the network — for hosts a Worker can't
-   * reach directly over the edge (e.g. a platform router on the SAME zone:
-   * Cloudflare 522s a same-zone Worker→Worker public `fetch`). Return a `Fetcher`
-   * to route the request through, or null/undefined to fall through to the normal
-   * fetch. The SDK names no backend or topology — the CALLER owns BOTH the
-   * predicate (which hosts) and the fetcher (the binding). This generalizes
-   * `selfBinding` (same-origin → SELF) to any caller policy; both are honored.
-   */
-  routeSubrequest?: (url: URL, env: TDeps) => Fetcher | null | undefined
-  /**
-   * Optional: handle a request before it reaches the kernel app — e.g. serve a
-   * SPA under `/ui/*` or a same-origin `/api/*` endpoint the view calls. Return
-   * a `Response` to short-circuit, or `undefined` to fall through to the domain
-   * dispatch.
-   */
-  before?: (
-    env: TDeps,
-    url: URL,
-    request: Request,
-  ) => Response | undefined | Promise<Response | undefined>
-  /**
-   * Optional: transform the request on the fall-through path, just before it
-   * reaches the kernel app (e.g. rewrite the hostname for wildcard-subdomain
-   * routing). Not applied when `before` short-circuits.
-   */
-  rewriteRequest?: (env: TDeps, request: Request) => Request
-}
-
-export interface AppWorkerEntryConfig<TDeps> extends Omit<WorkerEntryConfig<TDeps>, 'build'> {
-  buildApp: (url: string, env: TDeps) => WorkerApp
-}
-
-export interface WorkerEntry<TDeps> {
-  fetch(request: Request, env: TDeps, executionCtx?: ExecutionContext): Response | Promise<Response>
-}
-
-/**
- * The request origin as the CLIENT reached it — i.e. the origin a fallback
- * serving URL (and therefore the `iss`) may be derived from. Behind a
- * TLS-terminating proxy (a cloudflared tunnel in front of `wrangler dev`, any
- * reverse proxy) the worker sees plain HTTP, so `request.url` says `http://…`
- * while the public URL is `https://…`; the proxy advertises the original
- * scheme via `X-Forwarded-Proto`. Honoring it is restricted to the http→https
- * UPGRADE of the SAME host (never a downgrade, never a host change), so a
- * spoofed header can at worst derive an `iss` the kernel's JWKS check then
- * fails — it can never make this worker speak for another origin.
- */
-export function clientOrigin(url: URL, request: Request): string {
-  if (url.protocol !== 'http:') return url.origin
-  const forwarded = request.headers.get('x-forwarded-proto')
-  // Multiple proxies append: "https, http" — the first hop is the client-facing one.
-  const scheme = forwarded?.split(',')[0]?.trim().toLowerCase()
-  return scheme === 'https' ? `https://${url.host}` : url.origin
-}
-
-/**
- * Build a `before` hook that serves a static-asset `binding` (e.g. a Workers
- * Assets binding) mounted under `base` (default `/ui`) — the runtime half of an
- * adapter env's client-asset config. Returns `undefined` for non-matching paths
- * (and when no binding is present) so the request falls through to domain dispatch.
- *
- * Asset URLs are rooted at `base` (a client bundler sets `base: '<base>/'`);
- * this hook strips that prefix before delegating to the binding, so
- * `<base>/x.js` resolves from the binding's root. When `devProxy` yields a URL
- * (local dev), requests are proxied there instead — the seam for a bundler's
- * HMR dev server. Whether unknown sub-paths fall back to `index.html` is the
- * binding's own concern (e.g. wrangler's `not_found_handling`), not baked in
- * here.
- *
- * Lives here, type-checked and testable, instead of being emitted as a string
- * by every adapter's worker codegen.
- */
-export function assets<TDeps>(opts: {
-  base?: string
-  binding: (env: TDeps) => Fetcher | null | undefined
-  devProxy?: (env: TDeps) => string | null | undefined
-}): (env: TDeps, url: URL, request: Request) => Response | Promise<Response> | undefined {
-  const base = (opts.base ?? '/ui').replace(/\/+$/, '')
-  const prefix = `${base}/`
-  return (env, url, request) => {
-    const binding = opts.binding(env)
-    if (!binding) return undefined
-    if (url.pathname !== base && !url.pathname.startsWith(prefix)) return undefined
-    const devUrl = opts.devProxy?.(env)
-    if (devUrl) {
-      const devBase = devUrl.replace(/\/+$/, '')
-      return fetch(new Request(`${devBase}${url.pathname}${url.search}`, request))
-    }
-    // `<base>` → `/`, `<base>/x` → `/x`: serve from the binding's root.
-    const stripped = url.pathname.slice(base.length) || '/'
-    const rewritten = new URL(stripped + url.search, url.origin)
-    return binding.fetch(new Request(rewritten, request))
-  }
-}
-
-export function createWorkerEntry<TDeps>(config: WorkerEntryConfig<TDeps>): WorkerEntry<TDeps> {
-  return createAppWorkerEntry({
-    ...config,
-    buildApp: (url, env) => createRemoteServer<TDeps>(config.build(url, env)).app,
-  })
-}
-
-export function createAppWorkerEntry<TDeps>(
-  config: AppWorkerEntryConfig<TDeps>,
-): WorkerEntry<TDeps> {
-  // Cache the built app per distinct resolved URL — plural and bounded. On the
-  // request-origin fallback the URL legitimately alternates for one worker
-  // (direct http hits vs https-upgraded tunnel hits, workers.dev + custom
-  // domain), and a single slot would tear down and rebuild the whole app on
-  // every alternation. The bound caps abuse via attacker-minted Host /
-  // X-Forwarded-Proto values on that same fallback path.
-  const MAX_CACHED_APPS = 4
-  const apps = new Map<string, CachedApp>()
-  let self: Fetcher | null = null
-  let routeEnv: TDeps | null = null
-
-  function getApp(url: string, env: TDeps): WorkerApp {
-    const cached = apps.get(url)
-    if (cached) return cached.app
-    const app = config.buildApp(url, env)
-    if (apps.size >= MAX_CACHED_APPS) {
-      const oldest = apps.keys().next().value
-      if (oldest !== undefined) apps.delete(oldest)
-    }
-    apps.set(url, { origin: new URL(url).origin, app })
-    return app
-  }
-
-  // A Worker can't fetch its own hostname over the edge, nor — on Cloudflare — a
-  // same-zone hostname routed to another Worker (the `routeSubrequest` case).
-  // When either is configured, override `globalThis.fetch` to redirect those
-  // subrequests through the right target (see `selectSubrequestTarget`). Workers
-  // with neither selfBinding nor routeSubrequest get no global mutation. (A
-  // self-issued credential's JWKS is resolved in-memory by the verifier, not
-  // fetched — see `auth/verify.ts` — so no self-JWKS shim is needed.)
-  if (config.selfBinding || config.routeSubrequest) {
-    const originalFetch = globalThis.fetch
-    globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
-      const href = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
-      try {
-        const target = selectSubrequestTarget(new URL(href), {
-          self,
-          apps: apps.values(),
-          routeEnv,
-          routeSubrequest: config.routeSubrequest,
-        })
-        if (target) return target.fetch(new Request(input, init))
-      } catch {
-        // non-absolute URL — fall through to the original fetch
-      }
-      return originalFetch(input, init)
-    }) as typeof fetch
-  }
-
-  return {
-    async fetch(request: Request, env: TDeps, executionCtx?: ExecutionContext): Promise<Response> {
-      if (config.selfBinding) self ??= config.selfBinding(env) ?? null
-      if (config.routeSubrequest) routeEnv = env
-      // Only parse the request URL when a hook actually needs it.
-      const requestUrl = config.before || config.resolveUrl ? new URL(request.url) : null
-      if (config.before && requestUrl) {
-        // Await so an async `before` that resolves to `undefined` falls through
-        // (a returned Promise<undefined> would otherwise be sent as the response).
-        const handled = await config.before(env, requestUrl, request)
-        if (handled !== undefined) return handled
-      }
-      const raw = config.resolveUrl
-        ? config.resolveUrl(env, clientOrigin(requestUrl!, request))
-        : requireEnv(env, 'WORKER_URL', "the worker's public serving URL (its iss identity)")
-      const url = canonicalizeServingUrl(raw)
-      const dispatched = config.rewriteRequest ? config.rewriteRequest(env, request) : request
-      return getApp(url, env).fetch(dispatched, env, executionCtx)
-    },
-  }
-}

package/src/service/functions.ts

@@ -1,164 +0,0 @@
-import type { FunctionBinding } from '@astrale-os/kernel-api/routed'
-import type { FunctionSchema } from '@astrale-os/kernel-core/domain'
-
-import { deriveAllowedAlgorithms } from '@astrale-os/kernel-core'
-import { functionBindingSchema, functionOutputSchema } from '@astrale-os/kernel-core/domain'
-import { importJWK, jwtVerify } from 'jose'
-import { z } from 'zod'
-
-import type { RemoteIdentityConfig } from '../auth/identity.js'
-
-import { signCredential } from '../auth/sign.js'
-
-export const SERVICE_FUNCTIONS_PATH = '/_astrale/functions'
-export const SERVICE_FUNCTIONS_PURPOSE = 'astrale.service-functions.v1'
-
-const JsonSchema = z.record(z.string(), z.unknown())
-
-export const ServiceFunctionManifestEntrySchema = z.object({
-  slug: z.string().regex(/^[a-z][a-z0-9-]*$/),
-  ref: z.string().regex(/^function\.[a-z][a-z0-9-]*$/),
-  inputSchema: JsonSchema,
-  outputSchema: JsonSchema,
-  output: functionOutputSchema.default('value'),
-  binding: functionBindingSchema.unwrap(),
-})
-
-export const ServiceFunctionManifestSchema = z.object({
-  version: z.literal(1),
-  service: z.object({ issuer: z.string().min(1), subject: z.string().min(1) }),
-  functions: z.array(ServiceFunctionManifestEntrySchema).max(500),
-})
-
-export const ServiceFunctionDiscoveryRequestSchema = z.object({
-  kernelIssuer: z.string().url(),
-  nonce: z.string().min(16).max(256),
-})
-
-export const ServiceFunctionDiscoveryResponseSchema = ServiceFunctionManifestSchema.extend({
-  identity: z.object({ credential: z.string().min(1) }),
-})
-
-export type ServiceFunctionManifestEntry = z.infer<typeof ServiceFunctionManifestEntrySchema>
-export type ServiceFunctionManifest = z.infer<typeof ServiceFunctionManifestSchema>
-export type ServiceFunctionDiscoveryRequest = z.infer<typeof ServiceFunctionDiscoveryRequestSchema>
-export type ServiceFunctionDiscoveryResponse = z.infer<
-  typeof ServiceFunctionDiscoveryResponseSchema
->
-
-export function toServiceFunctionManifestEntries(
-  schemas: readonly FunctionSchema[],
-): ServiceFunctionManifestEntry[] {
-  return schemas
-    .map((schema) => {
-      const slug = schema.ref.slice('function.'.length)
-      return ServiceFunctionManifestEntrySchema.parse({
-        slug,
-        ref: schema.ref,
-        inputSchema: schema.inputSchema,
-        outputSchema: schema.outputSchema,
-        output: schema.output ?? 'value',
-        binding: schema.binding,
-      })
-    })
-    .sort((a, b) => a.slug.localeCompare(b.slug))
-}
-
-export async function signServiceFunctionManifest(
-  manifest: ServiceFunctionManifest,
-  request: ServiceFunctionDiscoveryRequest,
-  identity: RemoteIdentityConfig,
-): Promise<ServiceFunctionDiscoveryResponse> {
-  const parsedManifest = ServiceFunctionManifestSchema.parse(manifest)
-  const manifestHash = await hashServiceFunctionManifest(parsedManifest)
-  const credential = await signCredential(
-    { purpose: SERVICE_FUNCTIONS_PURPOSE, nonce: request.nonce, manifestHash },
-    {
-      issuer: identity.issuer,
-      subject: identity.subject,
-      audience: request.kernelIssuer,
-      privateKey: identity.privateKey,
-      ttl: '2m',
-    },
-  )
-  return { ...parsedManifest, identity: { credential } }
-}
-
-export async function verifyServiceFunctionManifest(
-  input: unknown,
-  expected: {
-    kernelIssuer: string
-    nonce: string
-    serviceIssuer: string
-    serviceSubject: string
-    publicKey: JsonWebKey
-  },
-): Promise<ServiceFunctionDiscoveryResponse> {
-  const response = ServiceFunctionDiscoveryResponseSchema.parse(input)
-  if (
-    response.service.issuer !== expected.serviceIssuer ||
-    response.service.subject !== expected.serviceSubject
-  ) {
-    throw new Error('service function manifest identity does not match the deployed Service')
-  }
-
-  const algorithms = deriveAllowedAlgorithms(expected.publicKey)
-  const algorithm = algorithms[0]
-  if (!algorithm) throw new Error('service function manifest public key has no supported algorithm')
-  const key = await importJWK(expected.publicKey, algorithm)
-  const verified = await jwtVerify(response.identity.credential, key, {
-    algorithms,
-    issuer: expected.serviceIssuer,
-    subject: expected.serviceSubject,
-    audience: expected.kernelIssuer,
-  })
-  const expectedHash = await hashServiceFunctionManifest({
-    version: response.version,
-    service: response.service,
-    functions: response.functions,
-  })
-  if (verified.payload.purpose !== SERVICE_FUNCTIONS_PURPOSE) {
-    throw new Error('service function manifest credential has the wrong purpose')
-  }
-  if (verified.payload.nonce !== expected.nonce) {
-    throw new Error('service function manifest credential has the wrong nonce')
-  }
-  if (verified.payload.manifestHash !== expectedHash) {
-    throw new Error('service function manifest credential does not cover the returned manifest')
-  }
-  return response
-}
-
-export async function hashServiceFunctionManifest(
-  manifest: ServiceFunctionManifest,
-): Promise<string> {
-  const bytes = new TextEncoder().encode(
-    canonicalJson(ServiceFunctionManifestSchema.parse(manifest)),
-  )
-  const digest = await crypto.subtle.digest('SHA-256', bytes)
-  return `sha256:${hex(new Uint8Array(digest))}`
-}
-
-export function functionBindingForManifest(
-  binding: FunctionBinding,
-  auth: 'required' | 'optional' | 'public' | undefined,
-): FunctionBinding {
-  return { ...binding, auth: auth ?? 'required' }
-}
-
-function canonicalJson(value: unknown): string {
-  if (value === null || typeof value !== 'object') return JSON.stringify(value)
-  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`
-  const entries = Object.entries(value as Record<string, unknown>)
-    .filter(([, item]) => item !== undefined)
-    .sort(([a], [b]) => a.localeCompare(b))
-  return `{${entries
-    .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`)
-    .join(',')}}`
-}
-
-function hex(bytes: Uint8Array): string {
-  let value = ''
-  for (const byte of bytes) value += byte.toString(16).padStart(2, '0')
-  return value
-}

package/src/service/index.ts

@@ -1,18 +0,0 @@
-export {
-  SERVICE_FUNCTIONS_PATH,
-  SERVICE_FUNCTIONS_PURPOSE,
-  ServiceFunctionDiscoveryRequestSchema,
-  ServiceFunctionDiscoveryResponseSchema,
-  ServiceFunctionManifestEntrySchema,
-  ServiceFunctionManifestSchema,
-  hashServiceFunctionManifest,
-  signServiceFunctionManifest,
-  toServiceFunctionManifestEntries,
-  verifyServiceFunctionManifest,
-} from './functions.js'
-export type {
-  ServiceFunctionDiscoveryRequest,
-  ServiceFunctionDiscoveryResponse,
-  ServiceFunctionManifest,
-  ServiceFunctionManifestEntry,
-} from './functions.js'

package/src/step/index.ts

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

package/src/step/inline.ts

@@ -1,38 +0,0 @@
-import type { Step, StepRun, StepScope } from './step.js'
-
-import { buildStepRun, roundTripStepResult } from './step.js'
-
-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

@@ -1,95 +0,0 @@
-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
-}