@beignet/core 0.0.31 → 0.0.33

package/src/application/index.ts

@@ -5,6 +5,8 @@ import {
 } from "../providers/instrumentation.js";
 import {
   createChildTraceContext,
+  resolveTracingPort,
+  runWithTracing,
   type TraceContextInput,
 } from "../tracing/index.js";
 
@@ -482,6 +484,7 @@ function getInstrumentationTrace(ctx: unknown): TraceContextInput | undefined {
     spanId: context.spanId,
     parentSpanId: context.parentSpanId,
     traceparent: context.traceparent,
+    tracestate: context.tracestate,
   };
 }
 
@@ -517,9 +520,9 @@ function startUseCaseRunInstrumentation(args: {
   if (!useCasesEnabled && !errorsEnabled) return undefined;
 
   const requestId = getInstrumentationRequestId(args.ctx);
-  const trace = createChildTraceContext(
-    getInstrumentationTrace(args.ctx) ?? {},
-  );
+  const trace =
+    resolveTracingPort(ports)?.current() ??
+    createChildTraceContext(getInstrumentationTrace(args.ctx) ?? {});
 
   const record = (event: ProviderInstrumentationEventInput) => {
     try {
@@ -542,6 +545,7 @@ function startUseCaseRunInstrumentation(args: {
         spanId: trace.spanId,
         parentSpanId: trace.parentSpanId,
         traceparent: trace.traceparent,
+        tracestate: trace.tracestate,
         name: args.name,
         kind: args.kind,
         phase,
@@ -558,6 +562,7 @@ function startUseCaseRunInstrumentation(args: {
         spanId: trace.spanId,
         parentSpanId: trace.parentSpanId,
         traceparent: trace.traceparent,
+        tracestate: trace.tracestate,
         message: getRunErrorMessage(error),
         stack: error instanceof Error ? error.stack : undefined,
         useCaseName: args.name,
@@ -725,61 +730,88 @@ class UseCaseBuilder<
         : never,
       parseInput: boolean,
     ) => {
-      const startedAt = Date.now();
-      const instrumentation = instrumented
-        ? startUseCaseRunInstrumentation({
-            ctx: args.ctx,
+      const traceAttributes = {
+        "beignet.use_case.name": useCaseName,
+        "beignet.use_case.kind": useCaseKind,
+      } as const;
+
+      return await runWithTracing(
+        args.ctx,
+        {
+          name: `beignet.use_case ${useCaseName}`,
+          type: "useCase",
+          kind: "internal",
+          attributes: traceAttributes,
+          metricAttributes: traceAttributes,
+        },
+        async () => {
+          const startedAt = Date.now();
+          const instrumentation = instrumented
+            ? startUseCaseRunInstrumentation({
+                ctx: args.ctx,
+                name: useCaseName,
+                kind: useCaseKind,
+              })
+            : undefined;
+          onRun?.({
             name: useCaseName,
             kind: useCaseKind,
-          })
-        : undefined;
-      onRun?.({
-        name: useCaseName,
-        kind: useCaseKind,
-        phase: "start",
-        ctx: args.ctx,
-      });
-
-      try {
-        const parsedInput =
-          parseInput && validation.input
-            ? await parseSchema(inputSchema, args.input, useCaseName, "input")
-            : (args.input as SchemaOutput<InputSchema>);
-
-        const rawResult = await fn({
-          ctx: args.ctx,
-          input: parsedInput,
-          events: eventHelpers,
-        });
-
-        const result = validation.output
-          ? await parseSchema(outputSchema, rawResult, useCaseName, "output")
-          : (rawResult as SchemaOutput<OutputSchema>);
-
-        const durationMs = Date.now() - startedAt;
-        instrumentation?.end(durationMs);
-        onRun?.({
-          name: useCaseName,
-          kind: useCaseKind,
-          phase: "end",
-          durationMs,
-          ctx: args.ctx,
-        });
-
-        return result;
-      } catch (err) {
-        const durationMs = Date.now() - startedAt;
-        instrumentation?.error(durationMs, err);
-        onRun?.({
-          name: useCaseName,
-          kind: useCaseKind,
-          phase: "error",
-          durationMs,
-          error: err,
-          ctx: args.ctx,
-        });
-        throw err;
-      }
+            phase: "start",
+            ctx: args.ctx,
+          });
+
+          try {
+            const parsedInput =
+              parseInput && validation.input
+                ? await parseSchema(
+                    inputSchema,
+                    args.input,
+                    useCaseName,
+                    "input",
+                  )
+                : (args.input as SchemaOutput<InputSchema>);
+
+            const rawResult = await fn({
+              ctx: args.ctx,
+              input: parsedInput,
+              events: eventHelpers,
+            });
+
+            const result = validation.output
+              ? await parseSchema(
+                  outputSchema,
+                  rawResult,
+                  useCaseName,
+                  "output",
+                )
+              : (rawResult as SchemaOutput<OutputSchema>);
+
+            const durationMs = Date.now() - startedAt;
+            instrumentation?.end(durationMs);
+            onRun?.({
+              name: useCaseName,
+              kind: useCaseKind,
+              phase: "end",
+              durationMs,
+              ctx: args.ctx,
+            });
+
+            return result;
+          } catch (err) {
+            const durationMs = Date.now() - startedAt;
+            instrumentation?.error(durationMs, err);
+            onRun?.({
+              name: useCaseName,
+              kind: useCaseKind,
+              phase: "error",
+              durationMs,
+              error: err,
+              ctx: args.ctx,
+            });
+            throw err;
+          }
+        },
+      );
     };
 
     type RunArgs = Parameters<typeof execute>[0];

package/src/domain/entity.ts

@@ -66,9 +66,47 @@ function validateSchemaSync<T>(
 // biome-ignore lint/suspicious/noExplicitAny: Base methods type for flexibility
 type AnyMethods = Record<string, any>;
 
+/**
+ * Base entity instance passed to the `.methods(...)` builder: validated props
+ * plus the `with` and `toJSON` helpers, before domain methods attach.
+ *
+ * `with(...)` is typed as returning the base instance here because the final
+ * methods object is still being defined while the builder runs. At runtime
+ * the returned instance carries the entity's methods, and `EntityInstance`
+ * maps base-instance returns back to the full instance type so consumers keep
+ * typed method chaining.
+ */
+export type EntityBaseInstance<Schema extends StandardSchema> =
+  InferOutput<Schema> & {
+    /**
+     * Create a new validated entity instance with patched properties.
+     */
+    with(
+      patch: Partial<InferOutput<Schema>>,
+    ): EntityBaseInstance<Schema> | Promise<EntityBaseInstance<Schema>>;
+    /**
+     * Convert the entity to a plain JSON object for persistence.
+     */
+    toJSON(): InferOutput<Schema>;
+  };
+
+/**
+ * Replace base-instance returns with the full entity instance type, unwrapping
+ * promises, so methods that return `self` or `self.with(...)` chain with the
+ * entity's methods attached.
+ */
+type WithEntityInstance<R, Instance, Schema extends StandardSchema> =
+  R extends Promise<infer P>
+    ? Promise<WithEntityInstance<P, Instance, Schema>>
+    : R extends EntityBaseInstance<Schema>
+      ? Instance
+      : R;
+
 /**
  * Entity instance with validated props, attached methods, and immutable update
- * helpers.
+ * helpers. Method returns that are typed as the base instance (`self` or
+ * `self.with(...)`) are mapped to the full instance type so chaining keeps
+ * the entity's methods.
  */
 export type EntityInstance<
   Name extends string,
@@ -87,7 +125,13 @@ export type EntityInstance<
    * Convert the entity to a plain JSON object for persistence.
    */
   toJSON(): InferOutput<Schema>;
-} & Methods;
+} & {
+  [K in keyof Methods]: Methods[K] extends (...args: infer A) => infer R
+    ? (
+        ...args: A
+      ) => WithEntityInstance<R, EntityInstance<Name, Schema, Methods>, Schema>
+    : Methods[K];
+};
 
 /**
  * Entity definition returned by `defineEntity(...).build()`.
@@ -135,8 +179,7 @@ class EntityBuilder<
     private readonly cfg: {
       name: Name;
       schema?: Schema;
-      // biome-ignore lint/suspicious/noExplicitAny: Methods builder receives base instance
-      methods?: (self: any) => Methods;
+      methods?: (self: EntityBaseInstance<Schema>) => Methods;
     },
   ) {}
 
@@ -147,17 +190,22 @@ class EntityBuilder<
     return new EntityBuilder<Name, S, Methods>({
       name: this.cfg.name,
       schema,
-      methods: this.cfg.methods,
+      // Methods declared before props were typed against the previous schema;
+      // canonical builder order is props-then-methods, so this widening only
+      // affects the discouraged reverse order.
+      methods: this.cfg.methods as unknown as
+        | ((self: EntityBaseInstance<S>) => Methods)
+        | undefined,
     });
   }
 
   /**
    * Define methods to attach to entity instances.
-   * The method builder receives the base instance (with props, with, and toJSON).
+   * The method builder receives the typed base instance: validated props plus
+   * `with` and `toJSON`.
    */
   methods<M extends AnyMethods>(
-    // biome-ignore lint/suspicious/noExplicitAny: Methods builder receives base instance with props
-    build: (self: any) => M,
+    build: (self: EntityBaseInstance<Schema>) => M,
   ): EntityBuilder<Name, Schema, M> {
     return new EntityBuilder<Name, Schema, M>({
       name: this.cfg.name,
@@ -190,8 +238,7 @@ class EntityBuilder<
         // Cast parsed to a plain object for spreading
         const parsedObj = parsed as Record<string, unknown>;
 
-        // biome-ignore lint/suspicious/noExplicitAny: Dynamic object construction
-        const base: any = {
+        const base = {
           ...parsedObj,
           // Immutable update - creates a new validated instance
           // Note: Re-validates the merged props for data integrity
@@ -205,7 +252,7 @@ class EntityBuilder<
           toJSON() {
             return parsed;
           },
-        };
+        } as EntityBaseInstance<Schema>;
 
         const methods = methodsBuilder?.(base) ?? {};
         const instance = Object.freeze({
@@ -262,6 +309,7 @@ class EntityBuilder<
  * ```
  */
 export function defineEntity<Name extends string>(name: Name) {
-  // biome-ignore lint/suspicious/noExplicitAny: Initial schema type will be set via .props()
-  return new EntityBuilder<Name, any, Record<string, never>>({ name } as any);
+  return new EntityBuilder<Name, StandardSchema, Record<string, never>>({
+    name,
+  });
 }

package/src/domain/index.ts

@@ -1,18 +1,19 @@
 /**
  * @beignet/core/domain
  *
- * Domain modeling helpers for Beignet - value objects, entities, and domain events.
+ * Domain modeling helpers for Beignet - value objects and entities.
  *
  * This package provides small, framework-agnostic helpers for domain modeling:
  * - A Value Object builder (defineValueObject)
  * - An Entity/Aggregate builder (defineEntity)
- * - A Domain Event helper (defineDomainEvent)
+ *
+ * Domain events are declared with `defineEvent` from `@beignet/core/events`.
  */
 
-export { defineEntity, type EntityDef, type EntityInstance } from "./entity.js";
 export {
-  type DomainEventDef,
-  defineDomainEvent,
-  type InferEventPayload,
-} from "./events.js";
+  defineEntity,
+  type EntityBaseInstance,
+  type EntityDef,
+  type EntityInstance,
+} from "./entity.js";
 export { defineValueObject, type ValueObjectDef } from "./value-object.js";

package/src/events/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.
@@ -160,6 +162,11 @@ export interface RegisterListenersOptions<Ctx> {
    * Static listener context or factory evaluated for each delivered event.
    */
   ctx?: Ctx | (() => MaybePromise<Ctx>);
+  /**
+   * Runtime tracing port used to start the listener span before a lazy context
+   * factory runs.
+   */
+  tracing?: TracingPort;
   /**
    * Called when a listener fails. When omitted, listener errors are rethrown to
    * the event bus subscription callback.
@@ -243,16 +250,6 @@ async function parsePayload<Schema extends StandardSchemaV1>(
   throw new Error("Invalid Standard Schema result: missing value");
 }
 
-async function resolveCtx<Ctx>(
-  ctx: Ctx | (() => MaybePromise<Ctx>) | undefined,
-): Promise<Ctx> {
-  if (typeof ctx === "function") {
-    return (ctx as () => MaybePromise<Ctx>)();
-  }
-
-  return ctx as Ctx;
-}
-
 /**
  * Define a typed event.
  *
@@ -326,10 +323,26 @@ export function registerListeners<Ctx>(
     eventBus.subscribe(listener.event, async (rawPayload) => {
       try {
         const payload = await parseEventPayload(listener.event, rawPayload);
-        await listener.handle({
-          event: listener.event,
-          payload,
-          ctx: await resolveCtx(options.ctx),
+        const traceAttributes = {
+          "beignet.listener.name": listener.name,
+          "beignet.event.name": listener.event.name,
+        } as const;
+        await runWithResolvedTracingContext({
+          tracing: options.tracing,
+          ctx: options.ctx as Ctx | (() => MaybePromise<Ctx>),
+          operation: {
+            name: `beignet.listener ${listener.name}`,
+            type: "listener",
+            kind: "consumer",
+            attributes: traceAttributes,
+            metricAttributes: traceAttributes,
+          },
+          run: (ctx) =>
+            listener.handle({
+              event: listener.event,
+              payload,
+              ctx,
+            }),
         });
       } catch (error) {
         options.onError?.(error, listener);

package/src/flags/index.ts

@@ -38,7 +38,7 @@ export type FlagKey = string;
 /**
  * Feature flag value kind.
  */
-export type FlagKind = "boolean" | "string" | "number" | "object";
+export type FlagValueKind = "boolean" | "string" | "number" | "object";
 
 /**
  * Subject used for provider-neutral flag targeting.
@@ -104,8 +104,9 @@ export type FlagEvaluationContext = {
  * Flag definition registered through `defineFlags(...)`.
  */
 export type FlagDef<TValue extends FlagValue = FlagValue> = {
+  kind: "flag";
   key: FlagKey;
-  kind: FlagKindForValue<TValue>;
+  valueKind: FlagValueKindForValue<TValue>;
   defaultValue: TValue;
   description?: string;
   metadata?: Record<string, unknown>;
@@ -120,13 +121,14 @@ export type InferFlagValue<TFlag> =
 /**
  * Map a value type to its runtime flag kind.
  */
-export type FlagKindForValue<TValue extends FlagValue> = TValue extends boolean
-  ? "boolean"
-  : TValue extends string
-    ? "string"
-    : TValue extends number
-      ? "number"
-      : "object";
+export type FlagValueKindForValue<TValue extends FlagValue> =
+  TValue extends boolean
+    ? "boolean"
+    : TValue extends string
+      ? "string"
+      : TValue extends number
+        ? "number"
+        : "object";
 
 /**
  * Options accepted when declaring a flag.
@@ -184,7 +186,7 @@ export type FlagEvaluationDetails<TValue extends FlagValue = FlagValue> = {
   key: string;
   value: TValue;
   defaultValue: TValue;
-  kind: FlagKindForValue<TValue>;
+  valueKind: FlagValueKindForValue<TValue>;
   reason: FlagEvaluationReason;
   defaulted: boolean;
   variant?: string;
@@ -320,20 +322,21 @@ export type MemoryFlagsPort = FlagsPort & {
 };
 
 function createFlag<TValue extends FlagValue>(
-  kind: FlagKind,
+  valueKind: FlagValueKind,
   key: string,
   options: DefineFlagOptions<TValue>,
 ): FlagDef<TValue> {
   const defaultValue = options.default;
-  if (!matchesKind(defaultValue, kind)) {
+  if (!matchesValueKind(defaultValue, valueKind)) {
     throw new Error(
-      `Flag "${key}" default value does not match "${kind}" flag kind.`,
+      `Flag "${key}" default value does not match "${valueKind}" flag value kind.`,
     );
   }
 
   return {
+    kind: "flag",
     key,
-    kind: kind as FlagKindForValue<TValue>,
+    valueKind: valueKind as FlagValueKindForValue<TValue>,
     defaultValue,
     description: options.description,
     metadata: options.metadata,
@@ -454,9 +457,9 @@ export function createMemoryFlags(
     ...port,
     values,
     set(flag, value) {
-      if (!matchesKind(value, flag.kind)) {
+      if (!matchesValueKind(value, flag.valueKind)) {
         throw new Error(
-          `Flag "${flag.key}" value does not match "${flag.kind}" flag kind.`,
+          `Flag "${flag.key}" value does not match "${flag.valueKind}" flag value kind.`,
         );
       }
       values.set(flag.key, value);
@@ -485,13 +488,14 @@ function createFlagsFromStore(
     const values = readValues();
     const stored = values[flag.key];
     const hasStored = Object.hasOwn(values, flag.key);
-    const usedStoredValue = hasStored && matchesKind(stored, flag.kind);
+    const usedStoredValue =
+      hasStored && matchesValueKind(stored, flag.valueKind);
     const value = usedStoredValue
       ? (stored as typeof defaultValue)
       : defaultValue;
     const details: FlagEvaluationDetails<typeof defaultValue> = {
       key: flag.key,
-      kind: flag.kind as FlagKindForValue<typeof defaultValue>,
+      valueKind: flag.valueKind as FlagValueKindForValue<typeof defaultValue>,
       value,
       defaultValue,
       reason: usedStoredValue ? "static" : "default",
@@ -551,7 +555,7 @@ function createFlagsFromStore(
   return flags;
 }
 
-function matchesKind(value: unknown, kind: FlagKind): boolean {
+function matchesValueKind(value: unknown, kind: FlagValueKind): boolean {
   switch (kind) {
     case "boolean":
       return typeof value === "boolean";

package/src/idempotency/index.ts

@@ -507,13 +507,27 @@ function reservationFromRecord(
   };
 }
 
+/**
+ * Options for `createMemoryIdempotencyStore(...)`.
+ */
+export interface MemoryIdempotencyStoreOptions {
+  /**
+   * Clock used for reservation and completion timestamps. Defaults to the
+   * system clock.
+   */
+  now?: () => Date;
+}
+
 /**
  * Create an in-memory idempotency store for tests and local examples.
  *
  * The memory store is process-local and not suitable for multi-process
  * production deployments.
  */
-export function createMemoryIdempotencyStore(): MemoryIdempotencyStore {
+export function createMemoryIdempotencyStore(
+  options: MemoryIdempotencyStoreOptions = {},
+): MemoryIdempotencyStore {
+  const storeNow = options.now ?? (() => new Date());
   const records = new Map<string, MemoryRecord>();
 
   return {
@@ -527,7 +541,7 @@ export function createMemoryIdempotencyStore(): MemoryIdempotencyStore {
       assertNonEmptyString("fingerprint", input.fingerprint);
       assertTtl(input.ttlSec);
 
-      const now = new Date();
+      const now = storeNow();
       const storageKey = createIdempotencyStorageKey(input);
       const existing = records.get(storageKey);
 
@@ -573,7 +587,7 @@ export function createMemoryIdempotencyStore(): MemoryIdempotencyStore {
 
       existing.status = "completed";
       existing.result = input.result;
-      existing.completedAt = new Date();
+      existing.completedAt = storeNow();
     },
 
     async fail(input) {