@vurb/core 3.2.0

package/dist/core/schema/SchemaGenerator.js

@@ -0,0 +1,192 @@
+/**
+ * SchemaGenerator — JSON Schema Input Schema Strategy
+ *
+ * Generates MCP-compatible inputSchema from Zod definitions:
+ * - Discriminator enum from action keys
+ * - Common + per-action schema merging (with omitCommon support)
+ * - Per-field annotations (required-for / optional-for)
+ *
+ * Pure-function module: no state, no side effects.
+ */
+import {} from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import {} from '@modelcontextprotocol/sdk/types.js';
+import {} from '../types.js';
+import { assertFieldCompatibility } from './SchemaUtils.js';
+import { isPresenter } from '../../presenter/Presenter.js';
+// ── Public API ───────────────────────────────────────────
+export function generateInputSchema(actions, discriminator, hasGroup, commonSchema, selectEnabled = false) {
+    const actionKeys = actions.map(a => a.key);
+    const properties = {};
+    const topLevelRequired = [discriminator];
+    const fieldActions = new Map();
+    addDiscriminatorProperty(properties, discriminator, actionKeys, hasGroup);
+    const omitSets = buildOmitSets(actions);
+    const commonRequiredFields = collectCommonFields(commonSchema, actionKeys, omitSets, properties, topLevelRequired, fieldActions);
+    collectActionFields(actions, properties, fieldActions);
+    applyAnnotations(fieldActions, commonRequiredFields, actionKeys, properties);
+    // ── _select Reflection (opt-in) ──────────────────────
+    if (selectEnabled) {
+        injectSelectProperty(actions, properties);
+    }
+    return {
+        type: 'object',
+        properties,
+        required: topLevelRequired,
+    };
+}
+// ── Internal Steps ───────────────────────────────────────
+/** Step 1: Add the discriminator enum property */
+function addDiscriminatorProperty(properties, discriminator, actionKeys, hasGroup) {
+    properties[discriminator] = {
+        type: 'string',
+        enum: actionKeys,
+        description: hasGroup
+            ? `Module and operation (module.${discriminator} format)`
+            : 'Which operation to perform',
+    };
+}
+/** Build per-action omit sets for O(1) field exclusion checks */
+function buildOmitSets(actions) {
+    const sets = new Map();
+    for (const action of actions) {
+        if ((action.omitCommonFields?.length ?? 0) > 0) {
+            sets.set(action.key, new Set(action.omitCommonFields));
+        }
+    }
+    return sets;
+}
+/**
+ * Step 2: Process commonSchema fields.
+ *
+ * Omitted fields are excluded from per-action tracking.
+ * Fields required by ALL actions go to topLevelRequired.
+ *
+ * @returns The set of common required field names (for annotation logic)
+ */
+function collectCommonFields(commonSchema, actionKeys, omitSets, properties, topLevelRequired, fieldActions) {
+    const commonRequiredFields = new Set();
+    if (!commonSchema)
+        return commonRequiredFields;
+    const jsonSchema = zodToJsonSchema(commonSchema, { target: 'jsonSchema7' });
+    const schemaProps = jsonSchema.properties ?? {};
+    const schemaRequired = jsonSchema.required ?? [];
+    for (const field of schemaRequired) {
+        commonRequiredFields.add(field);
+    }
+    for (const [key, value] of Object.entries(schemaProps)) {
+        const actionsUsingField = actionKeys.filter(ak => {
+            const omitSet = omitSets.get(ak);
+            return !omitSet || !omitSet.has(key);
+        });
+        // If no action uses the field, skip it entirely
+        if (actionsUsingField.length === 0)
+            continue;
+        properties[key] = value;
+        // Only add to topLevelRequired if ALL actions use this field
+        if (commonRequiredFields.has(key) && actionsUsingField.length === actionKeys.length) {
+            topLevelRequired.push(key);
+        }
+        fieldActions.set(key, {
+            keys: [...actionsUsingField],
+            requiredIn: commonRequiredFields.has(key) ? [...actionsUsingField] : [],
+        });
+    }
+    return commonRequiredFields;
+}
+/** Step 3: Collect per-action schema fields with compatibility checks */
+function collectActionFields(actions, properties, fieldActions) {
+    for (const action of actions) {
+        if (!action.schema)
+            continue;
+        const jsonSchema = zodToJsonSchema(action.schema, { target: 'jsonSchema7' });
+        const schemaProps = jsonSchema.properties ?? {};
+        const schemaRequired = jsonSchema.required ?? [];
+        const requiredSet = new Set(schemaRequired);
+        for (const [key, value] of Object.entries(schemaProps)) {
+            const existing = properties[key];
+            if (!existing) {
+                properties[key] = value;
+            }
+            else {
+                const merged = assertFieldCompatibility(existing, value, key, action.key);
+                if (merged) {
+                    properties[key] = merged;
+                }
+            }
+            let tracking = fieldActions.get(key);
+            if (!tracking) {
+                tracking = { keys: [], requiredIn: [] };
+                fieldActions.set(key, tracking);
+            }
+            tracking.keys.push(action.key);
+            if (requiredSet.has(key)) {
+                tracking.requiredIn.push(action.key);
+            }
+        }
+    }
+}
+/** Step 4: Apply per-field annotations based on tracking data */
+function applyAnnotations(fieldActions, commonRequiredFields, actionKeys, properties) {
+    for (const [key, tracking] of fieldActions.entries()) {
+        if (commonRequiredFields.has(key) && tracking.keys.length === actionKeys.length) {
+            annotateField(properties, key, '(always required)');
+        }
+        else if (tracking.requiredIn.length > 0 && tracking.requiredIn.length === tracking.keys.length) {
+            annotateField(properties, key, `Required for: ${tracking.requiredIn.join(', ')}`);
+        }
+        else if (tracking.requiredIn.length > 0) {
+            const optionalIn = tracking.keys.filter(k => !tracking.requiredIn.includes(k));
+            let annotation = `Required for: ${tracking.requiredIn.join(', ')}`;
+            if (optionalIn.length > 0) {
+                annotation += `. For: ${optionalIn.join(', ')}`;
+            }
+            annotateField(properties, key, annotation);
+        }
+        else {
+            annotateField(properties, key, `For: ${tracking.keys.join(', ')}`);
+        }
+    }
+}
+function annotateField(properties, key, annotation) {
+    const field = properties[key];
+    if (!field)
+        return;
+    const existingDesc = field.description ?? '';
+    field.description = existingDesc
+        ? `${existingDesc}. ${annotation}`
+        : annotation;
+}
+// ── _select Reflection ───────────────────────────────────
+/**
+ * Inject `_select` property into the input schema.
+ *
+ * Collects the union of all top-level schema keys from Presenters
+ * across all actions. If any action has a Presenter with extractable
+ * keys, a `_select` optional array property is added with an enum
+ * constraint of those keys.
+ *
+ * **Top-level only**: The enum lists root-level keys only.
+ * Nested objects are returned whole when selected.
+ */
+function injectSelectProperty(actions, properties) {
+    const allKeys = new Set();
+    for (const action of actions) {
+        if (action.returns && isPresenter(action.returns)) {
+            for (const key of action.returns.getSchemaKeys()) {
+                allKeys.add(key);
+            }
+        }
+    }
+    if (allKeys.size === 0)
+        return;
+    properties['_select'] = {
+        type: 'array',
+        description: '⚡ Context optimization: select only the response fields you need. Omit to receive all fields.',
+        items: {
+            type: 'string',
+            enum: [...allKeys].sort(),
+        },
+    };
+}
+//# sourceMappingURL=SchemaGenerator.js.map

