@beignet/core 0.0.31 → 0.0.33

package/src/tasks/index.ts

@@ -1,4 +1,6 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { runWithResolvedTracingContext } from "../tracing/execution.js";
+import type { TracingPort } from "../tracing/index.js";
 
 /**
  * Any Standard Schema compatible validator.
@@ -75,9 +77,7 @@ export interface TaskHandleArgs<T extends TaskDef, Ctx> {
    * Parsed task input.
    */
   input: InferTaskInput<T>;
-  /**
-   * Handler context.
-   */
+  /** Handler context. */
   ctx: Ctx;
 }
 
@@ -115,10 +115,10 @@ export interface RunTaskOptions<Ctx> {
    * handler runs.
    */
   input: unknown;
-  /**
-   * Handler context.
-   */
-  ctx: Ctx;
+  /** Handler context or factory resolved inside the task span. */
+  ctx: Ctx | (() => MaybePromise<Ctx>);
+  /** Runtime tracing port used before a lazy context factory runs. */
+  tracing?: TracingPort;
 }
 
 /**
@@ -260,12 +260,29 @@ export async function runTask<
   T extends TaskDef<string, StandardSchema, Ctx>,
   Ctx,
 >(task: T, options: RunTaskOptions<Ctx>): Promise<InferTaskOutput<T>> {
-  const parsed = await parseTaskInput(task, options.input);
-  return (await task.handle({
-    task,
-    input: parsed,
+  const traceAttributes = {
+    "beignet.task.name": task.name,
+  } as const;
+
+  return await runWithResolvedTracingContext({
+    tracing: options.tracing,
     ctx: options.ctx,
-  })) as InferTaskOutput<T>;
+    operation: {
+      name: `beignet.task ${task.name}`,
+      type: "task",
+      kind: "internal",
+      attributes: traceAttributes,
+      metricAttributes: traceAttributes,
+    },
+    run: async (ctx) => {
+      const parsed = await parseTaskInput(task, options.input);
+      return (await task.handle({
+        task,
+        input: parsed,
+        ctx,
+      })) as InferTaskOutput<T>;
+    },
+  });
 }
 
 /**

package/src/tenancy/index.ts

@@ -0,0 +1,55 @@
+import type { ActivityTenant } from "../ports/audit.js";
+import { type RequireOptions, requireTenant } from "../ports/auth.js";
+
+const tenantScopeBrand = Symbol("TenantScope");
+
+/**
+ * Branded tenant scope token for repository boundaries.
+ *
+ * Apps still own tenant resolution and tenant data modeling. `TenantScope`
+ * carries the already-resolved activity tenant through app-facing repository
+ * ports so adapters can apply tenant predicates without accepting arbitrary
+ * caller-provided tenant IDs.
+ */
+export type TenantScope = Readonly<{
+  id: string;
+  tenant: ActivityTenant;
+  readonly [tenantScopeBrand]: true;
+}>;
+
+/**
+ * Create a tenant scope from a resolved activity tenant.
+ *
+ * This does not load, create, or validate a tenant record. It only brands the
+ * already-resolved tenant for repository and adapter boundaries.
+ */
+export function createTenantScope(tenant: ActivityTenant): TenantScope {
+  return {
+    id: tenant.id,
+    tenant,
+    [tenantScopeBrand]: true,
+  };
+}
+
+/**
+ * Return a branded tenant scope from `ctx.tenant` or throw.
+ *
+ * Throws `TenantRequiredError` by default through `requireTenant`. Pass
+ * `options.error` to throw an app-owned error instead.
+ */
+export function requireTenantScope(
+  ctx: { tenant?: ActivityTenant | null },
+  options?: RequireOptions,
+): TenantScope {
+  return createTenantScope(requireTenant(ctx, options));
+}
+
+/**
+ * Extract the stable tenant ID from a tenant scope.
+ *
+ * Repository adapters should use this helper at the persistence boundary
+ * instead of accepting raw tenant IDs from use cases.
+ */
+export function tenantScopeId(scope: TenantScope): string {
+  return scope.id;
+}

package/src/testing/index.ts

