@beignet/core 0.0.1 → 0.0.2

package/dist/contracts/index.js

@@ -3,9 +3,21 @@
  *
  * HTTP contract definitions and builders for Beignet.
  */
+/**
+ * Contract builder exports.
+ */
 export { ContractBuilder, createContract, } from "./contract-builder";
+/**
+ * Contract group exports.
+ */
 export { ContractGroup, createContractGroup } from "./contract-group";
+/**
+ * Contract-like helper exports.
+ */
 export { resolveContract, } from "./contract-like";
+/**
+ * Path template parsing exports.
+ */
 export { parsePathTemplate, } from "./path-template";
 export { BEIGNET_ERROR_OWNER_HEADER, BODY_HTTP_METHODS, getContractHeaderSchemas, methodSupportsRequestBody, STANDARD_ERROR_RESPONSE_SCHEMA, } from "./types";
 //# sourceMappingURL=index.js.map

package/dist/contracts/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/contracts/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EACL,eAAe,EAEf,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAGL,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAGL,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAsBzB,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EACjB,wBAAwB,EACxB,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/contracts/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH;;GAEG;AACH,OAAO,EACL,eAAe,EAEf,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B;;GAEG;AACH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACtE;;GAEG;AACH,OAAO,EAGL,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAKzB;;GAEG;AACH,OAAO,EAGL,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AA4BzB,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EACjB,wBAAwB,EACxB,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,SAAS,CAAC"}

package/dist/contracts/openapi-meta.d.ts

@@ -1,23 +1,23 @@
 /**
- * OpenAPI operation-level metadata for HTTP contracts
+ * OpenAPI operation-level metadata for HTTP contracts.
  */
 export type OpenAPIOperationMeta = {
-    /** A brief summary of the operation */
+    /** Brief operation summary. */
     summary?: string;
-    /** A detailed description of the operation */
+    /** Detailed operation description. */
     description?: string;
-    /** Tags for grouping operations */
+    /** Tags used to group operations. */
     tags?: string[];
-    /** Marks the operation as deprecated */
+    /** Whether the operation is deprecated. */
     deprecated?: boolean;
-    /** External documentation reference */
+    /** External documentation reference. */
     externalDocs?: {
         description?: string;
         url: string;
     };
-    /** Override for operationId (default is contract.name) */
+    /** Operation ID override. Defaults to `contract.name`. */
     operationId?: string;
-    /** Per-operation security requirements */
+    /** Per-operation security requirements. */
     security?: Array<Record<string, string[]>>;
 };
 //# sourceMappingURL=openapi-meta.d.ts.map