package/dist/core/schema/SchemaGenerator.js.map

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

package/dist/core/schema/SchemaUtils.d.ts

@@ -0,0 +1,26 @@
+/**
+ * SchemaUtils — Shared Schema Inspection & Validation Utilities
+ *
+ * Extracted helpers for inspecting Zod schema metadata and
+ * asserting JSON Schema field compatibility across actions.
+ *
+ * Used by: SchemaGenerator, DescriptionGenerator, ToonDescriptionGenerator.
+ *
+ * Pure-function module: no state, no side effects.
+ */
+import { type ZodObject, type ZodRawShape } from 'zod';
+import { type InternalAction } from '../types.js';
+/**
+ * Check if a value is a Zod schema (has `_def` property).
+ *
+ * Used by `defineTool` and `definePrompt` to distinguish
+ * Zod schemas from JSON descriptor objects.
+ */
+export declare function isZodSchema(value: unknown): value is ZodObject<ZodRawShape>;
+/**
+ * Get the list of required field names from an action's Zod schema.
+ * Returns an empty array if the action has no schema.
+ */
+export declare function getActionRequiredFields<TContext>(action: InternalAction<TContext>): string[];
+export declare function assertFieldCompatibility(existing: object, incoming: object, field: string, actionKey: string): object | undefined;
+//# sourceMappingURL=SchemaUtils.d.ts.map

