@defai.digital/ax-cli 3.8.6 → 3.8.7

package/packages/schemas/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @ax-cli/schemas - Single Source of Truth Type System
+ *
+ * This package provides centralized Zod schemas, brand types, and enums
+ * for the entire ax-cli ecosystem.
+ *
+ * SECURITY: All exports are controlled. Internal helpers are not exposed.
+ *
+ * @packageDocumentation
+ */
+export { brand, unbrand, isBranded, createBrandFactory, type __brand, type Brand, type ExtractBrand, type ExtractBase, } from './public/core/brand-types.js';
+export { ApiResponseId, ToolCallId, ToolCallIdSchema, ModelId, ModelIdSchema, TenantId, ApiKeyId, MCPServerId, MCPServerIdSchema, UsageRecordId, PlanId, SessionId, RequestId, type ApiResponseId as ApiResponseIdType, type ToolCallId as ToolCallIdType, type ModelId as ModelIdType, type TenantId as TenantIdType, type ApiKeyId as ApiKeyIdType, type MCPServerId as MCPServerIdType, type UsageRecordId as UsageRecordIdType, type PlanId as PlanIdType, type SessionId as SessionIdType, type RequestId as RequestIdType, } from './public/core/id-types.js';
+export { MessageRoleEnum, FinishReasonEnum, TransportEnum, EditorCommandEnum, type MessageRole, type FinishReason, type Transport, type EditorCommand, } from './public/core/enums.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/schemas/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EACL,KAAK,EACL,OAAO,EACP,SAAS,EACT,kBAAkB,EAClB,KAAK,OAAO,EACZ,KAAK,KAAK,EACV,KAAK,YAAY,EACjB,KAAK,WAAW,GACjB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACL,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,OAAO,EACP,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,MAAM,EACN,SAAS,EACT,SAAS,EACT,KAAK,aAAa,IAAI,iBAAiB,EACvC,KAAK,UAAU,IAAI,cAAc,EACjC,KAAK,OAAO,IAAI,WAAW,EAC3B,KAAK,QAAQ,IAAI,YAAY,EAC7B,KAAK,QAAQ,IAAI,YAAY,EAC7B,KAAK,WAAW,IAAI,eAAe,EACnC,KAAK,aAAa,IAAI,iBAAiB,EACvC,KAAK,MAAM,IAAI,UAAU,EACzB,KAAK,SAAS,IAAI,aAAa,EAC/B,KAAK,SAAS,IAAI,aAAa,GAChC,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,aAAa,GACnB,MAAM,wBAAwB,CAAC"}

package/packages/schemas/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @ax-cli/schemas - Single Source of Truth Type System
+ *
+ * This package provides centralized Zod schemas, brand types, and enums
+ * for the entire ax-cli ecosystem.
+ *
+ * SECURITY: All exports are controlled. Internal helpers are not exposed.
+ *
+ * @packageDocumentation
+ */
+// Core brand type utilities
+export { brand, unbrand, isBranded, createBrandFactory, } from './public/core/brand-types.js';
+// ID Brand Types
+export { ApiResponseId, ToolCallId, ToolCallIdSchema, ModelId, ModelIdSchema, TenantId, ApiKeyId, MCPServerId, MCPServerIdSchema, UsageRecordId, PlanId, SessionId, RequestId, } from './public/core/id-types.js';
+// Centralized Enums
+export { MessageRoleEnum, FinishReasonEnum, TransportEnum, EditorCommandEnum, } from './public/core/enums.js';
+// Additional exports will be added as we implement them:
+// - Domain schemas (Usage, API, MCP)
+//# sourceMappingURL=index.js.map

package/packages/schemas/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,4BAA4B;AAC5B,OAAO,EACL,KAAK,EACL,OAAO,EACP,SAAS,EACT,kBAAkB,GAKnB,MAAM,8BAA8B,CAAC;AAEtC,iBAAiB;AACjB,OAAO,EACL,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,OAAO,EACP,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,MAAM,EACN,SAAS,EACT,SAAS,GAWV,MAAM,2BAA2B,CAAC;AAEnC,oBAAoB;AACpB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,iBAAiB,GAKlB,MAAM,wBAAwB,CAAC;AAEhC,yDAAyD;AACzD,qCAAqC"}