@@ -66,6 +66,7 @@ import type {
 } from "../providers/provider.js";
 import { createMemorySearch, type MemorySearchPort } from "../search/index.js";
 import { createAmbientAuditLog } from "../server/audit-context.js";
+import { loadProviderConfig } from "../server/providers/loadProviderConfig.js";
 import {
   clearActiveRequestContext,
   enterActiveRequestContext,
@@ -377,8 +378,10 @@ export function createTestPorts<
   const errorReporter = createMemoryErrorReporter();
   const flags = createMemoryFlags();
   const { jobs, dispatchedJobs } = createRecordingJobDispatcher();
-  const idempotency = createMemoryIdempotencyStore();
   const ids = options.ids ?? createUuidIdGenerator();
+  const idempotency = createMemoryIdempotencyStore({
+    now: () => clock.now(),
+  });
   const logger = createNoopLogger();
   const locks = createMemoryLocks({
     now: () => clock.now(),
@@ -386,7 +389,10 @@ export function createTestPorts<
   });
   const mailer = createMemoryMailer();
   const notifications = createMemoryNotificationPort();
-  const outbox = createMemoryOutbox();
+  const outbox = createMemoryOutbox({
+    id: () => ids.nextId(),
+    now: () => clock.now(),
+  });
   const payments = createMemoryPayments();
   const rateLimit = createMemoryRateLimiter();
   const search = createMemorySearch();
@@ -983,6 +989,12 @@ function createUnboundPortGuard<Ports extends AnyPorts>(ports: Ports): Ports {
  * Options for `installProviderForTest(...)`.
  */
 export interface InstallProviderForTestOptions {
+  /**
+   * Environment variables used to resolve the provider's config through the
+   * same loader the server uses (including the provider's `overrides`).
+   * Ignored when `config` is passed explicitly.
+   */
+  env?: Record<string, string | undefined>;
   /**
    * Base app ports visible to provider setup, such as `{ devtools }`.
    */
@@ -1047,9 +1059,13 @@ export async function installProviderForTest(
           "Pass createServiceContext to installProviderForTest(...) when the test needs a service context.",
       );
     });
+  const config =
+    options.config !== undefined
+      ? options.config
+      : await loadProviderConfig(provider, options.env ?? {}, {});
   const result = await provider.setup({
     ports: basePorts,
-    config: options.config,
+    config,
     createServiceContext,
   });
   const ports: Record<string, unknown> = { ...basePorts, ...result.ports };

package/src/tracing/execution.ts

@@ -0,0 +1,37 @@
+import {
+  resolveTracingPort,
+  runWithTracing,
+  type TraceOperation,
+  type TraceSpan,
+  type TracingPort,
+} from "./index.js";
+
+type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Resolve a lazy application context inside a span when the runtime tracing
+ * port is available independently from that context.
+ */
+export async function runWithResolvedTracingContext<Ctx, Result>(args: {
+  tracing?: TracingPort;
+  ctx: Ctx | (() => MaybePromise<Ctx>);
+  operation: TraceOperation;
+  run(ctx: Ctx, span?: TraceSpan): MaybePromise<Result>;
+}): Promise<Result> {
+  const resolveContext = async (): Promise<Ctx> =>
+    typeof args.ctx === "function"
+      ? await (args.ctx as () => MaybePromise<Ctx>)()
+      : args.ctx;
+
+  if (args.tracing) {
+    return await runWithTracing(args.tracing, args.operation, async (span) =>
+      args.run(await resolveContext(), span),
+    );
+  }
+
+  const ctx = await resolveContext();
+  const tracing = resolveTracingPort(ctx);
+  return await runWithTracing(tracing, args.operation, (span) =>
+    args.run(ctx, span),
+  );
+}

package/src/tracing/index.ts

@@ -30,6 +30,10 @@ export interface TraceContext {
    * W3C traceparent header value.
    */
   traceparent: string;
+  /**
+   * Optional W3C tracestate value associated with this context.
+   */
+  tracestate?: string;
 }
 
 /**
@@ -62,6 +66,137 @@ export interface TraceContextInput {
   spanId?: string;
   parentSpanId?: string;
   traceparent?: string;
+  tracestate?: string;
+}
+
+/** Values accepted as tracing attributes. */
+export type TraceAttributeValue =
+  | string
+  | number
+  | boolean
+  | readonly string[]
+  | readonly number[]
+  | readonly boolean[];
+
+/** Attributes attached to a traced Beignet operation. */
+export type TraceAttributes = Readonly<Record<string, TraceAttributeValue>>;
+
+/** Span kinds understood by tracing providers. */
+export type TraceSpanKind =
+  | "internal"
+  | "server"
+  | "client"
+  | "producer"
+  | "consumer";
+
+/** Stable Beignet operation categories used by tracing and metrics providers. */
+export type TraceOperationType =
+  | "request"
+  | "useCase"
+  | "listener"
+  | "job"
+  | "schedule"
+  | "task"
+  | "outbox"
+  | "provider";
+
+/** Description of one operation to run inside an active trace span. */
+export interface TraceOperation {
+  name: string;
+  type: TraceOperationType;
+  kind?: TraceSpanKind;
+  parent?: TraceContextInput;
+  /** Attributes attached to the operation span. */
+  attributes?: TraceAttributes;
+  /**
+   * Bounded attributes attached to operation metrics. Values must describe a
+   * stable operation dimension, never a request, actor, tenant, or payload.
+   */
+  metricAttributes?: TraceAttributes;
+}
+
+/** Framework-neutral span handle exposed to Beignet execution wrappers. */
+export interface TraceSpan {
+  readonly context: TraceContext;
+  setAttribute(name: string, value: TraceAttributeValue): void;
+  setAttributes(attributes: TraceAttributes): void;
+  addEvent(name: string, attributes?: TraceAttributes): void;
+  setStatus(status: "ok" | "error"): void;
+  recordError(error: unknown): void;
+}
+
+/** Optional app port implemented by production tracing integrations. */
+export interface TracingPort {
+  current(): TraceContext | undefined;
+  startActiveSpan<T>(operation: TraceOperation, run: (span: TraceSpan) => T): T;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/** Return whether a value implements `TracingPort`. */
+export function isTracingPort(value: unknown): value is TracingPort {
+  return (
+    isObject(value) &&
+    "current" in value &&
+    "startActiveSpan" in value &&
+    typeof value.current === "function" &&
+    typeof value.startActiveSpan === "function"
+  );
+}
+
+/** Resolve a tracing port from a direct port, ports object, or app context. */
+export function resolveTracingPort(target: unknown): TracingPort | undefined {
+  if (!target) return undefined;
+  if (isTracingPort(target)) return target;
+  if (!isObject(target)) return undefined;
+
+  const direct = "tracing" in target ? (target.tracing as unknown) : undefined;
+  if (isTracingPort(direct)) return direct;
+
+  const ports = "ports" in target ? target.ports : undefined;
+  if (!ports || ports === target) return undefined;
+  return resolveTracingPort(ports);
+}
+
+/** Resolve trace fields from a trace context or context-like object. */
+export function resolveTraceContextInput(
+  target: unknown,
+): TraceContextInput | undefined {
+  if (!isObject(target)) return undefined;
+
+  const context = target as TraceContextInput;
+  if (
+    context.traceId ||
+    context.spanId ||
+    context.parentSpanId ||
+    context.traceparent ||
+    context.tracestate
+  ) {
+    return {
+      ...(context.traceId ? { traceId: context.traceId } : {}),
+      ...(context.spanId ? { spanId: context.spanId } : {}),
+      ...(context.parentSpanId ? { parentSpanId: context.parentSpanId } : {}),
+      ...(context.traceparent ? { traceparent: context.traceparent } : {}),
+      ...(context.tracestate ? { tracestate: context.tracestate } : {}),
+    };
+  }
+
+  const traceContext = "trace" in target ? target.trace : undefined;
+  if (!traceContext || traceContext === target) return undefined;
+  return resolveTraceContextInput(traceContext);
+}
+
+/** Run a callback inside a tracing span when an app tracing port is installed. */
+export function runWithTracing<T>(
+  target: unknown,
+  operation: TraceOperation,
+  run: (span?: TraceSpan) => T,
+): T {
+  const tracing = resolveTracingPort(target);
+  if (!tracing) return run();
+  return tracing.startActiveSpan(operation, (span) => run(span));
 }
 
 function createHexId(length: number): string {
@@ -159,6 +294,7 @@ export function createTraceContext(
       spanId,
       traceFlags: parsed?.traceFlags,
     }),
+    ...(input.tracestate ? { tracestate: input.tracestate } : {}),
   };
 }
 