package/dist/core/schema/SchemaUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SchemaUtils.d.ts","sourceRoot":"","sources":["../../../src/core/schema/SchemaUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAmB,MAAM,KAAK,CAAC;AACxE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAAC,WAAW,CAAC,CAO3E;AAID;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,MAAM,EAAE,CAU5F;AAsCD,wBAAgB,wBAAwB,CACpC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CAwCpB"}

package/dist/core/schema/SchemaUtils.js

@@ -0,0 +1,85 @@
+/**
+ * SchemaUtils — Shared Schema Inspection & Validation Utilities
+ *
+ * Extracted helpers for inspecting Zod schema metadata and
+ * asserting JSON Schema field compatibility across actions.
+ *
+ * Used by: SchemaGenerator, DescriptionGenerator, ToonDescriptionGenerator.
+ *
+ * Pure-function module: no state, no side effects.
+ */
+import {} from 'zod';
+import {} from '../types.js';
+// ── Zod Type Guards ──────────────────────────────────────
+/**
+ * Check if a value is a Zod schema (has `_def` property).
+ *
+ * Used by `defineTool` and `definePrompt` to distinguish
+ * Zod schemas from JSON descriptor objects.
+ */
+export function isZodSchema(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '_def' in value &&
+        typeof value._def === 'object');
+}
+// ── Schema Inspection ────────────────────────────────────
+/**
+ * Get the list of required field names from an action's Zod schema.
+ * Returns an empty array if the action has no schema.
+ */
+export function getActionRequiredFields(action) {
+    if (!action.schema)
+        return [];
+    const shape = action.schema.shape;
+    const required = [];
+    for (const [key, fieldSchema] of Object.entries(shape)) {
+        if (!fieldSchema.isOptional()) {
+            required.push(key);
+        }
+    }
+    return required;
+}
+// ── Schema Compatibility ─────────────────────────────────
+/**
+ * Normalize JSON Schema type for compatibility comparison.
+ * "integer" is treated as compatible with "number" (integer IS-A number).
+ */
+const normalizeType = (t) => t === 'integer' ? 'number' : t;
+/** Build a consistently-formatted conflict error. */
+function conflictError(field, actionKey, detail) {
+    return new Error(`Schema conflict for field "${field}" in action "${actionKey}": ` +
+        `${detail}. All actions sharing a field name must use the same type.`);
+}
+export function assertFieldCompatibility(existing, incoming, field, actionKey) {
+    const ex = existing;
+    const inc = incoming;
+    const exType = ex.type;
+    const incType = inc.type;
+    const exEnum = ex.enum;
+    const incEnum = inc.enum;
+    // 1. Base type mismatch (with integer ≈ number normalization)
+    if (exType !== undefined && incType !== undefined &&
+        normalizeType(exType) !== normalizeType(incType)) {
+        throw conflictError(field, actionKey, `type "${incType}" conflicts with previously declared type "${exType}"`);
+    }
+    // 2. Enum presence mismatch → WIDEN to non-enum (drop constraint)
+    //    Plain string is a superset of enum-constrained string.
+    //    Essential for OpenAPI imports where the same field name has enum
+    //    in one endpoint and plain string in another.
+    const exHasEnum = exEnum !== undefined;
+    const incHasEnum = incEnum !== undefined;
+    if (exHasEnum !== incHasEnum) {
+        // Return the non-enum version (superset)
+        const nonEnum = exHasEnum ? inc : ex;
+        return { ...nonEnum };
+    }
+    // 3. Enum value-set mismatch → MERGE (union) instead of throwing
+    if (exHasEnum && incHasEnum &&
+        JSON.stringify(exEnum) !== JSON.stringify(incEnum)) {
+        const merged = new Set([...exEnum, ...incEnum]);
+        return { ...ex, enum: [...merged] };
+    }
+    return undefined;
+}
+//# sourceMappingURL=SchemaUtils.js.map

package/dist/core/schema/SchemaUtils.js.map

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

package/dist/core/schema/ToonDescriptionGenerator.d.ts

@@ -0,0 +1,3 @@
+import { type InternalAction } from '../types.js';
+export declare function generateToonDescription<TContext>(actions: readonly InternalAction<TContext>[], name: string, description: string | undefined, hasGroup: boolean, discriminator?: string): string;
+//# sourceMappingURL=ToonDescriptionGenerator.d.ts.map