package/dist/contracts/openapi-meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openapi-meta.d.ts","sourceRoot":"","sources":["../../src/contracts/openapi-meta.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,wCAAwC;IACxC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,uCAAuC;IACvC,YAAY,CAAC,EAAE;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,GAAG,EAAE,MAAM,CAAC;KACb,CAAC;IACF,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;CAC5C,CAAC"}
+{"version":3,"file":"openapi-meta.d.ts","sourceRoot":"","sources":["../../src/contracts/openapi-meta.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,wCAAwC;IACxC,YAAY,CAAC,EAAE;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,GAAG,EAAE,MAAM,CAAC;KACb,CAAC;IACF,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;CAC5C,CAAC"}

package/dist/contracts/path-template.d.ts

@@ -1,3 +1,6 @@
+/**
+ * Parsed path segment from a Beignet route template.
+ */
 export type PathTemplateSegment = {
     kind: "static";
     value: string;
@@ -6,12 +9,36 @@ export type PathTemplateSegment = {
     name: string;
     raw: string;
 };
+/**
+ * Parsed representation of a Beignet route path template.
+ */
 export interface ParsedPathTemplate {
+    /**
+     * Dynamic parameter names in declaration order.
+     */
     keys: string[];
+    /**
+     * Static and dynamic path segments.
+     */
     segments: PathTemplateSegment[];
+    /**
+     * Normalized Beignet path using `:param` dynamic syntax.
+     */
     normalizedPath: string;
+    /**
+     * Route shape used for ambiguity detection, ignoring dynamic parameter names.
+     */
     shapeKey: string;
+    /**
+     * OpenAPI-compatible path using `{param}` syntax.
+     */
     openApiPath: string;
 }
+/**
+ * Parse a Beignet route path template.
+ *
+ * Paths must start with `/`. Dynamic segments may use `:id` or `[id]`.
+ * Catch-all segments and partial dynamic segments are intentionally rejected.
+ */
 export declare function parsePathTemplate(path: string): ParsedPathTemplate;
 //# sourceMappingURL=path-template.d.ts.map

package/dist/contracts/path-template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path-template.d.ts","sourceRoot":"","sources":["../../src/contracts/path-template.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAmCD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CA6ClE"}
+{"version":3,"file":"path-template.d.ts","sourceRoot":"","sources":["../../src/contracts/path-template.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,IAAI,EAAE,MAAM,EAAE,CAAC;IACf;;OAEG;IACH,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB;AAmCD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CA6ClE"}

package/dist/contracts/path-template.js

@@ -21,6 +21,12 @@ function parsePathSegment(path, segment) {
     }
     return { kind: "static", value: segment };
 }
+/**
+ * Parse a Beignet route path template.
+ *
+ * Paths must start with `/`. Dynamic segments may use `:id` or `[id]`.
+ * Catch-all segments and partial dynamic segments are intentionally rejected.
+ */
 export function parsePathTemplate(path) {
     if (!path.startsWith("/")) {
         throw new Error(`Invalid path template "${path}". Paths must start with "/".`);

package/dist/contracts/path-template.js.map

@@ -1 +1 @@
-{"version":3,"file":"path-template.js","sourceRoot":"","sources":["../../src/contracts/path-template.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"path-template.js","sourceRoot":"","sources":["../../src/contracts/path-template.ts"],"names":[],"mappings":"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"}

package/dist/contracts/types.d.ts

@@ -1,57 +1,117 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { IdempotencyMeta } from "../idempotency";
 import type { OpenAPIOperationMeta } from "./openapi-meta";
 import type { RateLimitMeta } from "./rate-limit";
 /**
- * Any Standard Schema validator type
- * Replaces ZodTypeAny to support all Standard Schema compatible libraries
+ * Any Standard Schema compatible validator.
  */
 export type StandardSchema = StandardSchemaV1<unknown, unknown>;
+/**
+ * Response schema for one HTTP status.
+ *
+ * Use `null` for empty responses such as 204.
+ */
 export type ContractResponseSchema = StandardSchema | null;
+/**
+ * Response schemas keyed by HTTP status code.
+ */
 export type ContractResponses = Partial<Record<number, ContractResponseSchema>>;
+/**
+ * Standard Beignet error response body.
+ */
 export type StandardErrorResponseBody = {
     code: string;
     message: string;
     details?: unknown;
     requestId?: string;
 };
+/**
+ * Standard Schema for Beignet's error envelope.
+ */
 export type StandardErrorResponseSchema = StandardSchemaV1<unknown, StandardErrorResponseBody>;
+/**
+ * Route-owned error definition stored in contract metadata.
+ */
 export type ContractErrorDefinition = {
+    /**
+     * Stable public error code.
+     */
     code: string;
+    /**
+     * HTTP status code.
+     */
     status: number;
+    /**
+     * Default human-readable message.
+     */
     message: string;
+    /**
+     * Optional details schema for TypeScript inference.
+     */
     details?: StandardSchema;
 };
+/**
+ * Route-owned error definitions keyed by catalog key.
+ */
 export type ContractErrorResponses = Record<string, ContractErrorDefinition>;
+/**
+ * Convert route-owned error definitions into standard envelope response schemas.
+ */
 export type ResponsesFromErrorDefinitions<T extends ContractErrorResponses> = {
     [K in keyof T as T[K]["status"]]: StandardErrorResponseSchema;
 };
+/**
+ * Header schema declaration for a contract.
+ */
 export type ContractHeaderSchemas = StandardSchema | readonly StandardSchema[] | null;
+/**
+ * Header used to distinguish framework-owned and route-owned error responses.
+ */
 export declare const BEIGNET_ERROR_OWNER_HEADER = "x-beignet-error-owner";
+/**
+ * Infer merged header input from one or more Standard Schema header validators.
+ */
 export type InferHeaderSchemaInput<T extends ContractHeaderSchemas | undefined> = T extends readonly StandardSchemaV1[] ? UnionToIntersection<InferInput<T[number]>> : T extends StandardSchemaV1 ? InferInput<T> : undefined;
+/**
+ * Infer merged header output from one or more Standard Schema header validators.
+ */
 export type InferHeaderSchemaOutput<T extends ContractHeaderSchemas | undefined> = T extends readonly StandardSchemaV1[] ? UnionToIntersection<InferOutput<T[number]>> : T extends StandardSchemaV1 ? InferOutput<T> : undefined;
 type UnionToIntersection<T> = (T extends unknown ? (value: T) => void : never) extends (value: infer I) => void ? I : never;
 /**
- * Infer the output type from a Standard Schema
+ * Infer the parsed output type from a Standard Schema.
  */
 export type InferOutput<T extends StandardSchemaV1> = StandardSchemaV1.InferOutput<T>;
 /**
- * Infer the input type from a Standard Schema
+ * Infer the input type accepted by a Standard Schema.
  */
 export type InferInput<T extends StandardSchemaV1> = StandardSchemaV1.InferInput<T>;
 /**
- * HTTP methods supported by contracts
+ * HTTP methods supported by contracts.
  */
 export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+/**
+ * HTTP methods that may carry a JSON request body.
+ */
 export type BodyHttpMethod = Extract<HttpMethod, "POST" | "PUT" | "PATCH">;
+/**
+ * Runtime list of HTTP methods that support request bodies.
+ */
 export declare const BODY_HTTP_METHODS: readonly ["POST", "PUT", "PATCH"];
+/**
+ * Check whether a method supports a contract request body.
+ */
 export declare function methodSupportsRequestBody(method: HttpMethod): method is BodyHttpMethod;
+/**
+ * Runtime Standard Schema for Beignet's standard error envelope.
+ */
 export declare const STANDARD_ERROR_RESPONSE_SCHEMA: StandardErrorResponseSchema;
 /**
- * Contract metadata - freeform object for policies, auth, etc.
- * May include an optional openapi namespace for OpenAPI-specific metadata,
- * and an optional rateLimit namespace for rate limiting configuration.
+ * Contract metadata consumed by hooks, OpenAPI, and app conventions.
  */
 export type ContractMeta = {
+    /**
+     * OpenAPI operation metadata.
+     */
     openapi?: OpenAPIOperationMeta;
     /**
      * Optional rate limit configuration for this contract.
@@ -59,10 +119,17 @@ export type ContractMeta = {
      * If absent, no rate limiting is applied.
      */
     rateLimit?: RateLimitMeta;
+    /**
+     * Optional idempotency configuration for this contract.
+     *
+     * This metadata is intended for hooks, docs, and OpenAPI. Use cases should
+     * still call `runIdempotently(...)` for workflows that must be retry-safe.
+     */
+    idempotency?: IdempotencyMeta;
     [namespace: string]: unknown;
 };
 /**
- * HTTP contract configuration
+ * Plain HTTP contract configuration consumed by server, client, and tooling.
  */
 export type HttpContractConfig<TMethod extends HttpMethod = HttpMethod, TPathParams extends StandardSchema | null = StandardSchema | null, TQuery extends StandardSchema | null = StandardSchema | null, TBody extends StandardSchema | null = StandardSchema | null, TResponses extends ContractResponses = ContractResponses, TMeta extends ContractMeta = ContractMeta, TPath extends string = string, THeaders extends ContractHeaderSchemas = ContractHeaderSchemas> = {
     kind: "http";
@@ -79,19 +146,46 @@ export type HttpContractConfig<TMethod extends HttpMethod = HttpMethod, TPathPar
      * Contract name without the resource namespace.
      */
     localName?: string;
+    /**
+     * HTTP method.
+     */
     method: TMethod;
+    /**
+     * Path template.
+     */
     path: TPath;
+    /**
+     * Path parameter schema.
+     */
     pathParams: TPathParams;
+    /**
+     * Query parameter schema.
+     */
     query: TQuery;
+    /**
+     * Request header schema or schemas.
+     */
     headers?: THeaders;
+    /**
+     * Request body schema.
+     */
     body: TBody;
+    /**
+     * Response schemas keyed by HTTP status code.
+     */
     responses: TResponses;
+    /**
+     * Contract metadata.
+     */
     metadata: TMeta;
 };
 /**
- * Any contract type
+ * Any HTTP contract config.
  */
 export type AnyContract = HttpContractConfig;
+/**
+ * Normalize a contract header declaration into a schema list.
+ */
 export declare function getContractHeaderSchemas(headers: ContractHeaderSchemas | undefined): readonly StandardSchema[];
 export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/contracts/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/contracts/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/contracts/types.ts"],"names":[],"mappings":"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"}

package/dist/contracts/types.js

@@ -1,12 +1,24 @@
+/**
+ * Header used to distinguish framework-owned and route-owned error responses.
+ */
 export const BEIGNET_ERROR_OWNER_HEADER = "x-beignet-error-owner";
+/**
+ * Runtime list of HTTP methods that support request bodies.
+ */
 export const BODY_HTTP_METHODS = [
     "POST",
     "PUT",
     "PATCH",
 ];
+/**
+ * Check whether a method supports a contract request body.
+ */
 export function methodSupportsRequestBody(method) {
     return BODY_HTTP_METHODS.includes(method);
 }
+/**
+ * Runtime Standard Schema for Beignet's standard error envelope.
+ */
 export const STANDARD_ERROR_RESPONSE_SCHEMA = {
     "~standard": {
         version: 1,
@@ -44,6 +56,9 @@ export const STANDARD_ERROR_RESPONSE_SCHEMA = {
         },
     },
 };
+/**
+ * Normalize a contract header declaration into a schema list.
+ */
 export function getContractHeaderSchemas(headers) {
     if (!headers)
         return [];

package/dist/contracts/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/contracts/types.ts"],"names":[],"mappings":"AAqCA,MAAM,CAAC,MAAM,0BAA0B,GAAG,uBAAuB,CAAC;AAoDlE,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,MAAM;IACN,KAAK;IACL,OAAO;CACqC,CAAC;AAE/C,MAAM,UAAU,yBAAyB,CACvC,MAAkB;IAElB,OAAQ,iBAA2C,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACvE,CAAC;AAED,MAAM,CAAC,MAAM,8BAA8B,GAAgC;IACzE,WAAW,EAAE;QACX,OAAO,EAAE,CAAC;QACV,MAAM,EAAE,SAAS;QACjB,QAAQ,CAAC,KAAK;YACZ,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBAChD,OAAO;oBACL,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,sCAAsC,EAAE,CAAC;iBAC9D,CAAC;YACJ,CAAC;YAED,MAAM,IAAI,GAAG,KAAgC,CAAC;YAC9C,MAAM,MAAM,GAA6B,EAAE,CAAC;YAC5C,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAClC,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,iCAAiC,EAAE,CAAC,CAAC;YAC9D,CAAC;YACD,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;gBACrC,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,oCAAoC,EAAE,CAAC,CAAC;YACjE,CAAC;YACD,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;gBACvE,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,sCAAsC,EAAE,CAAC,CAAC;YACnE,CAAC;YACD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAClB,OAAO,EAAE,MAAM,EAAE,CAAC;YACpB,CAAC;YAED,OAAO;gBACL,KAAK,EAAE;oBACL,IAAI,EAAE,IAAI,CAAC,IAAc;oBACzB,OAAO,EAAE,IAAI,CAAC,OAAiB;oBAC/B,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAChE,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS;wBAC9B,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAmB,EAAE;wBACzC,CAAC,CAAC,EAAE,CAAC;iBACR;aACF,CAAC;QACJ,CAAC;KACF;CACF,CAAC;AA4DF,MAAM,UAAU,wBAAwB,CACtC,OAA0C;IAE1C,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACxB,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAC3B,CAAC,CAAE,OAAqC;QACxC,CAAC,CAAC,CAAC,OAAyB,CAAC,CAAC;AAClC,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/contracts/types.ts"],"names":[],"mappings":"AAkFA;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,uBAAuB,CAAC;AA6DlE;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,MAAM;IACN,KAAK;IACL,OAAO;CACqC,CAAC;AAE/C;;GAEG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAAkB;IAElB,OAAQ,iBAA2C,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACvE,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAgC;IACzE,WAAW,EAAE;QACX,OAAO,EAAE,CAAC;QACV,MAAM,EAAE,SAAS;QACjB,QAAQ,CAAC,KAAK;YACZ,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBAChD,OAAO;oBACL,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,sCAAsC,EAAE,CAAC;iBAC9D,CAAC;YACJ,CAAC;YAED,MAAM,IAAI,GAAG,KAAgC,CAAC;YAC9C,MAAM,MAAM,GAA6B,EAAE,CAAC;YAC5C,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAClC,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,iCAAiC,EAAE,CAAC,CAAC;YAC9D,CAAC;YACD,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;gBACrC,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,oCAAoC,EAAE,CAAC,CAAC;YACjE,CAAC;YACD,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;gBACvE,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,sCAAsC,EAAE,CAAC,CAAC;YACnE,CAAC;YACD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAClB,OAAO,EAAE,MAAM,EAAE,CAAC;YACpB,CAAC;YAED,OAAO;gBACL,KAAK,EAAE;oBACL,IAAI,EAAE,IAAI,CAAC,IAAc;oBACzB,OAAO,EAAE,IAAI,CAAC,OAAiB;oBAC/B,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAChE,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS;wBAC9B,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAmB,EAAE;wBACzC,CAAC,CAAC,EAAE,CAAC;iBACR;aACF,CAAC;QACJ,CAAC;KACF;CACF,CAAC;AA4FF;;GAEG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAA0C;IAE1C,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACxB,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAC3B,CAAC,CAAE,OAAqC;QACxC,CAAC,CAAC,CAAC,OAAyB,CAAC,CAAC;AAClC,CAAC"}

package/dist/contracts/utils.d.ts

@@ -1,3 +1,9 @@
 import type { HttpMethod } from "./types";
+/**
+ * Generate a stable contract name from an HTTP method and path.
+ *
+ * `/api` is ignored as a leading path segment so generated names focus on the
+ * resource shape.
+ */
 export declare function generateContractName(method: HttpMethod, path: string): string;
 //# sourceMappingURL=utils.d.ts.map

package/dist/contracts/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/contracts/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAkC1C,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAoB7E"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/contracts/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAkC1C;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAoB7E"}

package/dist/contracts/utils.js

@@ -24,6 +24,12 @@ function getMeaningfulPathSegments(path) {
     }
     return segments;
 }
+/**
+ * Generate a stable contract name from an HTTP method and path.
+ *
+ * `/api` is ignored as a leading path segment so generated names focus on the
+ * resource shape.
+ */
 export function generateContractName(method, path) {
     const methodPrefix = methodNameMap[method];
     const segments = getMeaningfulPathSegments(path);

package/dist/contracts/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/contracts/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAG9E,MAAM,aAAa,GAA+B;IAChD,GAAG,EAAE,KAAK;IACV,IAAI,EAAE,QAAQ;IACd,GAAG,EAAE,QAAQ;IACb,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;CACnB,CAAC;AAEF,SAAS,YAAY,CAAC,KAAa;IACjC,OAAO,KAAK;SACT,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;SACtC,KAAK,CAAC,eAAe,CAAC;SACtB,MAAM,CAAC,OAAO,CAAC;SACf,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAC3D,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAED,SAAS,yBAAyB,CAAC,IAAY;IAC7C,MAAM,QAAQ,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC;IAElD,IACE,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,KAAK,QAAQ;QAC9B,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,KAAK,EACzC,CAAC;QACD,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,MAAkB,EAAE,IAAY;IACnE,MAAM,YAAY,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,yBAAyB,CAAC,IAAI,CAAC,CAAC;IAEjD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,GAAG,YAAY,MAAM,CAAC;IAC/B,CAAC;IAED,MAAM,UAAU,GAAG,QAAQ;SACxB,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QACf,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC/B,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC7C,OAAO,KAAK,SAAS,IAAI,OAAO,EAAE,CAAC;QACrC,CAAC;QAED,OAAO,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC;IACnD,CAAC,CAAC;SACD,IAAI,CAAC,EAAE,CAAC,CAAC;IAEZ,OAAO,GAAG,YAAY,GAAG,UAAU,EAAE,CAAC;AACxC,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/contracts/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAG9E,MAAM,aAAa,GAA+B;IAChD,GAAG,EAAE,KAAK;IACV,IAAI,EAAE,QAAQ;IACd,GAAG,EAAE,QAAQ;IACb,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;CACnB,CAAC;AAEF,SAAS,YAAY,CAAC,KAAa;IACjC,OAAO,KAAK;SACT,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;SACtC,KAAK,CAAC,eAAe,CAAC;SACtB,MAAM,CAAC,OAAO,CAAC;SACf,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAC3D,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAED,SAAS,yBAAyB,CAAC,IAAY;IAC7C,MAAM,QAAQ,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC;IAElD,IACE,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,KAAK,QAAQ;QAC9B,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,KAAK,EACzC,CAAC;QACD,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAkB,EAAE,IAAY;IACnE,MAAM,YAAY,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,yBAAyB,CAAC,IAAI,CAAC,CAAC;IAEjD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,GAAG,YAAY,MAAM,CAAC;IAC/B,CAAC;IAED,MAAM,UAAU,GAAG,QAAQ;SACxB,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QACf,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC/B,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC7C,OAAO,KAAK,SAAS,IAAI,OAAO,EAAE,CAAC;QACrC,CAAC;QAED,OAAO,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC;IACnD,CAAC,CAAC;SACD,IAAI,CAAC,EAAE,CAAC,CAAC;IAEZ,OAAO,GAAG,YAAY,GAAG,UAAU,EAAE,CAAC;AACxC,CAAC"}

package/dist/domain/entity.d.ts

@@ -1,19 +1,20 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 /**
- * Any Standard Schema validator type
+ * Any Standard Schema compatible validator.
  */
 export type StandardSchema = StandardSchemaV1<unknown, unknown>;
 /**
- * Infer the output type from a Standard Schema
+ * Infer the parsed output type from a Standard Schema.
  */
 export type InferOutput<T extends StandardSchemaV1> = StandardSchemaV1.InferOutput<T>;
 type AnyMethods = Record<string, any>;
 /**
- * Represents an instance of an entity with props, methods, and immutable update capability.
+ * Entity instance with validated props, attached methods, and immutable update
+ * helpers.
  */
 export type EntityInstance<Name extends string, Schema extends StandardSchema, Methods extends AnyMethods> = InferOutput<Schema> & {
     /**
-     * Create a new entity instance with updated properties (immutable update).
+     * Create a new validated entity instance with patched properties.
      */
     with(patch: Partial<InferOutput<Schema>>): EntityInstance<Name, Schema, Methods> | Promise<EntityInstance<Name, Schema, Methods>>;
     /**
@@ -22,18 +23,24 @@ export type EntityInstance<Name extends string, Schema extends StandardSchema, M
     toJSON(): InferOutput<Schema>;
 } & Methods;
 /**
- * Represents a defined Entity with schema and factory methods.
+ * Entity definition returned by `defineEntity(...).build()`.
  */
 export interface EntityDef<Name extends string, Schema extends StandardSchema, Methods extends AnyMethods> {
-    /** The name of this entity (for debugging/introspection) */
+    /** Name used for debugging and introspection. */
     name: Name;
-    /** The Standard Schema for validating entity props */
+    /** Standard Schema used to validate entity props. */
     schema: Schema;
-    /** Create a new entity instance from props */
+    /**
+     * Create a new frozen entity instance from props.
+     *
+     * Returns a promise when the underlying Standard Schema validates async.
+     */
     create(props: InferOutput<Schema>): EntityInstance<Name, Schema, Methods> | Promise<EntityInstance<Name, Schema, Methods>>;
-    /** Reconstruct an entity instance from JSON (e.g., from persistence) */
+    /**
+     * Reconstruct an entity instance from JSON, usually from persistence.
+     */
     fromJSON(json: InferOutput<Schema>): EntityInstance<Name, Schema, Methods> | Promise<EntityInstance<Name, Schema, Methods>>;
-    /** Type alias for the entity instance type */
+    /** Type-only alias for the entity instance type. Undefined at runtime. */
     Type: EntityInstance<Name, Schema, Methods>;
 }
 /**
@@ -61,7 +68,11 @@ declare class EntityBuilder<Name extends string, Schema extends StandardSchema,
     build(): EntityDef<Name, Schema, Methods>;
 }
 /**
- * Create a new Entity builder.
+ * Create a new entity builder.
+ *
+ * Entities validate props, attach domain methods, and return frozen immutable
+ * instances. `with(...)` revalidates the merged props. `.Type` is type-only and
+ * should be used with `typeof Entity.Type`.
  *
  * @example
  * ```ts

package/dist/domain/entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../src/domain/entity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAEhE;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,gBAAgB,IAChD,gBAAgB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;AAuDlC,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEtC;;GAEG;AACH,MAAM,MAAM,cAAc,CACxB,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,cAAc,EAC7B,OAAO,SAAS,UAAU,IACxB,WAAW,CAAC,MAAM,CAAC,GAAG;IACxB;;OAEG;IACH,IAAI,CACF,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,GAEjC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,GACrC,OAAO,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD;;OAEG;IACH,MAAM,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;CAC/B,GAAG,OAAO,CAAC;AAEZ;;GAEG;AACH,MAAM,WAAW,SAAS,CACxB,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,cAAc,EAC7B,OAAO,SAAS,UAAU;IAE1B,4DAA4D;IAC5D,IAAI,EAAE,IAAI,CAAC;IACX,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,MAAM,CACJ,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GAExB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,GACrC,OAAO,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,wEAAwE;IACxE,QAAQ,CACN,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,GAEvB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,GACrC,OAAO,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,8CAA8C;IAC9C,IAAI,EAAE,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAED;;GAEG;AACH,cAAM,aAAa,CACjB,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,cAAc,EAC7B,OAAO,SAAS,UAAU;IAGxB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE;QACpB,IAAI,EAAE,IAAI,CAAC;QACX,MAAM,CAAC,EAAE,MAAM,CAAC;QAEhB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC;KAClC;IAGH;;OAEG;IACH,KAAK,CAAC,CAAC,SAAS,cAAc,EAAE,MAAM,EAAE,CAAC,GAAG,aAAa,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC;IAQ3E;;;OAGG;IACH,OAAO,CAAC,CAAC,SAAS,UAAU,EAE1B,KAAK,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,GACtB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAQjC;;OAEG;IACH,KAAK,IAAI,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC;CAgE1C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,IAAI,SAAS,MAAM,EAAE,IAAI,EAAE,IAAI,mDAG3D"}
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../src/domain/entity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAEhE;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,gBAAgB,IAChD,gBAAgB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;AAuDlC,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEtC;;;GAGG;AACH,MAAM,MAAM,cAAc,CACxB,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,cAAc,EAC7B,OAAO,SAAS,UAAU,IACxB,WAAW,CAAC,MAAM,CAAC,GAAG;IACxB;;OAEG;IACH,IAAI,CACF,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,GAEjC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,GACrC,OAAO,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD;;OAEG;IACH,MAAM,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;CAC/B,GAAG,OAAO,CAAC;AAEZ;;GAEG;AACH,MAAM,WAAW,SAAS,CACxB,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,cAAc,EAC7B,OAAO,SAAS,UAAU;IAE1B,iDAAiD;IACjD,IAAI,EAAE,IAAI,CAAC;IACX,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CACJ,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GAExB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,GACrC,OAAO,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD;;OAEG;IACH,QAAQ,CACN,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,GAEvB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,GACrC,OAAO,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,0EAA0E;IAC1E,IAAI,EAAE,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAED;;GAEG;AACH,cAAM,aAAa,CACjB,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,cAAc,EAC7B,OAAO,SAAS,UAAU;IAGxB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE;QACpB,IAAI,EAAE,IAAI,CAAC;QACX,MAAM,CAAC,EAAE,MAAM,CAAC;QAEhB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC;KAClC;IAGH;;OAEG;IACH,KAAK,CAAC,CAAC,SAAS,cAAc,EAAE,MAAM,EAAE,CAAC,GAAG,aAAa,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC;IAQ3E;;;OAGG;IACH,OAAO,CAAC,CAAC,SAAS,UAAU,EAE1B,KAAK,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,GACtB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAQjC;;OAEG;IACH,KAAK,IAAI,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC;CAgE1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,YAAY,CAAC,IAAI,SAAS,MAAM,EAAE,IAAI,EAAE,IAAI,mDAG3D"}

package/dist/domain/entity.js

@@ -127,7 +127,11 @@ class EntityBuilder {
     }
 }
 /**
- * Create a new Entity builder.
+ * Create a new entity builder.
+ *
+ * Entities validate props, attach domain methods, and return frozen immutable
+ * instances. `with(...)` revalidates the merged props. `.Type` is type-only and
+ * should be used with `typeof Entity.Type`.
  *
  * @example
  * ```ts

package/dist/domain/entity.js.map

@@ -1 +1 @@
-{"version":3,"file":"entity.js","sourceRoot":"","sources":["../../src/domain/entity.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"entity.js","sourceRoot":"","sources":["../../src/domain/entity.ts"],"names":[],"mappings":"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"}

package/dist/domain/events.d.ts

@@ -1,6 +1,6 @@
 import type { EventDef, InferEventPayload, StandardSchema } from "../events";
 /**
- * Represents a defined Domain Event with name and payload schema.
+ * Domain event definition with a stable name and payload schema.
  */
 export type DomainEventDef<Name extends string = string, Payload extends StandardSchema = StandardSchema> = EventDef<Name, Payload>;
 /**
@@ -22,7 +22,10 @@ export type DomainEventDef<Name extends string = string, Payload extends Standar
  */
 export type { InferEventPayload };
 /**
- * Create a new Domain Event definition.
+ * Create a new domain event definition.
+ *
+ * This is a domain-focused alias around `defineEvent(...)` for applications
+ * that separate domain events from integration events.
  *
  * @example
  * ```ts

package/dist/domain/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/domain/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG7E;;GAEG;AACH,MAAM,MAAM,cAAc,CACxB,IAAI,SAAS,MAAM,GAAG,MAAM,EAC5B,OAAO,SAAS,cAAc,GAAG,cAAc,IAC7C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAE5B;;;;;;;;;;;;;;;;GAgBG;AACH,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAElC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,SAAS,MAAM,EACnB,OAAO,SAAS,cAAc,EAC9B,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,GAAG,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,CAE7D"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/domain/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG7E;;GAEG;AACH,MAAM,MAAM,cAAc,CACxB,IAAI,SAAS,MAAM,GAAG,MAAM,EAC5B,OAAO,SAAS,cAAc,GAAG,cAAc,IAC7C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAE5B;;;;;;;;;;;;;;;;GAgBG;AACH,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAElC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,SAAS,MAAM,EACnB,OAAO,SAAS,cAAc,EAC9B,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,GAAG,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,CAE7D"}

package/dist/domain/events.js

@@ -1,6 +1,9 @@
 import { defineEvent } from "../events";
 /**
- * Create a new Domain Event definition.
+ * Create a new domain event definition.
+ *
+ * This is a domain-focused alias around `defineEvent(...)` for applications
+ * that separate domain events from integration events.
  *
  * @example
  * ```ts

package/dist/domain/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/domain/events.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AA6BxC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB,CAG/B,IAAU,EAAE,OAAgB;IAC5B,OAAO,WAAW,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;AACxC,CAAC"}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/domain/events.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AA6BxC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,iBAAiB,CAG/B,IAAU,EAAE,OAAgB;IAC5B,OAAO,WAAW,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;AACxC,CAAC"}