stitchkit 0.41.0 → 0.43.0

package/README.md

@@ -51,6 +51,17 @@ supported via `stitchkit/node`.
 
 ## Install
 
+Start a production-shaped Next.js, Stitchkit and PostgreSQL application:
+
+```bash
+bun create stitchkit my-app
+cd my-app
+# Point DATABASE_URL in .env at your PostgreSQL database.
+bun run dev
+```
+
+To add Stitchkit to an existing project instead:
+
 ```bash
 bun add stitchkit        # Bun
 npm install stitchkit    # Node
@@ -348,11 +359,17 @@ never touches MCP never installs the MCP SDK. → [ADR 0011](./docs/decisions/00
 The framework stays focused and inspectable: explicit adapters, no generated
 application code and no framework build step in your app.
 
-## Example
-
-A complete runnable app lives in [`packages/starter`](./packages/starter) — a
-notes CRUD with a contract, a typed client, `react-query-kit` hooks and a
-Socket.IO live-reload.
+## Official starter
+
+`bun create stitchkit my-app` generates the canonical application: separate
+Next.js and Bun API processes, Prisma/PostgreSQL, shared Zod contracts, typed
+HTTP/React Query clients, Socket.IO cache updates, OpenAPI, MCP, CLI and a full
+UI catalogue. Its only source is
+[`packages/create-stitchkit/template`](./packages/create-stitchkit/template).
+The application owns its Prisma schema and migrations while PostgreSQL remains
+external infrastructure configured through `DATABASE_URL`.
+The template owns a committed Bun lockfile and an explicit Stitchkit catalog
+range, so framework and scaffolder releases advance independently.
 
 ## Documentation — two roads
 

package/dist/cli.js

@@ -4,10 +4,10 @@ import {
   emitResult,
   parseCliArgs,
   pollUntilDone
-} from "./index-ncqqn1bc.js";
+} from "./index-h2wdcsby.js";
 import"./index-frfyw9fa.js";
 import"./index-x3fcszf8.js";
-import"./index-sc67e454.js";
+import"./index-gex6gxhe.js";
 export {
   pollUntilDone,
   parseCliArgs,

package/dist/contract/errors-factory.d.ts

@@ -1,18 +1,91 @@
-/** A typed thrower — throws an `AppError` with the declared code and status. */
-export type ErrorThrower = (message?: string, details?: Record<string, unknown>, hint?: string) => never;
-/** The handle `defineErrors` returns. `TDef` maps `CODE → HTTP status`. */
-export interface DefinedErrors<TDef extends Record<string, number>> {
-    /** One thrower per code — `errors.CODE(message?)` throws the matching `AppError`. */
-    errors: {
-        [K in keyof TDef]: ErrorThrower;
+/**
+ * Declare an application's domain errors once. Each definition owns its HTTP
+ * status and optional Zod schema for structured details; generated factories
+ * construct (but do not throw) branded `AppError` instances.
+ *
+ * ```ts
+ * export const appErrors = defineErrors({
+ *   SESSION_NOT_FOUND: { status: 404 },
+ *   QUOTA_EXCEEDED: {
+ *     status: 429,
+ *     details: z.object({ retryAfterSeconds: z.number().int().positive() }),
+ *   },
+ * })
+ *
+ * throw appErrors.errors.SESSION_NOT_FOUND({ message: 'No such session' })
+ * throw appErrors.errors.QUOTA_EXCEEDED({
+ *   details: { retryAfterSeconds: 30 },
+ *   hint: 'Wait for the current window to expire',
+ * })
+ * ```
+ */
+import { z } from 'zod';
+import { AppError } from './errors';
+/** Supported structured-details schemas: a required or optional Zod object. */
+export type ErrorDetailsSchema = z.ZodObject | z.ZodOptional<z.ZodObject>;
+/** One domain error definition. Omitting `details` forbids structured details. */
+export type ErrorDefinition = {
+    readonly status: number;
+    readonly details?: never;
+} | {
+    readonly status: number;
+    readonly details: ErrorDetailsSchema;
+};
+export type ErrorDefinitions = Record<string, ErrorDefinition>;
+/** Parsed details retained by the constructed `AppError`. */
+export type ErrorDetailsOutput<TDefinition extends ErrorDefinition> = TDefinition extends {
+    details: infer TSchema extends ErrorDetailsSchema;
+} ? Extract<z.output<TSchema>, Record<string, unknown> | undefined> : undefined;
+/** AppError instance with required details refined when its schema is required. */
+export type DefinedAppError<TCode extends string, TDefinition extends ErrorDefinition> = AppError<TCode, ErrorDetailsOutput<TDefinition>> & (TDefinition extends {
+    details: infer TSchema extends ErrorDetailsSchema;
+} ? undefined extends z.output<TSchema> ? object : {
+    readonly details: ErrorDetailsOutput<TDefinition>;
+} : object);
+/**
+ * Factory arguments inferred from the definition: details are forbidden,
+ * required or optional according to the declared schema.
+ */
+export type ErrorFactoryArguments<TDefinition extends ErrorDefinition> = TDefinition extends {
+    details: infer TSchema extends ErrorDetailsSchema;
+} ? undefined extends z.input<TSchema> ? [
+    options?: {
+        message?: string;
+        details?: Exclude<z.input<TSchema>, undefined>;
+        hint?: string;
+    }
+] : [
+    options: {
+        message?: string;
+        details: z.input<TSchema>;
+        hint?: string;
+    }
+] : [options?: {
+    message?: string;
+    details?: never;
+    hint?: string;
+}];
+/** Typed constructor for one declared domain error code. */
+export type ErrorFactory<TCode extends string, TDefinition extends ErrorDefinition> = (...args: ErrorFactoryArguments<TDefinition>) => DefinedAppError<TCode, TDefinition>;
+export type ErrorFactories<TDefinitions extends ErrorDefinitions> = {
+    readonly [TCode in keyof TDefinitions]: ErrorFactory<TCode & string, TDefinitions[TCode]>;
+};
+export type FrozenErrorDefinitions<TDefinitions extends ErrorDefinitions> = {
+    readonly [TCode in keyof TDefinitions]: Readonly<TDefinitions[TCode]>;
+};
+/** The immutable handle returned by `defineErrors`. */
+export interface DefinedErrors<TDefinitions extends ErrorDefinitions> {
+    /** One typed `AppError` constructor per code. The caller chooses when to throw. */
+    readonly errors: ErrorFactories<TDefinitions>;
+    /** Code literals for client-side matching without magic strings. */
+    readonly codes: {
+        readonly [TCode in keyof TDefinitions]: TCode & string;
     };
-    /** The code literals — `codes.CODE === 'CODE'`, for client-side matching. */
-    codes: {
-        readonly [K in keyof TDef]: K;
-    };
-    /** Type guard — is `code` one of this app's declared codes? */
-    isCode: (code: string) => code is keyof TDef & string;
+    /** Read-only definitions; status and details schemas remain one source of truth. */
+    readonly definitions: FrozenErrorDefinitions<TDefinitions>;
+    /** Type guard — is `code` one of this application's declared codes? */
+    readonly isCode: (code: string) => code is Extract<keyof TDefinitions, string>;
 }
-/** Declare a set of domain error codes (`{ CODE: httpStatus }`). */
-export declare function defineErrors<const TDef extends Record<string, number>>(defs: TDef): DefinedErrors<TDef>;
+/** Declare an immutable, Zod-first domain error vocabulary. */
+export declare function defineErrors<const TDefinitions extends ErrorDefinitions>(source: TDefinitions): DefinedErrors<TDefinitions>;
 //# sourceMappingURL=errors-factory.d.ts.map

package/dist/contract/errors-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors-factory.d.ts","sourceRoot":"","sources":["../../src/contract/errors-factory.ts"],"names":[],"mappings":"AA8BA,gFAAgF;AAChF,MAAM,MAAM,YAAY,GAAG,CACzB,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,IAAI,CAAC,EAAE,MAAM,KACV,KAAK,CAAC;AAEX,2EAA2E;AAC3E,MAAM,WAAW,aAAa,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAChE,qFAAqF;IACrF,MAAM,EAAE;SAAG,CAAC,IAAI,MAAM,IAAI,GAAG,YAAY;KAAE,CAAC;IAC5C,6EAA6E;IAC7E,KAAK,EAAE;QAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,IAAI,GAAG,CAAC;KAAE,CAAC;IACzC,+DAA+D;IAC/D,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,IAAI,MAAM,IAAI,GAAG,MAAM,CAAC;CACvD;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,KAAK,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACpE,IAAI,EAAE,IAAI,GACT,aAAa,CAAC,IAAI,CAAC,CAgBrB"}
+{"version":3,"file":"errors-factory.d.ts","sourceRoot":"","sources":["../../src/contract/errors-factory.ts"],"names":[],"mappings":"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"}

package/dist/contract/errors.d.ts

@@ -21,12 +21,12 @@ export interface ErrorEnvelope {
  * structured `details` and a `hint`. `toJSON()` renders the public error
  * envelope. Throw it directly, or via the typed helpers below.
  */
-export declare class AppError extends Error {
-    readonly code: string;
+export declare class AppError<TCode extends string = string, TDetails extends Record<string, unknown> | undefined = Record<string, unknown> | undefined> extends Error {
+    readonly code: TCode;
     readonly status: number;
-    readonly details?: Record<string, unknown> | undefined;
+    readonly details?: TDetails | undefined;
     readonly hint?: string | undefined;
-    constructor(code: string, message?: string, status?: number, details?: Record<string, unknown> | undefined, hint?: string | undefined);
+    constructor(code: TCode, message?: string, status?: number, details?: TDetails | undefined, hint?: string | undefined);
     static is(err: unknown): err is AppError;
     toJSON(): ErrorEnvelope;
 }

package/dist/contract/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/contract/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE;QACL,2CAA2C;QAC3C,IAAI,EAAE,MAAM,CAAC;QACb,8BAA8B;QAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,gCAAgC;QAChC,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,0BAA0B;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAcD;;;;GAIG;AACH,qBAAa,QAAS,SAAQ,KAAK;aAEf,IAAI,EAAE,MAAM;aAEZ,MAAM,EAAE,MAAM;aACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;aACjC,IAAI,CAAC,EAAE,MAAM;IAL/B,YACkB,IAAI,EAAE,MAAM,EAC5B,OAAO,CAAC,EAAE,MAAM,EACA,MAAM,GAAE,MAAY,EACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA,EACjC,IAAI,CAAC,EAAE,MAAM,YAAA,EAQ9B;IAED,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,QAAQ,CAEvC;IAED,MAAM,IAAI,aAAa,CAStB;CACF;AAED,qCAAqC;AACrC,wBAAgB,QAAQ,CAAC,OAAO,SAAc,GAAG,KAAK,CAErD;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAEpF;AAED,wCAAwC;AACxC,wBAAgB,YAAY,CAAC,OAAO,SAAiB,GAAG,KAAK,CAE5D;AAED,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,OAAO,SAAc,GAAG,KAAK,CAEtD;AAED,0EAA0E;AAC1E,wBAAgB,QAAQ,CAAC,OAAO,SAAa,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAEvF;AAED,wCAAwC;AACxC,wBAAgB,WAAW,CAAC,OAAO,SAAsB,GAAG,KAAK,CAEhE;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;CAUE,CAAC;AAEnC,mFAAmF;AACnF,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,mBAAmB,CAAC;AAE/D,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,eAAe,CAEvE;AAED,+FAA+F;AAC/F,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,KAAK,CAOP"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/contract/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE;QACL,2CAA2C;QAC3C,IAAI,EAAE,MAAM,CAAC;QACb,8BAA8B;QAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,gCAAgC;QAChC,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,0BAA0B;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAcD;;;;GAIG;AACH,qBAAa,QAAQ,CACnB,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAC1F,SAAQ,KAAK;aAEK,IAAI,EAAE,KAAK;aAEX,MAAM,EAAE,MAAM;aACd,OAAO,CAAC,EAAE,QAAQ;aAClB,IAAI,CAAC,EAAE,MAAM;IAL/B,YACkB,IAAI,EAAE,KAAK,EAC3B,OAAO,CAAC,EAAE,MAAM,EACA,MAAM,GAAE,MAAY,EACpB,OAAO,CAAC,EAAE,QAAQ,YAAA,EAClB,IAAI,CAAC,EAAE,MAAM,YAAA,EAQ9B;IAED,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,QAAQ,CAEvC;IAED,MAAM,IAAI,aAAa,CAStB;CACF;AAED,qCAAqC;AACrC,wBAAgB,QAAQ,CAAC,OAAO,SAAc,GAAG,KAAK,CAErD;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAEpF;AAED,wCAAwC;AACxC,wBAAgB,YAAY,CAAC,OAAO,SAAiB,GAAG,KAAK,CAE5D;AAED,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,OAAO,SAAc,GAAG,KAAK,CAEtD;AAED,0EAA0E;AAC1E,wBAAgB,QAAQ,CAAC,OAAO,SAAa,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAEvF;AAED,wCAAwC;AACxC,wBAAgB,WAAW,CAAC,OAAO,SAAsB,GAAG,KAAK,CAEhE;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;CAUE,CAAC;AAEnC,mFAAmF;AACnF,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,mBAAmB,CAAC;AAE/D,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,eAAe,CAEvE;AAED,+FAA+F;AAC/F,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,KAAK,CAOP"}

package/dist/contract/factory.d.ts

@@ -20,13 +20,37 @@
  * The returned contracts are ordinary `ContractDef`s — `implement`, `createClient`
  * and the tool mounts treat them exactly as before.
  */
-import type { ContractDef, EndpointDef } from './define';
+import type { ContractDef, ContractMeta, EndpointDef, Transport } from './define';
+export type ContractFactoryToolExposure = 'explicit';
+export interface ContractFactoryConfig {
+    /** Missing endpoint `expose` becomes HTTP-only; every tool surface is opt-in. */
+    toolExposure: ContractFactoryToolExposure;
+}
+export type ExplicitToolExposureEndpoints<T extends Record<string, EndpointDef>> = {
+    [K in keyof T]: T[K] extends {
+        expose: readonly Transport[];
+    } ? T[K] : T[K] & {
+        expose: readonly ['HTTP'];
+    };
+};
+/** A factory-defined contract whose concrete scope remains required in metadata. */
+export interface ScopedContractDef<T extends Record<string, EndpointDef> = Record<string, EndpointDef>, TScope extends string = string> extends ContractDef<T, TScope> {
+    meta: ContractMeta<TScope> & {
+        scope: TScope;
+    };
+}
 /** A `defineContract` whose `scope` is required and typed to `TScope`. */
 export type ScopedDefineContract<TScope extends string> = <const TContractScope extends TScope, const T extends Record<string, EndpointDef>>(meta: {
     prefix: string;
     scope: TContractScope;
     meta?: Record<string, unknown>;
-}, endpoints: T) => ContractDef<T, TContractScope>;
+}, endpoints: T) => ScopedContractDef<T, TContractScope>;
+/** Scoped contract authoring where every omitted exposure becomes HTTP-only. */
+export type ExplicitScopedDefineContract<TScope extends string> = <const TContractScope extends TScope, const T extends Record<string, EndpointDef>>(meta: {
+    prefix: string;
+    scope: TContractScope;
+    meta?: Record<string, unknown>;
+}, endpoints: T) => ScopedContractDef<ExplicitToolExposureEndpoints<T>, TContractScope>;
 /**
  * Build a `defineContract` that requires a `scope` from the application's own
  * union. Call once per app and re-export the returned `defineContract`.
@@ -34,4 +58,7 @@ export type ScopedDefineContract<TScope extends string> = <const TContractScope
 export declare function createContractFactory<TScope extends string>(): {
     defineContract: ScopedDefineContract<TScope>;
 };
+export declare function createContractFactory<TScope extends string>(config: ContractFactoryConfig): {
+    defineContract: ExplicitScopedDefineContract<TScope>;
+};
 //# sourceMappingURL=factory.d.ts.map

package/dist/contract/factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/contract/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAGzD,0EAA0E;AAC1E,MAAM,MAAM,oBAAoB,CAAC,MAAM,SAAS,MAAM,IAAI,CACxD,KAAK,CAAC,cAAc,SAAS,MAAM,EACnC,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAE3C,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,cAAc,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EAC/E,SAAS,EAAE,CAAC,KACT,WAAW,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;AAEpC;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,SAAS,MAAM,KAAK;IAC9D,cAAc,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC;CAC9C,CAiBA"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/contract/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAGlF,MAAM,MAAM,2BAA2B,GAAG,UAAU,CAAC;AAErD,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,YAAY,EAAE,2BAA2B,CAAC;CAC3C;AAED,MAAM,MAAM,6BAA6B,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,IAAI;KAChF,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;QAAE,MAAM,EAAE,SAAS,SAAS,EAAE,CAAA;KAAE,GACzD,CAAC,CAAC,CAAC,CAAC,GACJ,CAAC,CAAC,CAAC,CAAC,GAAG;QAAE,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,CAAA;KAAE;CACzC,CAAC;AAEF,oFAAoF;AACpF,MAAM,WAAW,iBAAiB,CAChC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACnE,MAAM,SAAS,MAAM,GAAG,MAAM,CAC9B,SAAQ,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC;IAC9B,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAChD;AAED,0EAA0E;AAC1E,MAAM,MAAM,oBAAoB,CAAC,MAAM,SAAS,MAAM,IAAI,CACxD,KAAK,CAAC,cAAc,SAAS,MAAM,EACnC,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAE3C,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,cAAc,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EAC/E,SAAS,EAAE,CAAC,KACT,iBAAiB,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;AAE1C,gFAAgF;AAChF,MAAM,MAAM,4BAA4B,CAAC,MAAM,SAAS,MAAM,IAAI,CAChE,KAAK,CAAC,cAAc,SAAS,MAAM,EACnC,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAE3C,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,cAAc,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EAC/E,SAAS,EAAE,CAAC,KACT,iBAAiB,CAAC,6BAA6B,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;AAEzE;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,SAAS,MAAM,KAAK;IAC9D,cAAc,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC;CAC9C,CAAC;AACF,wBAAgB,qBAAqB,CAAC,MAAM,SAAS,MAAM,EACzD,MAAM,EAAE,qBAAqB,GAC5B;IACD,cAAc,EAAE,4BAA4B,CAAC,MAAM,CAAC,CAAC;CACtD,CAAC"}

package/dist/contract/index.d.ts

@@ -1,6 +1,6 @@
 export { ALL_TRANSPORTS, type BodyHttpSuccessStatus, type ContractDef, type ContractMeta, defineContract, type EndpointDef, type EndpointFn, type EndpointResponseMeta, type EndpointToolAnnotations, type EndpointUiMeta, type FileDescriptor, type HandlerContext, type HeadEndpointDef, type HttpMethod, type HttpSuccessStatus, type MultipartFile, type ResponseMetadata, type RuntimeContext, type ScopedEndpointFn, type ScopedHttpClient, type ScopedUrlBuilder, type ScopedUrlFn, type Transport, type TransportSource, type TypedClient, type TypedHttpClient, type TypedUrlBuilder, } from './define';
 export { AppError, appError, badRequest, conflict, type ErrorEnvelope, forbidden, isStitchErrorCode, notFound, rateLimited, STITCH_ERROR_STATUS, type StitchErrorCode, unauthorized, } from './errors';
-export { type DefinedErrors, defineErrors, type ErrorThrower, } from './errors-factory';
-export { createContractFactory, type ScopedDefineContract } from './factory';
+export { type DefinedAppError, type DefinedErrors, defineErrors, type ErrorDefinition, type ErrorDefinitions, type ErrorDetailsOutput, type ErrorDetailsSchema, type ErrorFactories, type ErrorFactory, type ErrorFactoryArguments, type FrozenErrorDefinitions, } from './errors-factory';
+export { type ContractFactoryConfig, type ContractFactoryToolExposure, createContractFactory, type ExplicitScopedDefineContract, type ExplicitToolExposureEndpoints, type ScopedContractDef, type ScopedDefineContract, } from './factory';
 export { decodeCursor, encodeCursor, type Paginated, paginatedSchema, } from './pagination';
 //# sourceMappingURL=index.d.ts.map

package/dist/contract/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,KAAK,aAAa,EAClB,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,KAAK,eAAe,EACpB,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,aAAa,EAClB,YAAY,EACZ,KAAK,YAAY,GAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAE7E,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,KAAK,SAAS,EACd,eAAe,GAChB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,KAAK,aAAa,EAClB,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,KAAK,eAAe,EACpB,YAAY,GACb,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,qBAAqB,EACrB,KAAK,4BAA4B,EACjC,KAAK,6BAA6B,EAClC,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,GAC1B,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,KAAK,SAAS,EACd,eAAe,GAChB,MAAM,cAAc,CAAC"}

package/dist/contract/index.js

@@ -16,8 +16,8 @@ import {
   paginatedSchema,
   rateLimited,
   unauthorized
-} from "../index-xax049k6.js";
-import"../index-809wc1tt.js";
+} from "../index-r6czv7yt.js";
+import"../index-s4qsmgwe.js";
 export {
   unauthorized,
   rateLimited,

package/dist/{index-dnkefke9.js → index-310bfer5.js}

@@ -6,7 +6,7 @@ import {
   isUnsafeKey,
   safeJsonParse,
   unauthorized
-} from "./index-sc67e454.js";
+} from "./index-gex6gxhe.js";
 
 // src/server/middleware/cookies.ts
 function parseCookies(header) {

package/dist/{index-4e1c0hsw.js → index-esqmem78.js}

@@ -22,13 +22,15 @@ import {
   parseTrailingWildcard,
   recordedErrorMessage,
   resolveSocketIp,
+  resolveTraceContext,
   resolveTraceId,
+  runWithRequestContext,
   safeJsonParse,
   setRequestEndpoint,
   setRequestError,
   typedEntries,
   validateDeclaredOutput
-} from "./index-sc67e454.js";
+} from "./index-gex6gxhe.js";
 
 // src/server/multipart.ts
 var DEFAULT_MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
@@ -484,9 +486,6 @@ function timestamp() {
   });
   return `${t}.${now.getMilliseconds().toString().padStart(3, "0")}`;
 }
-function elapsedMs(startTime) {
-  return performance.now() - startTime;
-}
 function safePath(pathname) {
   let out = "";
   for (let i = 0;i < pathname.length; i++) {
@@ -544,7 +543,7 @@ function shouldLog(pathname, method) {
   return !SKIP_PREFIXES.some((prefix) => pathname.startsWith(prefix));
 }
 function logIncoming(req, pathname, traceId, format, ipAddress) {
-  const log = { traceId, startTime: performance.now() };
+  const log = { traceId };
   if (format === "pretty") {
     const mc = METHOD_COLOR[req.method] ?? c.dim;
     console.log(`${c.gray}[${timestamp()}]${c.reset} ${mc}${req.method}${c.reset} ${c.dim}${traceId}${c.reset} ${c.cyan}→${c.reset} ${safePath(pathname)} ${ipLabel(ipAddress ?? "")}`);
@@ -560,7 +559,7 @@ function structuredLine(own, extra) {
 }
 function logOutgoing(entry) {
   const { req, pathname, status, log, ipAddress, errorCode: errorCode2, durationMs, format, extra } = entry;
-  const ms = elapsedMs(log.startTime);
+  const ms = durationMs;
   if (format === "json") {
     const own = {
       ts: new Date().toISOString(),
@@ -664,8 +663,9 @@ function applyResponseMetadata(target, metadata, endpointIdentity) {
 }
 
 // src/server/create.ts
+var BODY_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
 function createHandler(config) {
-  const { cors, hooks, logging = false, trustProxy = false } = config;
+  const { cors, hooks, logging = false, observability, trustProxy = false } = config;
   if (cors)
     assertCorsConfig(cors);
   assertJsonBodyLimit(config.maxJsonBodyBytes, "HandlerConfig.maxJsonBodyBytes");
@@ -683,17 +683,17 @@ function createHandler(config) {
   };
   let traceResolverBroken = false;
   const warnedEnrichKeys = new Set;
-  const resolveId = (req) => {
+  const resolveId = (req, fallback) => {
     if (!customTraceId)
-      return resolveTraceId(req);
+      return fallback ?? resolveTraceId(req);
     try {
-      return customTraceId(req) ?? resolveTraceId(req);
+      return customTraceId(req) ?? fallback ?? resolveTraceId(req);
     } catch (err) {
       if (!traceResolverBroken) {
         traceResolverBroken = true;
         warn("[stitchkit] `traceId` resolver threw — falling back to the framework resolver. " + "Ids will not match your observability context until it is fixed: " + `${err instanceof Error ? err.message : String(err)}`);
       }
-      return resolveTraceId(req);
+      return fallback ?? resolveTraceId(req);
     }
   };
   const routeMap = buildRouteMap(normalizeGroups(config));
@@ -704,16 +704,19 @@ function createHandler(config) {
     const line = `[stitchkit] raw route ${shadow.rawRoute} shadows contract route ${shadow.pattern}` + ` → ${shadow.endpoint}${gate} will never run, and its hooks never apply`;
     warn(line);
   }
-  async function dispatch(req, url, traceId, server, clientIp) {
+  async function dispatch(req, url, traceId, server, clientIp, startedAt) {
     const shouldLogRequest = logConfig !== null && shouldLog(url.pathname, req.method) && !shouldSkipLog(logConfig, req, url);
     const ipAddress = extractIp(req, clientIp) || undefined;
+    const payload = observability?.includePayload && BODY_METHODS.has(req.method) ? req.clone().json().catch(() => {
+      return;
+    }) : undefined;
     const logFormat = resolveLogFormat(logConfig?.format);
     let reqLog;
     if (shouldLogRequest && useDefaultLog) {
       reqLog = logIncoming(req, url.pathname, traceId, logFormat, ipAddress);
     }
     if (shouldLogRequest && customLogger) {
-      reqLog = { traceId, startTime: performance.now() };
+      reqLog = { traceId };
       try {
         customLogger.debug(`${req.method} ${url.pathname}`, {
           traceId,
@@ -723,50 +726,58 @@ function createHandler(config) {
         });
       } catch {}
     }
-    let logged = false;
-    const logDone = (status, errorCode2) => {
-      if (!reqLog || logged || !logConfig)
+    let completed = false;
+    const complete = (status, errorCode2) => {
+      if (completed)
         return;
-      logged = true;
-      try {
-        const durationMs = Math.round(elapsedMs(reqLog.startTime));
-        const collected = collectExtraLogFields(logConfig, req, url, {
-          status,
-          durationMs,
-          errorCode: errorCode2
-        });
-        const frameworkFields = buildLogFields(req.method, url.pathname, status, durationMs, reqLog.traceId, errorCode2);
-        const ownedFields = { ...frameworkFields, ip: ipAddress };
-        for (const key of collected.enrichKeys) {
-          const ownedByActiveSink = Object.hasOwn(ownedFields, key) || useDefaultLog && (key === "ts" || key === "level" || key === "msg");
-          if (ownedByActiveSink && !warnedEnrichKeys.has(key)) {
-            warnedEnrichKeys.add(key);
-            warn(`[stitchkit] logging.enrich field "${key}" was discarded because the framework owns it`);
-          }
-        }
-        const extra = collected.fields;
-        if (useDefaultLog) {
-          logOutgoing({
-            req,
-            pathname: url.pathname,
+      completed = true;
+      const durationMs = Math.round(Number(process.hrtime.bigint() - startedAt) / 1e6);
+      if (reqLog && logConfig) {
+        try {
+          const collected = collectExtraLogFields(logConfig, req, url, {
             status,
-            log: reqLog,
-            ipAddress,
-            errorCode: errorCode2,
             durationMs,
-            format: logFormat,
-            extra
+            errorCode: errorCode2
           });
-        }
-        if (customLogger) {
-          const level = levelForStatus(status);
-          customLogger[level](`${req.method} ${url.pathname} ${status}${errorCode2 ? ` ${errorCode2}` : ""} ${durationMs}ms`, {
-            ...extra,
-            ...frameworkFields,
-            ip: ipAddress
-          });
-        }
-      } catch {}
+          const frameworkFields = buildLogFields(req.method, url.pathname, status, durationMs, reqLog.traceId, errorCode2);
+          const ownedFields = { ...frameworkFields, ip: ipAddress };
+          for (const key of collected.enrichKeys) {
+            const ownedByActiveSink = Object.hasOwn(ownedFields, key) || useDefaultLog && (key === "ts" || key === "level" || key === "msg");
+            if (ownedByActiveSink && !warnedEnrichKeys.has(key)) {
+              warnedEnrichKeys.add(key);
+              warn(`[stitchkit] logging.enrich field "${key}" was discarded because the framework owns it`);
+            }
+          }
+          const extra = collected.fields;
+          if (useDefaultLog) {
+            logOutgoing({
+              req,
+              pathname: url.pathname,
+              status,
+              log: reqLog,
+              ipAddress,
+              errorCode: errorCode2,
+              durationMs,
+              format: logFormat,
+              extra
+            });
+          }
+          if (customLogger) {
+            const level = levelForStatus(status);
+            customLogger[level](`${req.method} ${url.pathname} ${status}${errorCode2 ? ` ${errorCode2}` : ""} ${durationMs}ms`, {
+              ...extra,
+              ...frameworkFields,
+              ip: ipAddress
+            });
+          }
+        } catch {}
+      }
+      const context = getRequestContext();
+      if (observability && context) {
+        try {
+          observability.complete({ context, statusCode: status, durationMs, payload });
+        } catch {}
+      }
     };
     const respondError = async (err, errCtx, endpoint) => {
       const recordFailure = (normalized) => {
@@ -786,25 +797,27 @@ function createHandler(config) {
           if (response instanceof Response) {
             recordFailure();
             const withCors = applyCors(response, cors, req);
-            logDone(withCors.status, errorCode(err));
+            complete(withCors.status, errorCode(err));
             return withCors;
           }
         } catch {}
       }
       const appErr = normalizeError(err);
       recordFailure(appErr);
-      logDone(appErr.status, appErr.code);
+      complete(appErr.status, appErr.code);
       return json(appErr.toJSON(), appErr.status, cors, req);
     };
     if (cors && req.method === "OPTIONS") {
-      return corsPreflightResponse(cors, req);
+      const response = corsPreflightResponse(cors, req);
+      complete(response.status);
+      return response;
     }
     try {
       if (hooks?.onRequest) {
         const earlyResponse = await hooks.onRequest(req);
         if (earlyResponse instanceof Response) {
           const withCors = applyCors(earlyResponse, cors, req);
-          logDone(withCors.status);
+          complete(withCors.status);
           return withCors;
         }
       }
@@ -821,7 +834,7 @@ function createHandler(config) {
             ipAddress
           });
           const withCors = applyCors(res, cors, req);
-          logDone(withCors.status);
+          complete(withCors.status);
           return withCors;
         } catch (err) {
           return respondError(err);
@@ -863,7 +876,7 @@ function createHandler(config) {
           headers: result.headers
         }) : result;
         const rawRes = applyCors(response, cors, req);
-        logDone(rawRes.status);
+        complete(rawRes.status);
         return rawRes;
       }
       if (groupHooks?.afterHandle) {
@@ -894,11 +907,11 @@ function createHandler(config) {
       applyResponseMetadata(responseHeaders, responseMetadata, `${method.serviceName}.${method.key}`);
       if (!method.outputSchema) {
         const empty = new Response(null, { status: responseStatus, headers: responseHeaders });
-        logDone(responseStatus);
+        complete(responseStatus);
         return empty;
       }
       const body = Response.json(result, { status: responseStatus, headers: responseHeaders });
-      logDone(responseStatus);
+      complete(responseStatus);
       return body;
     } catch (err) {
       return respondError(err, ctx, method);
@@ -906,16 +919,37 @@ function createHandler(config) {
   }
   return async (req, server) => {
     const url = new URL(req.url, "http://localhost");
-    const traceId = resolveId(req);
+    const requestStartedAt = process.hrtime.bigint();
     const clientIp = {
       trustProxy,
       socketIp: resolveSocketIp(req, server)
     };
-    const response = await dispatch(req, url, traceId, server, clientIp);
-    try {
-      response.headers.set("x-request-id", traceId);
-    } catch {}
-    return response;
+    const run = async (traceId2, startedAt) => {
+      const response = await dispatch(req, url, traceId2, server, clientIp, startedAt);
+      try {
+        response.headers.set("x-request-id", traceId2);
+      } catch {}
+      return response;
+    };
+    const activeContext = getRequestContext();
+    if (activeContext) {
+      return run(activeContext.trace.traceId, activeContext.startedAt);
+    }
+    if (!observability)
+      return run(resolveId(req), requestStartedAt);
+    const trace = resolveTraceContext(req);
+    const traceId = resolveId(req, trace.traceId);
+    const ipAddress = extractIp(req, clientIp) || undefined;
+    const userAgent = req.headers.get("user-agent") ?? undefined;
+    return runWithRequestContext({
+      source: "http",
+      method: req.method,
+      path: url.pathname,
+      startedAt: requestStartedAt,
+      trace: { ...trace, traceId },
+      ...ipAddress !== undefined && { ipAddress },
+      ...userAgent !== undefined && { userAgent }
+    }, () => run(traceId, requestStartedAt));
   };
 }
 function normalizeGroups(config) {