package/dist/core/schema/ToonDescriptionGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToonDescriptionGenerator.d.ts","sourceRoot":"","sources":["../../../src/core/schema/ToonDescriptionGenerator.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAKlD,wBAAgB,uBAAuB,CAAC,QAAQ,EAC5C,OAAO,EAAE,SAAS,cAAc,CAAC,QAAQ,CAAC,EAAE,EAC5C,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,QAAQ,EAAE,OAAO,EACjB,aAAa,SAAW,GACzB,MAAM,CAeR"}

package/dist/core/schema/ToonDescriptionGenerator.js

@@ -0,0 +1,65 @@
+/**
+ * ToonDescriptionGenerator — Token-Optimized Description Strategy
+ *
+ * Generates descriptions using TOON (Token-Oriented Object Notation) format,
+ * achieving ~30-50% token reduction compared to the default markdown descriptions.
+ *
+ * Uses `@toon-format/toon` encode() to serialize action metadata as compact
+ * pipe-delimited tabular data inside the description string.
+ *
+ * Pure-function module: no state, no side effects.
+ */
+import { encode } from '@toon-format/toon';
+import {} from '../types.js';
+import { getActionRequiredFields } from './SchemaUtils.js';
+// ── Public API ───────────────────────────────────────────
+export function generateToonDescription(actions, name, description, hasGroup, discriminator = 'action') {
+    const lines = [];
+    // Layer 1: Tool summary + dispatch instruction (always human-readable)
+    lines.push(`${description || name}. Select operation via the \`${discriminator}\` parameter.`);
+    lines.push('');
+    // Layer 2: Action metadata in TOON tabular format
+    if (hasGroup) {
+        lines.push(encodeGroupedActions(actions));
+    }
+    else {
+        lines.push(encodeFlatActions(actions));
+    }
+    return lines.join('\n');
+}
+function encodeFlatActions(actions) {
+    const rows = actions.map(a => buildActionRow(a.key, a));
+    return encode(rows, { delimiter: '|' });
+}
+function encodeGroupedActions(actions) {
+    // Group actions by their groupName
+    const groups = new Map();
+    for (const action of actions) {
+        const key = action.groupName || '_ungrouped';
+        let list = groups.get(key);
+        if (!list) {
+            list = [];
+            groups.set(key, list);
+        }
+        list.push(action);
+    }
+    // Build a structure that TOON can encode efficiently
+    const groupData = {};
+    for (const [groupName, groupActions] of groups) {
+        groupData[groupName] = groupActions.map(a => buildActionRow(a.actionName, a));
+    }
+    return encode(groupData, { delimiter: '|' });
+}
+function buildActionRow(key, action) {
+    const required = getActionRequiredFields(action);
+    const row = {
+        action: key,
+        desc: action.description || '',
+        required: required.join(','),
+    };
+    if (action.destructive) {
+        row.destructive = true;
+    }
+    return row;
+}
+//# sourceMappingURL=ToonDescriptionGenerator.js.map

package/dist/core/schema/ToonDescriptionGenerator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToonDescriptionGenerator.js","sourceRoot":"","sources":["../../../src/core/schema/ToonDescriptionGenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAuB,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,4DAA4D;AAE5D,MAAM,UAAU,uBAAuB,CACnC,OAA4C,EAC5C,IAAY,EACZ,WAA+B,EAC/B,QAAiB,EACjB,aAAa,GAAG,QAAQ;IAExB,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,uEAAuE;IACvE,KAAK,CAAC,IAAI,CAAC,GAAG,WAAW,IAAI,IAAI,gCAAgC,aAAa,eAAe,CAAC,CAAC;IAC/F,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,kDAAkD;IAClD,IAAI,QAAQ,EAAE,CAAC;QACX,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9C,CAAC;SAAM,CAAC;QACJ,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAWD,SAAS,iBAAiB,CACtB,OAA4C;IAE5C,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IACxD,OAAO,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;AAC5C,CAAC;AAED,SAAS,oBAAoB,CACzB,OAA4C;IAE5C,mCAAmC;IACnC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAsC,CAAC;IAC7D,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,IAAI,YAAY,CAAC;QAC7C,IAAI,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI,EAAE,CAAC;YACR,IAAI,GAAG,EAAE,CAAC;YACV,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC1B,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACtB,CAAC;IAED,qDAAqD;IACrD,MAAM,SAAS,GAAgC,EAAE,CAAC;IAClD,KAAK,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,IAAI,MAAM,EAAE,CAAC;QAC7C,SAAS,CAAC,SAAS,CAAC,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CACxC,cAAc,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAClC,CAAC;IACN,CAAC;IAED,OAAO,MAAM,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,cAAc,CACnB,GAAW,EACX,MAAgC;IAEhC,MAAM,QAAQ,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC;IACjD,MAAM,GAAG,GAAc;QACnB,MAAM,EAAE,GAAG;QACX,IAAI,EAAE,MAAM,CAAC,WAAW,IAAI,EAAE;QAC9B,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC;KAC/B,CAAC;IAEF,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;QACrB,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC;IAC3B,CAAC;IAED,OAAO,GAAG,CAAC;AACf,CAAC"}

