@beignet/core 0.0.32 → 0.0.34

package/src/server/instrumentation.ts

@@ -12,7 +12,9 @@ import {
 import {
   createTraceContext,
   parseTraceparent,
+  resolveTracingPort,
   type TraceContext,
+  type TracingPort,
 } from "../tracing/index.js";
 import type { HttpRequestLike, HttpResponseLike, ServerHook } from "./http.js";
 import {
@@ -129,6 +131,7 @@ type TraceContextFields = {
   spanId?: string;
   parentSpanId?: string;
   traceparent?: string;
+  tracestate?: string;
 };
 
 function getContextRequestId(ctx: unknown): string | undefined {
@@ -144,7 +147,8 @@ function getContextTraceContext(ctx: unknown): TraceContextFields | undefined {
     !context.traceId &&
     !context.spanId &&
     !context.parentSpanId &&
-    !context.traceparent
+    !context.traceparent &&
+    !context.tracestate
   ) {
     return undefined;
   }
@@ -153,6 +157,7 @@ function getContextTraceContext(ctx: unknown): TraceContextFields | undefined {
     spanId: context.spanId,
     parentSpanId: context.parentSpanId,
     traceparent: context.traceparent,
+    tracestate: context.tracestate,
   };
 }
 
@@ -249,6 +254,7 @@ export function createServerInstrumentation<Ctx>(
   const ignorePaths = resolvedOptions.ignorePaths ?? ["/api/devtools"];
 
   let port: ProviderInstrumentationPort | undefined;
+  let tracing: TracingPort | undefined;
   const correlations = new WeakMap<HttpRequestLike, RequestCorrelation>();
 
   const prepareRequest = (req: HttpRequestLike): RequestCorrelation => {
@@ -263,12 +269,19 @@ export function createServerInstrumentation<Ctx>(
       traceContextHeader === false
         ? undefined
         : (req.headers.get(traceContextHeader) ?? undefined);
+    const parsedTraceparent = parseTraceparent(headerTraceparent);
 
+    const activeTrace = tracing?.current();
     const correlation: RequestCorrelation = {
       requestId: headerRequestId ?? createRequestId(),
-      trace: createTraceContext({
-        traceparent: parseTraceparent(headerTraceparent)?.traceparent,
-      }),
+      trace:
+        activeTrace ??
+        createTraceContext({
+          traceparent: parsedTraceparent?.traceparent,
+          tracestate: parsedTraceparent
+            ? (req.headers.get("tracestate") ?? undefined)
+            : undefined,
+        }),
     };
     correlations.set(req, correlation);
     return correlation;
@@ -284,6 +297,9 @@ export function createServerInstrumentation<Ctx>(
     req: HttpRequestLike;
     ctx?: unknown;
   }): TraceContext => {
+    const activeTrace = tracing?.current();
+    if (activeTrace) return activeTrace;
+
     const contextTrace = getContextTraceContext(args.ctx);
     if (contextTrace) {
       return createTraceContext(contextTrace);
@@ -334,6 +350,7 @@ export function createServerInstrumentation<Ctx>(
       spanId: trace.spanId,
       parentSpanId: trace.parentSpanId,
       traceparent: trace.traceparent,
+      tracestate: trace.tracestate,
       actor: readContextActor(args.ctx),
       tenant: readContextTenant(args.ctx),
     });
@@ -416,6 +433,7 @@ export function createServerInstrumentation<Ctx>(
             spanId: trace.spanId,
             parentSpanId: trace.parentSpanId,
             traceparent: trace.traceparent,
+            tracestate: trace.tracestate,
             method: req.method,
             path,
             contractName: contract.name,
@@ -452,6 +470,7 @@ export function createServerInstrumentation<Ctx>(
             spanId: trace.spanId,
             parentSpanId: trace.parentSpanId,
             traceparent: trace.traceparent,
+            tracestate: trace.tracestate,
             message: getErrorMessage(error),
             stack: getErrorStack(error),
             contractName: contract.name,
@@ -466,13 +485,14 @@ export function createServerInstrumentation<Ctx>(
 
   return {
     attachPorts(ports) {
+      tracing = resolveTracingPort(ports);
       if (!enabled) return;
       port = resolveProviderInstrumentationPort(ports);
     },
     prepareRequest,
     createServiceCorrelation: () => ({
       requestId: createRequestId(),
-      trace: createTraceContext(),
+      trace: tracing?.current() ?? createTraceContext(),
     }),
     hook: enabled ? hook : undefined,
   };

package/src/server/request-context.ts

@@ -16,6 +16,7 @@ export interface ActiveRequestContext {
   spanId?: string;
   parentSpanId?: string;
   traceparent?: string;
+  tracestate?: string;
   /**
    * Actor for the current request or service execution, when known.
    */
@@ -116,7 +117,10 @@ export function inheritActiveRequestContext<
   Event extends {
     requestId?: string;
     traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
     traceparent?: string;
+    tracestate?: string;
   },
 >(event: Event): Event {
   const context = getActiveRequestContext();
@@ -126,6 +130,9 @@ export function inheritActiveRequestContext<
     ...event,
     requestId: event.requestId ?? context.requestId,
     traceId: event.traceId ?? context.traceId,
+    spanId: event.spanId ?? context.spanId,
+    parentSpanId: event.parentSpanId ?? context.parentSpanId,
     traceparent: event.traceparent ?? context.traceparent,
+    tracestate: event.tracestate ?? context.tracestate,
   };
 }

package/src/server/runtime-integrity.ts

@@ -0,0 +1,322 @@
+import type { EventPayloadDef, ListenerDef } from "../events/index.js";
+import type { JobDef } from "../jobs/index.js";
+import type { OutboxRegistry } from "../outbox/index.js";
+import type { ScheduleDef } from "../schedules/index.js";
+import type { TaskDef } from "../tasks/index.js";
+
+export type RuntimeIntegrityArtifact =
+  | "listener"
+  | "schedule"
+  | "task"
+  | "outboxEvent"
+  | "outboxJob";
+
+export type RuntimeIntegrityFindingCode =
+  | "missing_listener_registration"
+  | "missing_schedule_registration"
+  | "missing_task_registration"
+  | "missing_outbox_event_registration"
+  | "missing_outbox_job_registration"
+  | "duplicate_runtime_manifest_entry"
+  | "duplicate_runtime_registry_entry";
+
+export type RuntimeIntegrityFindingLocation = "manifest" | "registry";
+
+export interface RuntimeIntegrityFinding {
+  readonly code: RuntimeIntegrityFindingCode;
+  readonly artifact: RuntimeIntegrityArtifact;
+  readonly name: string;
+  readonly message: string;
+  readonly location?: RuntimeIntegrityFindingLocation;
+}
+
+export interface RuntimeIntegrityResult {
+  readonly ok: boolean;
+  readonly findings: readonly RuntimeIntegrityFinding[];
+}
+
+export interface RuntimeOutboxManifest {
+  readonly events?: readonly EventPayloadDef[];
+  readonly jobs?: readonly JobDef[];
+}
+
+export interface RuntimeManifestInput {
+  readonly listeners?: readonly ListenerDef[];
+  readonly schedules?: readonly ScheduleDef[];
+  readonly tasks?: readonly TaskDef[];
+  readonly outbox?: RuntimeOutboxManifest;
+}
+
+export interface RuntimeManifest {
+  readonly listeners: readonly ListenerDef[];
+  readonly schedules: readonly ScheduleDef[];
+  readonly tasks: readonly TaskDef[];
+  readonly outbox: {
+    readonly events: readonly EventPayloadDef[];
+    readonly jobs: readonly JobDef[];
+  };
+}
+
+export interface RuntimeRegistriesInput {
+  readonly listeners?: readonly ListenerDef[];
+  readonly schedules?: readonly ScheduleDef[];
+  readonly tasks?: readonly TaskDef[];
+  readonly outbox?: OutboxRegistry;
+}
+
+export interface RuntimeRegistries {
+  readonly listeners: readonly ListenerDef[];
+  readonly schedules: readonly ScheduleDef[];
+  readonly tasks: readonly TaskDef[];
+  readonly outbox?: OutboxRegistry;
+}
+
+export type RuntimeIntegrityMode = "error" | "warn";
+
+export interface RuntimeIntegrityLogger {
+  warn(message: string): void;
+}
+
+export interface CreateRuntimeIntegrityOptions {
+  readonly manifest: RuntimeManifest;
+  readonly registries: RuntimeRegistries;
+  /**
+   * How to handle integrity findings.
+   *
+   * @default "error"
+   */
+  readonly mode?: RuntimeIntegrityMode;
+  /**
+   * Logger used when `mode` is `"warn"`.
+   *
+   * @default console
+   */
+  readonly logger?: RuntimeIntegrityLogger;
+}
+
+export interface RuntimeIntegrityCheck {
+  readonly kind: "runtime-integrity";
+  check(): RuntimeIntegrityResult;
+}
+
+type NamedDefinition = {
+  readonly name: string;
+};
+
+type IntegrityArtifactConfig = {
+  readonly artifact: RuntimeIntegrityArtifact;
+  readonly label: string;
+  readonly manifestNames: readonly string[];
+  readonly registryNames: readonly string[];
+  readonly missingCode: RuntimeIntegrityFindingCode;
+  readonly registryDescription: string;
+};
+
+export class RuntimeIntegrityError extends Error {
+  readonly findings: readonly RuntimeIntegrityFinding[];
+
+  constructor(findings: readonly RuntimeIntegrityFinding[]) {
+    super(formatRuntimeIntegrityFailure(findings));
+    this.name = "RuntimeIntegrityError";
+    this.findings = findings;
+  }
+}
+
+export function defineRuntimeManifest(
+  input: RuntimeManifestInput,
+): RuntimeManifest {
+  return {
+    listeners: input.listeners ?? [],
+    schedules: input.schedules ?? [],
+    tasks: input.tasks ?? [],
+    outbox: {
+      events: input.outbox?.events ?? [],
+      jobs: input.outbox?.jobs ?? [],
+    },
+  };
+}
+
+export function defineRuntimeRegistries(
+  input: RuntimeRegistriesInput,
+): RuntimeRegistries {
+  return {
+    listeners: input.listeners ?? [],
+    schedules: input.schedules ?? [],
+    tasks: input.tasks ?? [],
+    outbox: input.outbox,
+  };
+}
+
+export function inspectRuntimeIntegrity(
+  manifest: RuntimeManifest,
+  registries: RuntimeRegistries,
+): RuntimeIntegrityResult {
+  const configs: readonly IntegrityArtifactConfig[] = [
+    {
+      artifact: "listener",
+      label: "listener",
+      manifestNames: namesFromDefinitions(manifest.listeners),
+      registryNames: namesFromDefinitions(registries.listeners),
+      missingCode: "missing_listener_registration",
+      registryDescription: "runtime registries.listeners",
+    },
+    {
+      artifact: "schedule",
+      label: "schedule",
+      manifestNames: namesFromDefinitions(manifest.schedules),
+      registryNames: namesFromDefinitions(registries.schedules),
+      missingCode: "missing_schedule_registration",
+      registryDescription: "runtime registries.schedules",
+    },
+    {
+      artifact: "task",
+      label: "task",
+      manifestNames: namesFromDefinitions(manifest.tasks),
+      registryNames: namesFromDefinitions(registries.tasks),
+      missingCode: "missing_task_registration",
+      registryDescription: "runtime registries.tasks",
+    },
+    {
+      artifact: "outboxEvent",
+      label: "outbox event",
+      manifestNames: namesFromDefinitions(manifest.outbox.events),
+      registryNames: namesFromMap(registries.outbox?.events),
+      missingCode: "missing_outbox_event_registration",
+      registryDescription: "runtime registries.outbox.events",
+    },
+    {
+      artifact: "outboxJob",
+      label: "outbox job",
+      manifestNames: namesFromDefinitions(manifest.outbox.jobs),
+      registryNames: namesFromMap(registries.outbox?.jobs),
+      missingCode: "missing_outbox_job_registration",
+      registryDescription: "runtime registries.outbox.jobs",
+    },
+  ];
+
+  const findings = configs.flatMap((config) =>
+    inspectArtifactIntegrity(config),
+  );
+
+  return {
+    ok: findings.length === 0,
+    findings,
+  };
+}
+
+export function createRuntimeIntegrity(
+  options: CreateRuntimeIntegrityOptions,
+): RuntimeIntegrityCheck {
+  const mode = options.mode ?? "error";
+  const logger = options.logger ?? console;
+
+  return {
+    kind: "runtime-integrity",
+    check() {
+      const result = inspectRuntimeIntegrity(
+        options.manifest,
+        options.registries,
+      );
+
+      if (result.ok) return result;
+
+      if (mode === "warn") {
+        logger.warn(
+          `[beignet] ${formatRuntimeIntegrityFailure(result.findings)}`,
+        );
+        return result;
+      }
+
+      throw new RuntimeIntegrityError(result.findings);
+    },
+  };
+}
+
+export function runRuntimeIntegrityCheck(
+  check: RuntimeIntegrityCheck | undefined,
+): RuntimeIntegrityResult | undefined {
+  return check?.check();
+}
+
+function inspectArtifactIntegrity(
+  config: IntegrityArtifactConfig,
+): RuntimeIntegrityFinding[] {
+  const findings: RuntimeIntegrityFinding[] = [];
+  const manifestDuplicates = duplicateNames(config.manifestNames);
+  const registryDuplicates = duplicateNames(config.registryNames);
+
+  for (const name of manifestDuplicates) {
+    findings.push({
+      code: "duplicate_runtime_manifest_entry",
+      artifact: config.artifact,
+      name,
+      location: "manifest",
+      message: `Duplicate ${config.label} "${name}" in runtime manifest.`,
+    });
+  }
+
+  for (const name of registryDuplicates) {
+    findings.push({
+      code: "duplicate_runtime_registry_entry",
+      artifact: config.artifact,
+      name,
+      location: "registry",
+      message: `Duplicate ${config.label} "${name}" in ${config.registryDescription}.`,
+    });
+  }
+
+  const registryNameSet = new Set(config.registryNames);
+  for (const name of uniqueNames(config.manifestNames)) {
+    if (registryNameSet.has(name)) continue;
+    findings.push({
+      code: config.missingCode,
+      artifact: config.artifact,
+      name,
+      message: `Missing ${config.label} registration "${name}": declared in runtime manifest but not present in ${config.registryDescription}.`,
+    });
+  }
+
+  return findings;
+}
+
+function namesFromDefinitions(
+  definitions: readonly NamedDefinition[] | undefined,
+): string[] {
+  return (definitions ?? []).map((definition) => definition.name);
+}
+
+function namesFromMap<T extends NamedDefinition>(
+  definitions: ReadonlyMap<string, T> | undefined,
+): string[] {
+  return [...(definitions?.keys() ?? [])];
+}
+
+function duplicateNames(names: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const duplicates = new Set<string>();
+
+  for (const name of names) {
+    if (seen.has(name)) {
+      duplicates.add(name);
+      continue;
+    }
+    seen.add(name);
+  }
+
+  return [...duplicates].sort();
+}
+
+function uniqueNames(names: readonly string[]): string[] {
+  return [...new Set(names)].sort();
+}
+
+function formatRuntimeIntegrityFailure(
+  findings: readonly RuntimeIntegrityFinding[],
+): string {
+  const summary = `Runtime integrity check failed with ${findings.length} finding${findings.length === 1 ? "" : "s"}.`;
+  const details = findings
+    .map((finding) => `- [${finding.code}] ${finding.message}`)
+    .join("\n");
+
+  return `${summary}\n${details}`;
+}

package/src/server/server.ts

@@ -44,6 +44,12 @@ import {
   resolveProviderInstrumentationPort,
   type ServiceProvider,
 } from "../providers/index.js";
+import {
+  parseTraceparent,
+  resolveTracingPort,
+  runWithTracing,
+  type TraceContextInput,
+} from "../tracing/index.js";
 import type {
   ContextSeed,
   ServerContextConfig,
@@ -87,6 +93,8 @@ import {
   runWithActiveRequestContext,
   setActiveRequestIdentity,
 } from "./request-context.js";
+import type { RuntimeIntegrityCheck } from "./runtime-integrity.js";
+import { runRuntimeIntegrityCheck } from "./runtime-integrity.js";
 import type {
   AnyUseCaseLike,
   AnyUseCaseRouteDef,
@@ -353,6 +361,15 @@ export type CreateServerOptions<
    * Server hooks that wrap every registered route.
    */
   hooks?: ServerHook<Ctx, Ports & InferProviderPorts<Providers>>[];
+  /**
+   * Optional pure startup check for app workflow registrations.
+   *
+   * Runtime integrity compares app-declared workflow artifacts against the
+   * registries passed to runtime entrypoints. It performs no filesystem,
+   * provider, database, network, worker, or background-loop work, so it is safe
+   * to run during serverless cold starts.
+   */
+  integrity?: RuntimeIntegrityCheck;
   /**
    * Server-owned request instrumentation.
    *
@@ -1192,7 +1209,7 @@ function createRequestExecutor<
   const warnedNativeReplacementHooks = new WeakSet<object>();
   const maxRequestBodyBytes = requestBodyLimit(options.requestBody);
 
-  return async (
+  const executeRequest = async (
     target: ExecutionTarget<Ctx, C>,
     req: HttpRequestLike,
     preMatchedParams?: Record<string, string>,
@@ -2131,6 +2148,72 @@ function createRequestExecutor<
       );
     }
   };
+
+  return async (
+    target: ExecutionTarget<Ctx, C>,
+    req: HttpRequestLike,
+    preMatchedParams?: Record<string, string>,
+  ) => {
+    const tracing = resolveTracingPort(finalPorts);
+    const instrumentationOptions =
+      options.instrumentation === false ? undefined : options.instrumentation;
+    const pathname = (() => {
+      try {
+        return new URL(req.url).pathname;
+      } catch {
+        return req.url;
+      }
+    })();
+    const ignored = (
+      instrumentationOptions?.ignorePaths ?? ["/api/devtools"]
+    ).some((prefix) => {
+      const normalized = prefix.replace(/\/+$/, "");
+      return pathname === normalized || pathname.startsWith(`${normalized}/`);
+    });
+
+    if (!tracing || ignored) {
+      return executeRequest(target, req, preMatchedParams);
+    }
+
+    const traceContextHeader =
+      instrumentationOptions?.traceContextHeader ?? "traceparent";
+    const active = tracing.current();
+    const parsedTraceparent =
+      traceContextHeader === false
+        ? undefined
+        : parseTraceparent(req.headers.get(traceContextHeader));
+    const parent: TraceContextInput | undefined = active
+      ? undefined
+      : !parsedTraceparent
+        ? undefined
+        : {
+            traceparent: parsedTraceparent.traceparent,
+            tracestate: req.headers.get("tracestate") ?? undefined,
+          };
+    const traceAttributes = {
+      "beignet.contract.name": target.contract.name,
+      "http.request.method": req.method.toUpperCase(),
+      "http.route": target.contract.path,
+    } as const;
+
+    return await runWithTracing(
+      tracing,
+      {
+        name: `beignet.request ${target.contract.name}`,
+        type: "request",
+        kind: active ? "internal" : "server",
+        parent,
+        attributes: traceAttributes,
+        metricAttributes: traceAttributes,
+      },
+      async (span) => {
+        const response = await executeRequest(target, req, preMatchedParams);
+        span?.setAttribute("http.response.status_code", response.status);
+        if (response.status >= 500) span?.setStatus("error");
+        return response;
+      },
+    );
+  };
 }
 
 /**
@@ -2581,6 +2664,8 @@ export async function createServer<
     }
   }
 
+  runRuntimeIntegrityCheck(options.integrity);
+
   try {
     for (const provider of providers) {
       const cfg = await loadProviderConfig(provider, env, overrides);
@@ -2856,30 +2941,7 @@ export function contractsFromRoutes<
  * });
  * ```
  */
-export function defineRouteGroup<Ctx>(): RouteGroupBuilder<Ctx>;
-/**
- * @deprecated Prefer `defineRouteGroup<Ctx>()({ ... })`. TypeScript cannot
- * infer the route tuple generic when callers provide only `Ctx`, so the direct
- * form preserves context checking but erases per-route contract output checks.
- */
-export function defineRouteGroup<
-  Ctx,
-  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-  const R extends readonly RouteDef<Ctx, any>[] = readonly RouteDef<Ctx, any>[],
->(group: {
-  name: string;
-  hooks?: readonly RouteHook<Ctx, object>[];
-  routes: R & ValidatedRouteInputs<Ctx, R>;
-}): RouteGroup<Ctx, R>;
-export function defineRouteGroup<
-  Ctx,
-  // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level
-  const R extends readonly RouteDef<any, any>[] = readonly RouteDef<any, any>[],
->(group?: {
-  name: string;
-  hooks?: readonly RouteHook<Ctx, object>[];
-  routes: R;
-}): RouteGroup<Ctx, R> | RouteGroupBuilder<Ctx> {
+export function defineRouteGroup<Ctx>(): RouteGroupBuilder<Ctx> {
   const createGroup = <
     const GroupHooks extends readonly RouteHook<Ctx, object>[] = readonly [],
     const GroupRoutes extends readonly AnyRouteDef[] = readonly AnyRouteDef[],
@@ -2894,16 +2956,7 @@ export function defineRouteGroup<
     routes: input.routes,
   });
 
-  if (!group) {
-    return createGroup;
-  }
-
-  return {
-    kind: ROUTE_GROUP_KIND,
-    name: group.name,
-    hooks: group.hooks,
-    routes: group.routes,
-  };
+  return createGroup as RouteGroupBuilder<Ctx>;
 }
 
 function isRouteGroup<Ctx>(route: RouteInput<Ctx>): route is RouteGroup<Ctx> {