@@ -172,5 +308,6 @@ export function createChildTraceContext(
     traceId: parent.traceId,
     parentSpanId: parent.spanId,
     traceparent: parent.traceparent,
+    tracestate: parent.tracestate,
   });
 }

package/src/uploads/client.ts

@@ -391,6 +391,17 @@ export function createUploadClient<
     uploadName: Name,
     prepareOptions: UploadClientPrepareOptions<UploadByName<Registry, Name>>,
   ) {
+    const fileConstraints = constraints(uploadName);
+    const files = await Promise.all(
+      prepareOptions.files.map((file) =>
+        fileIntentFromFile({
+          file,
+          constraints: fileConstraints,
+          uploadName,
+        }),
+      ),
+    );
+
     return requestJson<PrepareUploadResult>({
       fetchImpl,
       url: actionUrl(baseUrl, uploadName, "prepare"),
@@ -403,7 +414,7 @@ export function createUploadClient<
         signal: prepareOptions.signal,
         body: JSON.stringify({
           metadata: prepareOptions.metadata,
-          files: prepareOptions.files.map(fileIntentFromFile),
+          files,
         }),
       },
     });
@@ -564,12 +575,28 @@ export function createUploadClient<
   };
 }
 
-function fileIntentFromFile(file: File): UploadFileIntent {
-  return {
-    name: file.name,
-    contentType: file.type || "application/octet-stream",
-    size: file.size,
+async function fileIntentFromFile(args: {
+  file: File;
+  constraints: UploadFileConstraints | undefined;
+  uploadName: string;
+}): Promise<UploadFileIntent> {
+  const contentType =
+    normalizeContentType(args.file.type) || "application/octet-stream";
+  const intent: UploadFileIntent = {
+    name: args.file.name,
+    contentType,
+    size: args.file.size,
   };
+
+  const checksumRequirement = args.constraints?.checksum;
+  if (checksumRequirement?.algorithm === "sha256") {
+    intent.checksum = await createClientUploadChecksum(args.file, {
+      uploadName: args.uploadName,
+      required: checksumRequirement.required !== false,
+    });
+  }
+
+  return intent;
 }
 
 function completeFileInput(file: PreparedUploadResultFile): PreparedUploadFile {
@@ -577,15 +604,47 @@ function completeFileInput(file: PreparedUploadResultFile): PreparedUploadFile {
     name: file.name,
     contentType: file.contentType,
     size: file.size,
+    ...(file.checksum ? { checksum: file.checksum } : {}),
     uploadId: file.uploadId,
     key: file.key,
   };
 }
 
+async function createClientUploadChecksum(
+  file: File,
+  options: { uploadName: string; required: boolean },
+): Promise<UploadFileIntent["checksum"]> {
+  if (!globalThis.crypto?.subtle) {
+    if (!options.required) return undefined;
+
+    throw new UploadClientError({
+      operation: "prepare upload",
+      uploadName: options.uploadName,
+      code: "UPLOAD_CHECKSUM_UNAVAILABLE",
+      message: `Upload "${options.uploadName}" requires Web Crypto to compute checksums.`,
+    });
+  }
+
+  const digest = await globalThis.crypto.subtle.digest(
+    "SHA-256",
+    await file.arrayBuffer(),
+  );
+  return {
+    algorithm: "sha256",
+    value: [...new Uint8Array(digest)]
+      .map((byte) => byte.toString(16).padStart(2, "0"))
+      .join(""),
+  };
+}
+
 function normalizeBaseUrl(baseUrl: string): string {
   return baseUrl.replace(/\/+$/, "");
 }
 
+function normalizeContentType(contentType: string): string {
+  return contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+}
+
 function actionUrl(
   baseUrl: string,
   uploadName: string,