package/dist/core/schema/index.d.ts

@@ -0,0 +1,7 @@
+/** Schema Bounded Context — Barrel Export */
+export { generateDescription } from './DescriptionGenerator.js';
+export { generateToonDescription } from './ToonDescriptionGenerator.js';
+export { generateInputSchema } from './SchemaGenerator.js';
+export { getActionRequiredFields, assertFieldCompatibility, isZodSchema } from './SchemaUtils.js';
+export { aggregateAnnotations } from './AnnotationAggregator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/schema/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/schema/index.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAClG,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/core/schema/index.js

@@ -0,0 +1,7 @@
+/** Schema Bounded Context — Barrel Export */
+export { generateDescription } from './DescriptionGenerator.js';
+export { generateToonDescription } from './ToonDescriptionGenerator.js';
+export { generateInputSchema } from './SchemaGenerator.js';
+export { getActionRequiredFields, assertFieldCompatibility, isZodSchema } from './SchemaUtils.js';
+export { aggregateAnnotations } from './AnnotationAggregator.js';
+//# sourceMappingURL=index.js.map

package/dist/core/schema/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/schema/index.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAClG,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/core/serialization/JsonSerializer.d.ts

@@ -0,0 +1,71 @@
+/**
+ * A pre-compiled stringify function.
+ *
+ * Generated at boot or on first use from a Zod schema.
+ * Accepts any object and returns a JSON string (minified).
+ *
+ * @example
+ * ```typescript
+ * const stringify = serializer.compile(myZodSchema);
+ * const json = stringify({ id: 1, name: 'Alice' });
+ * // '{"id":1,"name":"Alice"}'
+ * ```
+ */
+export type StringifyFn = (doc: unknown) => string;
+/**
+ * AOT JSON serialization engine.
+ *
+ * Compiles Zod schemas into fast stringify functions at boot time
+ * or lazily on first use. Maintains a per-schema cache to avoid
+ * recompilation.
+ */
+export interface JsonSerializer {
+    /**
+     * Compile a Zod schema into a fast stringify function.
+     *
+     * Returns `undefined` if `fast-json-stringify` is not available
+     * or if compilation fails (defensive fallback).
+     *
+     * @param schema - Any Zod schema (ZodObject, ZodArray, etc.)
+     * @returns A compiled stringify function, or `undefined`
+     */
+    compile(schema: unknown): StringifyFn | undefined;
+    /**
+     * Stringify data using a compiled function or native fallback.
+     *
+     * @param data - The data to serialize
+     * @param compiled - Optional pre-compiled stringify function
+     * @returns JSON string
+     */
+    stringify(data: unknown, compiled?: StringifyFn): string;
+}
+/**
+ * Create an AOT JSON serializer.
+ *
+ * The serializer lazy-loads `fast-json-stringify` and provides
+ * compile/stringify methods with automatic fallback.
+ *
+ * @example
+ * ```typescript
+ * const serializer = createSerializer();
+ * await serializer.init(); // optional: pre-load the fjs module
+ *
+ * const stringify = serializer.compile(myZodSchema);
+ * if (stringify) {
+ *     const json = stringify(data); // 2-5x faster
+ * }
+ * ```
+ */
+export declare function createSerializer(): JsonSerializer & {
+    init(): Promise<void>;
+};
+/**
+ * Global singleton serializer.
+ *
+ * Shared across the engine so all Presenters and response helpers
+ * use the same cache and fjs module reference.
+ */
+export declare const defaultSerializer: JsonSerializer & {
+    init(): Promise<void>;
+};
+//# sourceMappingURL=JsonSerializer.d.ts.map

package/dist/core/serialization/JsonSerializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsonSerializer.d.ts","sourceRoot":"","sources":["../../../src/core/serialization/JsonSerializer.ts"],"names":[],"mappings":"AAmCA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC3B;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAAC;IAElD;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;CAC5D;AA4ID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,IAAI,cAAc,GAAG;IAAE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAsB7E;AAID;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;YAhCiC,OAAO,CAAC,IAAI,CAAC;CAgCzB,CAAC"}