package/packages/schemas/dist/public/core/brand-types.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Brand Types Utilities for @ax-cli/schemas
+ *
+ * CRITICAL SECURITY WARNING:
+ * =========================
+ * Brand types are COMPILE-TIME ONLY markers. They provide ZERO runtime validation.
+ *
+ * **YOU MUST VALIDATE ALL INPUTS AT SYSTEM BOUNDARIES**
+ *
+ * Unsafe usage (WILL FAIL IN PRODUCTION):
+ * ```typescript
+ * const tenantId = userInput as TenantId; // ❌ NO RUNTIME VALIDATION!
+ * ```
+ *
+ * Safe usage (REQUIRED):
+ * ```typescript
+ * const result = TenantId.parse(userInput); // ✅ Validates with Zod
+ * if (result.success) {
+ *   const tenantId = result.data; // Type-safe AND runtime-safe
+ * }
+ * ```
+ *
+ * WHEN TO USE BRAND TYPES:
+ * - Preventing ID mixing at compile time (ApiKeyId vs TenantId)
+ * - Enforcing domain boundaries in function signatures
+ * - Type-level documentation of intent
+ *
+ * WHEN TO VALIDATE:
+ * - API boundaries (HTTP requests, MCP inputs)
+ * - File I/O (reading configs, user settings)
+ * - Database queries (WHERE clauses with user IDs)
+ * - Environment variables
+ * - Command-line arguments
+ *
+ * PERFORMANCE:
+ * Brand types have ZERO runtime cost. They are erased during compilation.
+ *
+ * @module brand-types
+ * @see {@link https://github.com/microsoft/TypeScript/issues/4895|TypeScript Nominal Types}
+ */
+/**
+ * Unique symbol used as a phantom type marker for branding.
+ * This symbol is exported for type compatibility but cannot be accessed at runtime,
+ * making it impossible to forge branded types without using the
+ * provided constructor functions.
+ *
+ * @internal
+ */
+export declare const __brand: unique symbol;
+/**
+ * Brand<T, B> creates a "nominal type" from a structural type.
+ *
+ * TypeScript uses structural typing by default:
+ * ```typescript
+ * type UserId = string;
+ * type TenantId = string;
+ *
+ * const user: UserId = "user-123";
+ * const tenant: TenantId = user; // ✅ No error! Strings are compatible.
+ * ```
+ *
+ * Brand types enforce nominal typing:
+ * ```typescript
+ * type UserId = Brand<string, 'UserId'>;
+ * type TenantId = Brand<string, 'TenantId'>;
+ *
+ * const user = brand<string, 'UserId'>("user-123");
+ * const tenant: TenantId = user; // ❌ Compile error! Incompatible brands.
+ * ```
+ *
+ * @template T - The base type (string, number, etc.)
+ * @template B - The brand identifier (unique string literal)
+ *
+ * @example
+ * ```typescript
+ * type ApiKeyId = Brand<string, 'ApiKeyId'>;
+ * type TenantId = Brand<string, 'TenantId'>;
+ *
+ * function updateUsage(apiKeyId: ApiKeyId, tenantId: TenantId) {
+ *   // This function signature makes it impossible to swap arguments
+ * }
+ *
+ * const apiKey = brand<string, 'ApiKeyId'>("ak_123");
+ * const tenant = brand<string, 'TenantId'>("tn_456");
+ *
+ * updateUsage(apiKey, tenant);        // ✅ Correct
+ * updateUsage(tenant, apiKey);        // ❌ Compile error!
+ * updateUsage("ak_123", "tn_456");    // ❌ Compile error!
+ * ```
+ */
+export type Brand<T, B extends string> = T & {
+    readonly [__brand]: B;
+};
+/**
+ * Creates a branded value.
+ *
+ * WARNING: This function performs NO VALIDATION. It is a type-level assertion only.
+ *
+ * Use this ONLY in trusted contexts after validation:
+ * - Inside schema .transform() after Zod validation
+ * - After database queries that return validated data
+ * - In test fixtures with known-good values
+ *
+ * DO NOT use with user input directly:
+ * ```typescript
+ * // ❌ UNSAFE - No validation!
+ * const userId = brand<string, 'UserId'>(req.body.userId);
+ *
+ * // ✅ SAFE - Validated first
+ * const result = UserIdSchema.safeParse(req.body.userId);
+ * if (result.success) {
+ *   const userId = result.data; // Already branded by schema
+ * }
+ * ```
+ *
+ * @template T - The base type
+ * @template B - The brand identifier
+ * @param value - The value to brand
+ * @returns The same value, but with a brand type
+ *
+ * @example
+ * ```typescript
+ * // Safe usage in tests
+ * const mockTenantId = brand<string, 'TenantId'>("test-tenant-123");
+ *
+ * // Safe usage after validation
+ * const schema = z.string().uuid().transform(v => brand<string, 'TenantId'>(v));
+ * const tenantId = schema.parse(userInput); // Validated AND branded
+ * ```
+ */
+export declare function brand<T, B extends string>(value: T): Brand<T, B>;
+/**
+ * Type guard to check if a value is already branded with a specific brand.
+ *
+ * NOTE: This only works if the value was created using the brand() function.
+ * It CANNOT detect fake brands created with `as` casts.
+ *
+ * @template T - The base type
+ * @template B - The brand identifier
+ * @param value - The value to check
+ * @returns true if the value has the correct brand (compile-time only)
+ *
+ * @example
+ * ```typescript
+ * const value: string | TenantId = getTenantId();
+ *
+ * if (isBranded<string, 'TenantId'>(value)) {
+ *   const tenantId: TenantId = value; // TypeScript knows it's branded
+ * }
+ * ```
+ */
+export declare function isBranded<T, B extends string>(_value: unknown): _value is Brand<T, B>;
+/**
+ * Removes the brand from a branded type, returning the base type.
+ *
+ * Use this when you need to pass a branded value to a function that
+ * expects the base type (e.g., logging, serialization).
+ *
+ * @template T - The base type
+ * @template B - The brand identifier
+ * @param value - The branded value
+ * @returns The same value, but with the brand removed
+ *
+ * @example
+ * ```typescript
+ * const tenantId: TenantId = getTenantId();
+ *
+ * // Pass to function expecting plain string
+ * console.log(unbrand(tenantId)); // string, not TenantId
+ *
+ * // Serialize to JSON
+ * const json = JSON.stringify({ id: unbrand(tenantId) });
+ * ```
+ */
+export declare function unbrand<T, B extends string>(value: Brand<T, B>): T;
+/**
+ * Utility type to extract the brand identifier from a branded type.
+ *
+ * @template T - The branded type
+ *
+ * @example
+ * ```typescript
+ * type TenantId = Brand<string, 'TenantId'>;
+ * type BrandName = ExtractBrand<TenantId>; // 'TenantId'
+ * ```
+ */
+export type ExtractBrand<T> = T extends Brand<unknown, infer B> ? B : never;
+/**
+ * Utility type to extract the base type from a branded type.
+ *
+ * @template T - The branded type
+ *
+ * @example
+ * ```typescript
+ * type TenantId = Brand<string, 'TenantId'>;
+ * type BaseType = ExtractBase<TenantId>; // string
+ * ```
+ */
+export type ExtractBase<T> = T extends Brand<infer U, string> ? U : T;
+/**
+ * Creates a type-safe brand factory with validation.
+ *
+ * This is the RECOMMENDED way to create brand types with runtime validation.
+ *
+ * @template T - The base type
+ * @template B - The brand identifier
+ * @param schema - Zod schema for validation
+ * @param brandName - The brand identifier
+ * @returns Object with parse, create, and is methods
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * const TenantId = createBrandFactory(
+ *   z.string().uuid(),
+ *   'TenantId'
+ * );
+ *
+ * // Type-safe parsing with validation
+ * const result = TenantId.parse(userInput);
+ * if (result.success) {
+ *   const tenantId = result.data; // Brand<string, 'TenantId'>
+ * }
+ *
+ * // Create new ID
+ * const newId = TenantId.create(); // Generates UUID
+ *
+ * // Type guard
+ * if (TenantId.is(value)) {
+ *   // value is Brand<string, 'TenantId'>
+ * }
+ * ```
+ */
+export declare function createBrandFactory<T, B extends string>(schema: {
+    parse: (input: unknown) => T;
+    safeParse: (input: unknown) => {
+        success: boolean;
+        data?: T;
+        error?: unknown;
+    };
+}, brandName: B): {
+    /**
+     * The Zod schema with brand transformation.
+     */
+    schema: {
+        parse: (input: unknown) => Brand<T, B>;
+        safeParse: (input: unknown) => {
+            success: true;
+            data: Brand<T, B>;
+        } | {
+            success: false;
+            error: unknown;
+        };
+    };
+    /**
+     * Parse and validate input, returning branded value.
+     * Throws on validation failure.
+     */
+    parse: (input: unknown) => Brand<T, B>;
+    /**
+     * Type guard to check if a value is this brand.
+     */
+    is: (value: unknown) => value is Brand<T, B>;
+    /**
+     * Brand name identifier.
+     */
+    brandName: B;
+};
+/**
+ * BEST PRACTICES SUMMARY:
+ * =======================
+ *
+ * 1. ALWAYS validate at boundaries:
+ *    - API inputs: Use Zod schemas
+ *    - Database outputs: Use Zod schemas
+ *    - File I/O: Use Zod schemas
+ *    - CLI args: Use Zod schemas
+ *
+ * 2. NEVER cast to brand types:
+ *    ❌ const id = userInput as TenantId;
+ *    ✅ const id = TenantIdSchema.parse(userInput);
+ *
+ * 3. Use createBrandFactory for all brand types:
+ *    - Provides validation
+ *    - Provides type guards
+ *    - Centralizes brand creation
+ *
+ * 4. Document which functions validate:
+ *    ```typescript
+ *    // @validates TenantId - performs Zod validation
+ *    function parseTenantId(input: string): TenantId {
+ *      return TenantIdSchema.parse(input);
+ *    }
+ *
+ *    // @assumes TenantId - no validation, requires validated input
+ *    function formatTenantId(id: TenantId): string {
+ *      return `tenant:${unbrand(id)}`;
+ *    }
+ *    ```
+ *
+ * 5. Test brand type enforcement:
+ *    ```typescript
+ *    // Should fail to compile
+ *    const apiKey: ApiKeyId = getTenantId(); // ❌
+ *    ```
+ */
+//# sourceMappingURL=brand-types.d.ts.map

package/packages/schemas/dist/public/core/brand-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand-types.d.ts","sourceRoot":"","sources":["../../../src/public/core/brand-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,OAAO,CAAC,MAAM,OAAO,EAAE,OAAO,MAAM,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,CAAC,GAAG;IAAE,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;CAAE,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAEhE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,EAC3C,MAAM,EAAE,OAAO,GACd,MAAM,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAIvB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAElE;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE5E;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,EACpD,MAAM,EAAE;IAAE,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,CAAC;IAAC,SAAS,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,EACxH,SAAS,EAAE,CAAC;IAGV;;OAEG;;uBAEc,OAAO,KAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;2BAIjB,OAAO,KAAG;YAAE,OAAO,EAAE,IAAI,CAAC;YAAC,IAAI,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;SAAE,GAAG;YAAE,OAAO,EAAE,KAAK,CAAC;YAAC,KAAK,EAAE,OAAO,CAAA;SAAE;;IASxG;;;OAGG;mBACY,OAAO,KAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;IAKpC;;OAEG;gBACS,OAAO,KAAG,KAAK,IAAI,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;IAK1C;;OAEG;;EAGN;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG"}

package/packages/schemas/dist/public/core/brand-types.js

@@ -0,0 +1,243 @@
+/**
+ * Brand Types Utilities for @ax-cli/schemas
+ *
+ * CRITICAL SECURITY WARNING:
+ * =========================
+ * Brand types are COMPILE-TIME ONLY markers. They provide ZERO runtime validation.
+ *
+ * **YOU MUST VALIDATE ALL INPUTS AT SYSTEM BOUNDARIES**
+ *
+ * Unsafe usage (WILL FAIL IN PRODUCTION):
+ * ```typescript
+ * const tenantId = userInput as TenantId; // ❌ NO RUNTIME VALIDATION!
+ * ```
+ *
+ * Safe usage (REQUIRED):
+ * ```typescript
+ * const result = TenantId.parse(userInput); // ✅ Validates with Zod
+ * if (result.success) {
+ *   const tenantId = result.data; // Type-safe AND runtime-safe
+ * }
+ * ```
+ *
+ * WHEN TO USE BRAND TYPES:
+ * - Preventing ID mixing at compile time (ApiKeyId vs TenantId)
+ * - Enforcing domain boundaries in function signatures
+ * - Type-level documentation of intent
+ *
+ * WHEN TO VALIDATE:
+ * - API boundaries (HTTP requests, MCP inputs)
+ * - File I/O (reading configs, user settings)
+ * - Database queries (WHERE clauses with user IDs)
+ * - Environment variables
+ * - Command-line arguments
+ *
+ * PERFORMANCE:
+ * Brand types have ZERO runtime cost. They are erased during compilation.
+ *
+ * @module brand-types
+ * @see {@link https://github.com/microsoft/TypeScript/issues/4895|TypeScript Nominal Types}
+ */
+/**
+ * Creates a branded value.
+ *
+ * WARNING: This function performs NO VALIDATION. It is a type-level assertion only.
+ *
+ * Use this ONLY in trusted contexts after validation:
+ * - Inside schema .transform() after Zod validation
+ * - After database queries that return validated data
+ * - In test fixtures with known-good values
+ *
+ * DO NOT use with user input directly:
+ * ```typescript
+ * // ❌ UNSAFE - No validation!
+ * const userId = brand<string, 'UserId'>(req.body.userId);
+ *
+ * // ✅ SAFE - Validated first
+ * const result = UserIdSchema.safeParse(req.body.userId);
+ * if (result.success) {
+ *   const userId = result.data; // Already branded by schema
+ * }
+ * ```
+ *
+ * @template T - The base type
+ * @template B - The brand identifier
+ * @param value - The value to brand
+ * @returns The same value, but with a brand type
+ *
+ * @example
+ * ```typescript
+ * // Safe usage in tests
+ * const mockTenantId = brand<string, 'TenantId'>("test-tenant-123");
+ *
+ * // Safe usage after validation
+ * const schema = z.string().uuid().transform(v => brand<string, 'TenantId'>(v));
+ * const tenantId = schema.parse(userInput); // Validated AND branded
+ * ```
+ */
+export function brand(value) {
+    return value;
+}
+/**
+ * Type guard to check if a value is already branded with a specific brand.
+ *
+ * NOTE: This only works if the value was created using the brand() function.
+ * It CANNOT detect fake brands created with `as` casts.
+ *
+ * @template T - The base type
+ * @template B - The brand identifier
+ * @param value - The value to check
+ * @returns true if the value has the correct brand (compile-time only)
+ *
+ * @example
+ * ```typescript
+ * const value: string | TenantId = getTenantId();
+ *
+ * if (isBranded<string, 'TenantId'>(value)) {
+ *   const tenantId: TenantId = value; // TypeScript knows it's branded
+ * }
+ * ```
+ */
+export function isBranded(_value) {
+    // At runtime, branded types are indistinguishable from their base type
+    // This function exists only for type narrowing
+    return true;
+}
+/**
+ * Removes the brand from a branded type, returning the base type.
+ *
+ * Use this when you need to pass a branded value to a function that
+ * expects the base type (e.g., logging, serialization).
+ *
+ * @template T - The base type
+ * @template B - The brand identifier
+ * @param value - The branded value
+ * @returns The same value, but with the brand removed
+ *
+ * @example
+ * ```typescript
+ * const tenantId: TenantId = getTenantId();
+ *
+ * // Pass to function expecting plain string
+ * console.log(unbrand(tenantId)); // string, not TenantId
+ *
+ * // Serialize to JSON
+ * const json = JSON.stringify({ id: unbrand(tenantId) });
+ * ```
+ */
+export function unbrand(value) {
+    return value;
+}
+/**
+ * Creates a type-safe brand factory with validation.
+ *
+ * This is the RECOMMENDED way to create brand types with runtime validation.
+ *
+ * @template T - The base type
+ * @template B - The brand identifier
+ * @param schema - Zod schema for validation
+ * @param brandName - The brand identifier
+ * @returns Object with parse, create, and is methods
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * const TenantId = createBrandFactory(
+ *   z.string().uuid(),
+ *   'TenantId'
+ * );
+ *
+ * // Type-safe parsing with validation
+ * const result = TenantId.parse(userInput);
+ * if (result.success) {
+ *   const tenantId = result.data; // Brand<string, 'TenantId'>
+ * }
+ *
+ * // Create new ID
+ * const newId = TenantId.create(); // Generates UUID
+ *
+ * // Type guard
+ * if (TenantId.is(value)) {
+ *   // value is Brand<string, 'TenantId'>
+ * }
+ * ```
+ */
+export function createBrandFactory(schema, brandName) {
+    return {
+        /**
+         * The Zod schema with brand transformation.
+         */
+        schema: {
+            parse: (input) => {
+                const validated = schema.parse(input);
+                return brand(validated);
+            },
+            safeParse: (input) => {
+                const result = schema.safeParse(input);
+                if (result.success) {
+                    return { success: true, data: brand(result.data) };
+                }
+                return { success: false, error: result.error };
+            },
+        },
+        /**
+         * Parse and validate input, returning branded value.
+         * Throws on validation failure.
+         */
+        parse: (input) => {
+            const validated = schema.parse(input);
+            return brand(validated);
+        },
+        /**
+         * Type guard to check if a value is this brand.
+         */
+        is: (value) => {
+            const result = schema.safeParse(value);
+            return result.success;
+        },
+        /**
+         * Brand name identifier.
+         */
+        brandName,
+    };
+}
+/**
+ * BEST PRACTICES SUMMARY:
+ * =======================
+ *
+ * 1. ALWAYS validate at boundaries:
+ *    - API inputs: Use Zod schemas
+ *    - Database outputs: Use Zod schemas
+ *    - File I/O: Use Zod schemas
+ *    - CLI args: Use Zod schemas
+ *
+ * 2. NEVER cast to brand types:
+ *    ❌ const id = userInput as TenantId;
+ *    ✅ const id = TenantIdSchema.parse(userInput);
+ *
+ * 3. Use createBrandFactory for all brand types:
+ *    - Provides validation
+ *    - Provides type guards
+ *    - Centralizes brand creation
+ *
+ * 4. Document which functions validate:
+ *    ```typescript
+ *    // @validates TenantId - performs Zod validation
+ *    function parseTenantId(input: string): TenantId {
+ *      return TenantIdSchema.parse(input);
+ *    }
+ *
+ *    // @assumes TenantId - no validation, requires validated input
+ *    function formatTenantId(id: TenantId): string {
+ *      return `tenant:${unbrand(id)}`;
+ *    }
+ *    ```
+ *
+ * 5. Test brand type enforcement:
+ *    ```typescript
+ *    // Should fail to compile
+ *    const apiKey: ApiKeyId = getTenantId(); // ❌
+ *    ```
+ */
+//# sourceMappingURL=brand-types.js.map

package/packages/schemas/dist/public/core/brand-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand-types.js","sourceRoot":"","sources":["../../../src/public/core/brand-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAuDH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,UAAU,KAAK,CAAsB,KAAQ;IACjD,OAAO,KAAoB,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,SAAS,CACvB,MAAe;IAEf,uEAAuE;IACvE,+CAA+C;IAC/C,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,OAAO,CAAsB,KAAkB;IAC7D,OAAO,KAAU,CAAC;AACpB,CAAC;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAwH,EACxH,SAAY;IAEZ,OAAO;QACL;;WAEG;QACH,MAAM,EAAE;YACN,KAAK,EAAE,CAAC,KAAc,EAAe,EAAE;gBACrC,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBACtC,OAAO,KAAK,CAAO,SAAS,CAAC,CAAC;YAChC,CAAC;YACD,SAAS,EAAE,CAAC,KAAc,EAA6E,EAAE;gBACvG,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;gBACvC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;oBACnB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAO,MAAM,CAAC,IAAS,CAAC,EAAE,CAAC;gBAChE,CAAC;gBACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;YACjD,CAAC;SACF;QAED;;;WAGG;QACH,KAAK,EAAE,CAAC,KAAc,EAAe,EAAE;YACrC,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACtC,OAAO,KAAK,CAAO,SAAS,CAAC,CAAC;QAChC,CAAC;QAED;;WAEG;QACH,EAAE,EAAE,CAAC,KAAc,EAAwB,EAAE;YAC3C,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACvC,OAAO,MAAM,CAAC,OAAO,CAAC;QACxB,CAAC;QAED;;WAEG;QACH,SAAS;KACV,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG"}