@vurb/core 3.2.0

package/dist/core/serialization/JsonSerializer.js

@@ -0,0 +1,192 @@
+/**
+ * JsonSerializer — AOT JSON Serialization Engine
+ *
+ * Compiles Zod schemas into hyper-fast stringify functions using
+ * `fast-json-stringify` (the Fastify serialization engine).
+ *
+ * Architecture:
+ *   ┌──────────────────────────────────────────────────┐
+ *   │  Boot / First Call (AOT / Lazy)                  │
+ *   │                                                  │
+ *   │  ZodType ──► zod-to-json-schema ──► JSON Schema  │
+ *   │                    │                             │
+ *   │                    ▼                             │
+ *   │            fast-json-stringify                   │
+ *   │                    │                             │
+ *   │                    ▼                             │
+ *   │         Compiled StringifyFn (C-like)            │
+ *   │         Cached via WeakMap<ZodType>              │
+ *   └──────────────────────────────────────────────────┘
+ *
+ * Properties:
+ * - 2-5x faster than `JSON.stringify` for known schemas
+ * - Lazy-by-default: compiles on first use, cached via WeakMap
+ * - Zero-risk fallback: if `fast-json-stringify` is missing or
+ *   compilation fails, falls back to native `JSON.stringify`
+ * - Produces compact/minified JSON (no indentation) for max throughput
+ * - Safe optional/nullable handling via schema transformation
+ *
+ * @module
+ * @internal
+ */
+import { zodToJsonSchema } from 'zod-to-json-schema';
+let _fjsBuild = null;
+async function loadFastJsonStringify() {
+    if (_fjsBuild === false)
+        return null; // already tried, not available
+    if (_fjsBuild !== null)
+        return _fjsBuild;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const mod = await import('fast-json-stringify');
+        _fjsBuild = (typeof mod === 'function' ? mod : mod.default);
+        return _fjsBuild;
+    }
+    catch {
+        _fjsBuild = false; // mark as unavailable
+        return null;
+    }
+}
+// Synchronous version — uses the cached function if already loaded.
+function getFjsBuild() {
+    if (_fjsBuild === false || _fjsBuild === null)
+        return null;
+    return _fjsBuild;
+}
+// ── Schema Cache ─────────────────────────────────────────
+// WeakMap ensures schemas are compiled exactly once and can be GC'd
+// when the schema reference is released.
+const _cache = new WeakMap();
+// ── JSON Schema Transformation ───────────────────────────
+/**
+ * Transform a JSON Schema for safe use with fast-json-stringify.
+ *
+ * - Strips `$schema` (not supported by fjs)
+ * - Adds `additionalProperties: true` to objects so unknown fields
+ *   are serialized instead of silently dropped
+ * - Wraps types with nullable variants where appropriate
+ *
+ * @internal
+ */
+function transformForFjs(jsonSchema) {
+    const schema = { ...jsonSchema };
+    // Remove $schema — fast-json-stringify doesn't support it
+    delete schema['$schema'];
+    // For object-type schemas, allow additional properties
+    // so dynamic/runtime fields are not silently dropped
+    if (schema['type'] === 'object') {
+        if (schema['additionalProperties'] === undefined) {
+            schema['additionalProperties'] = true;
+        }
+    }
+    // Recursively transform nested properties
+    if (schema['properties'] && typeof schema['properties'] === 'object') {
+        const props = { ...schema['properties'] };
+        for (const [key, value] of Object.entries(props)) {
+            if (value && typeof value === 'object') {
+                props[key] = transformForFjs(value);
+            }
+        }
+        schema['properties'] = props;
+    }
+    // Transform array items
+    if (schema['items'] && typeof schema['items'] === 'object') {
+        schema['items'] = transformForFjs(schema['items']);
+    }
+    // Handle anyOf / oneOf for nullable unions
+    for (const combiner of ['anyOf', 'oneOf', 'allOf']) {
+        if (Array.isArray(schema[combiner])) {
+            schema[combiner] = schema[combiner]
+                .map(s => (s && typeof s === 'object' ? transformForFjs(s) : s));
+        }
+    }
+    return schema;
+}
+// ── Compile Logic ────────────────────────────────────────
+/**
+ * Core compilation: Zod schema → JSON Schema → fast-json-stringify function.
+ *
+ * @internal
+ */
+function compileSchema(schema) {
+    const build = getFjsBuild();
+    if (!build)
+        return undefined;
+    // Check cache first (schema as WeakMap key)
+    if (typeof schema === 'object' && schema !== null && _cache.has(schema)) {
+        return _cache.get(schema);
+    }
+    try {
+        // Step 1: Zod → JSON Schema
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const rawJsonSchema = zodToJsonSchema(schema, {
+            target: 'jsonSchema7',
+            $refStrategy: 'none',
+        });
+        // Step 2: Transform for fjs compatibility
+        const fjsSchema = transformForFjs(rawJsonSchema);
+        // Step 3: Compile the stringify function
+        const stringify = build(fjsSchema, {
+            largeArrayMechanism: 'json-stringify',
+        });
+        // Cache the compiled function
+        if (typeof schema === 'object' && schema !== null) {
+            _cache.set(schema, stringify);
+        }
+        return stringify;
+    }
+    catch {
+        // Compilation failed — fall back to native JSON.stringify
+        // This is expected for very complex schemas that fjs can't handle
+        return undefined;
+    }
+}
+// ── Public Factory ───────────────────────────────────────
+/**
+ * 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 function createSerializer() {
+    return {
+        async init() {
+            await loadFastJsonStringify();
+        },
+        compile(schema) {
+            return compileSchema(schema);
+        },
+        stringify(data, compiled) {
+            if (compiled) {
+                try {
+                    return compiled(data);
+                }
+                catch {
+                    // Defensive: if compiled function fails at runtime
+                    // (e.g., data shape mismatch), fall back to native
+                }
+            }
+            return JSON.stringify(data);
+        },
+    };
+}
+// ── Singleton ────────────────────────────────────────────
+/**
+ * Global singleton serializer.
+ *
+ * Shared across the engine so all Presenters and response helpers
+ * use the same cache and fjs module reference.
+ */
+export const defaultSerializer = createSerializer();
+//# sourceMappingURL=JsonSerializer.js.map

package/dist/core/serialization/JsonSerializer.js.map

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

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

@@ -0,0 +1,7 @@
+/**
+ * Serialization Module — AOT JSON Serialization Engine
+ *
+ * @module
+ */
+export { type StringifyFn, type JsonSerializer, createSerializer, defaultSerializer, } from './JsonSerializer.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/serialization/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACH,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,gBAAgB,EAChB,iBAAiB,GACpB,MAAM,qBAAqB,CAAC"}

package/dist/core/serialization/index.js

@@ -0,0 +1,7 @@
+/**
+ * Serialization Module — AOT JSON Serialization Engine
+ *
+ * @module
+ */
+export { createSerializer, defaultSerializer, } from './JsonSerializer.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/serialization/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAGH,gBAAgB,EAChB,iBAAiB,GACpB,MAAM,qBAAqB,CAAC"}

package/dist/core/types.d.ts

@@ -0,0 +1,303 @@
+/**
+ * Framework Contracts & Shared Types
+ *
+ * Single-file type definitions following the consolidated contracts pattern.
+ * All interfaces, type aliases, and shared contracts live here.
+ *
+ * This module has ZERO runtime code — only type declarations.
+ * It may be imported by any module without circular dependency risk.
+ *
+ * @module
+ */
+import { type Tool as McpTool } from '@modelcontextprotocol/sdk/types.js';
+import { type ZodObject, type ZodRawShape } from 'zod';
+import { type Presenter } from '../presenter/Presenter.js';
+import { type ProgressSink } from './execution/ProgressHelper.js';
+export type { ToolResponse } from './response.js';
+import { type ToolResponse } from './response.js';
+/**
+ * Interface that all tool builders must implement.
+ *
+ * This is the abstraction that {@link ToolRegistry} depends on,
+ * following the Dependency Inversion Principle. You can create
+ * custom builders by implementing this interface.
+ *
+ * @typeParam TContext - Application context passed to every handler
+ *
+ * @example
+ * ```typescript
+ * // The built-in GroupedToolBuilder implements this interface:
+ * const builder: ToolBuilder<AppContext> = new GroupedToolBuilder<AppContext>('projects');
+ *
+ * // Register with the registry:
+ * const registry = new ToolRegistry<AppContext>();
+ * registry.register(builder);
+ * ```
+ *
+ * @see {@link GroupedToolBuilder} for the default implementation
+ * @see {@link ToolRegistry} for registration and routing
+ */
+export interface ToolBuilder<TContext = void> {
+    /** Get the tool name (used as the registration key) */
+    getName(): string;
+    /** Get the capability tags for selective exposure */
+    getTags(): string[];
+    /** Get all registered action keys */
+    getActionNames(): string[];
+    /** Get metadata for all registered actions */
+    getActionMetadata(): ActionMetadata[];
+    /** Build and return the MCP Tool definition. May cache internally. */
+    buildToolDefinition(): McpTool;
+    /** Execute a tool call with the given context and arguments */
+    execute(ctx: TContext, args: Record<string, unknown>, progressSink?: ProgressSink, signal?: AbortSignal): Promise<ToolResponse>;
+    /**
+     * Preview the exact MCP prompt payload that the LLM will receive.
+     *
+     * Returns a formatted string showing the compiled tool definition
+     * (name, description, input schema, annotations) with approximate
+     * token count. Auto-calls buildToolDefinition() if needed.
+     *
+     * Use this to optimize token usage and verify LLM-facing grammar
+     * without starting an MCP server.
+     */
+    previewPrompt(): string;
+    /** Get all registered internal actions. Used by Exposition Compiler for atomic tool expansion. */
+    getActions?(): readonly InternalAction<TContext>[];
+    /** Get the discriminator field name (e.g. `"action"`). */
+    getDiscriminator?(): string;
+    /** Get the common schema shared across all actions. */
+    getCommonSchema?(): ZodObject<ZodRawShape> | undefined;
+    /** Check if `_select` reflection is enabled for context window optimization. */
+    getSelectEnabled?(): boolean;
+    /** Get per-action state sync hints declared via fluent `.invalidates()` / `.cached()`. */
+    getStateSyncHints?(): ReadonlyMap<string, StateSyncHint>;
+}
+/**
+ * Per-action hint for automatic State Sync policy generation.
+ *
+ * Declared via fluent API (`.invalidates()`, `.cached()`) and
+ * collected by {@link ServerAttachment} to auto-generate
+ * `SyncPolicy[]` without manual configuration.
+ *
+ * @see {@link StateSyncConfig} for centralized configuration
+ */
+export interface StateSyncHint {
+    /** Cache directive for this action's description. */
+    readonly cacheControl?: 'no-store' | 'immutable';
+    /** Glob patterns of tools invalidated on successful execution. */
+    readonly invalidates?: readonly string[];
+}
+/**
+ * Metadata for a single action within a grouped tool.
+ *
+ * Returned by {@link ToolBuilder.getActionMetadata} for
+ * introspection, compliance audits, or dashboard generation.
+ *
+ * @example
+ * ```typescript
+ * const meta = builder.getActionMetadata();
+ * for (const action of meta) {
+ *     console.log(`${action.key}: destructive=${action.destructive}`);
+ * }
+ * // Output: "users.create: destructive=false"
+ * //         "users.delete: destructive=true"
+ * ```
+ *
+ * @see {@link GroupedToolBuilder.getActionMetadata}
+ */
+export interface ActionMetadata {
+    /** Full action key (e.g. `"admin.create"` for grouped, `"list"` for flat) */
+    readonly key: string;
+    /** Action name within its group */
+    readonly actionName: string;
+    /** Group name (`undefined` for flat actions) */
+    readonly groupName: string | undefined;
+    /** Human-readable description */
+    readonly description: string | undefined;
+    /** Whether this action is destructive */
+    readonly destructive: boolean;
+    /** Whether this action is idempotent */
+    readonly idempotent: boolean;
+    /** Whether this action is read-only */
+    readonly readOnly: boolean;
+    /** Required field names from the Zod schema */
+    readonly requiredFields: readonly string[];
+    /** Whether this action has group/action-level middleware */
+    readonly hasMiddleware: boolean;
+    /** Presenter name (if MVA pattern is used via `returns: Presenter`) */
+    readonly presenterName: string | undefined;
+    /** Schema keys exposed by the Presenter (Zod shape keys) */
+    readonly presenterSchemaKeys: readonly string[] | undefined;
+    /** UI block types supported by the Presenter (e.g. 'echarts', 'mermaid') */
+    readonly presenterUiBlockTypes: readonly string[] | undefined;
+    /** Whether the Presenter has dynamic (context-aware) system rules */
+    readonly presenterHasContextualRules: boolean | undefined;
+    /** Static rule strings for fingerprinting (empty if rules are contextual) */
+    readonly presenterStaticRules: readonly string[] | undefined;
+}
+/**
+ * Internal representation of a registered action.
+ *
+ * This is the internal data structure used by the build-time
+ * strategies. You typically don't interact with this directly.
+ *
+ * @internal
+ */
+export interface InternalAction<TContext> {
+    /** Full key: `"name"` (flat) or `"group.name"` (grouped) */
+    readonly key: string;
+    /** Group name (`undefined` for flat actions) */
+    readonly groupName: string | undefined;
+    /** Group description */
+    readonly groupDescription: string | undefined;
+    /** Action name within the group */
+    readonly actionName: string;
+    /** Description */
+    readonly description: string | undefined;
+    /** Zod schema */
+    readonly schema: ZodObject<ZodRawShape> | undefined;
+    /** Whether this action is destructive */
+    readonly destructive: boolean | undefined;
+    /** Whether this action is idempotent */
+    readonly idempotent: boolean | undefined;
+    /** Whether this action is read-only */
+    readonly readOnly: boolean | undefined;
+    /** Per-action/group middleware (applied after global middleware) */
+    readonly middlewares: readonly MiddlewareFn<TContext>[] | undefined;
+    /** Common schema fields to omit for this action (LLM won't see them, validation skips them) */
+    readonly omitCommonFields: readonly string[] | undefined;
+    /** Presenter for MVA pattern — transforms raw handler output into rich multi-block responses */
+    readonly returns: Presenter<unknown> | undefined;
+    /** Handler — returns ToolResponse (classic) or raw data (MVA with `returns: Presenter`) */
+    readonly handler: (ctx: TContext, args: Record<string, unknown>) => Promise<unknown>;
+}
+/**
+ * Middleware function signature.
+ *
+ * Follows the `next()` pattern (similar to Express/Koa). Middleware
+ * can inspect/modify args, short-circuit with an error, or wrap
+ * the handler with cross-cutting concerns.
+ *
+ * Middleware chains are **pre-compiled at build time** — there is
+ * zero chain assembly or closure allocation per request.
+ *
+ * @typeParam TContext - Application context
+ *
+ * @example
+ * ```typescript
+ * // Authentication middleware
+ * const requireAuth: MiddlewareFn<AppContext> = async (ctx, args, next) => {
+ *     if (!ctx.user) return error('Unauthorized');
+ *     return next();
+ * };
+ *
+ * // Logging middleware
+ * const logger: MiddlewareFn<AppContext> = async (ctx, args, next) => {
+ *     const start = Date.now();
+ *     const result = await next();
+ *     console.log(`${args.action} took ${Date.now() - start}ms`);
+ *     return result;
+ * };
+ *
+ * // Apply to a builder
+ * const builder = new GroupedToolBuilder<AppContext>('projects')
+ *     .use(logger)        // Global: runs on every action
+ *     .use(requireAuth);  // Global: runs after logger
+ * ```
+ *
+ * @see {@link GroupedToolBuilder.use} for global middleware
+ * @see {@link ActionGroupBuilder.use} for group-scoped middleware
+ */
+export type MiddlewareFn<TContext> = (ctx: TContext, args: Record<string, unknown>, next: () => Promise<unknown>) => Promise<unknown>;
+/**
+ * Configuration for a single action within a grouped tool.
+ *
+ * Pass this to {@link GroupedToolBuilder.action} or
+ * {@link ActionGroupBuilder.action} to register an action.
+ *
+ * @typeParam TContext - Application context
+ *
+ * @example
+ * ```typescript
+ * builder.action({
+ *     name: 'create',
+ *     description: 'Create a new project',
+ *     schema: z.object({
+ *         name: z.string().describe('Project name'),
+ *         description: z.string().optional(),
+ *     }),
+ *     destructive: false,
+ *     handler: async (ctx, args) => {
+ *         const project = await ctx.db.projects.create(args);
+ *         return success(project);
+ *     },
+ * });
+ * ```
+ *
+ * @see {@link GroupedToolBuilder.action}
+ */
+export interface ActionConfig<TContext> {
+    /** Action name (must not contain dots in flat mode) */
+    name: string;
+    /** Human-readable description of what this action does */
+    description?: string;
+    /** Zod schema for this action's specific parameters */
+    schema?: ZodObject<ZodRawShape>;
+    /**
+     * Whether this action is destructive.
+     * When `true`, appends `[DESTRUCTIVE]` to the LLM description.
+     */
+    destructive?: boolean;
+    /**
+     * Whether this action is idempotent.
+     * Affects the aggregated `idempotentHint` annotation.
+     */
+    idempotent?: boolean;
+    /**
+     * Whether this action is read-only.
+     * Affects the aggregated `readOnlyHint` annotation.
+     */
+    readOnly?: boolean;
+    /**
+     * Common schema fields to omit for this specific action.
+     *
+     * Use when an action derives a common field from context (e.g. middleware)
+     * instead of requiring the LLM to provide it.
+     *
+     * @example
+     * ```typescript
+     * // workspace_id is derived from the JWT token for profile.me
+     * .action({
+     *     name: 'me',
+     *     omitCommon: ['workspace_id'],
+     *     handler: async (ctx, args) => success(ctx.user),
+     * })
+     * ```
+     */
+    omitCommon?: string[];
+    /**
+     * Presenter for the MVA (Model-View-Agent) pattern.
+     *
+     * When set, the handler's return type changes from `Promise<ToolResponse>`
+     * to `Promise<TPresenterOutput>` (raw data). The framework intercepts the
+     * raw return value, pipes it through the Presenter (schema validation,
+     * system rules, UI blocks), and compiles the final multi-block response.
+     *
+     * @example
+     * ```typescript
+     * .action({
+     *     name: 'get_invoice',
+     *     returns: InvoicePresenter,
+     *     handler: async (ctx, args) => {
+     *         return await db.invoices.find(args.id); // Raw data
+     *     },
+     * })
+     * ```
+     *
+     * @see {@link Presenter} for creating domain-level presenters
+     */
+    returns?: Presenter<unknown>;
+    /** Handler function — return ToolResponse (classic) or raw data when using `returns: Presenter` */
+    handler: (ctx: TContext, args: Record<string, unknown>) => Promise<unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/core/types.js

@@ -0,0 +1,17 @@
+/**
+ * Framework Contracts & Shared Types
+ *
+ * Single-file type definitions following the consolidated contracts pattern.
+ * All interfaces, type aliases, and shared contracts live here.
+ *
+ * This module has ZERO runtime code — only type declarations.
+ * It may be imported by any module without circular dependency risk.
+ *
+ * @module
+ */
+import {} from '@modelcontextprotocol/sdk/types.js';
+import {} from 'zod';
+import {} from '../presenter/Presenter.js';
+import {} from './execution/ProgressHelper.js';
+import {} from './response.js';
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAwB,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAoC,MAAM,KAAK,CAAC;AACvD,OAAO,EAAkB,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAqB,MAAM,+BAA+B,CAAC;AAKlE,OAAO,EAAqB,MAAM,eAAe,CAAC"}

package/dist/domain/Annotations.d.ts

@@ -0,0 +1,42 @@
+import { type Role } from './Role.js';
+/**
+ * Resource Annotations — audience, priority, and freshness metadata.
+ *
+ * Used on {@link Resource} instances to provide hints about who
+ * should see the resource and how important it is.
+ *
+ * @example
+ * ```typescript
+ * import { createAnnotations, Role } from 'vurb';
+ *
+ * const annotations = createAnnotations({
+ *     audience: [Role.ASSISTANT],
+ *     priority: 0.8,
+ *     lastModified: '2025-01-15T10:30:00Z',
+ * });
+ * ```
+ *
+ * @see {@link Resource} for usage on resources
+ * @see {@link createAnnotations} for the factory function
+ */
+export interface Annotations {
+    /** Target audience roles for this resource */
+    readonly audience?: readonly Role[];
+    /** Priority weight (0.0 = lowest, 1.0 = highest) */
+    readonly priority?: number;
+    /** ISO 8601 timestamp of last modification */
+    readonly lastModified?: string;
+}
+/**
+ * Create Annotations from partial properties.
+ *
+ * @param props - Annotation properties (all optional)
+ * @returns An Annotations instance
+ *
+ * @example
+ * ```typescript
+ * const ann = createAnnotations({ priority: 0.5 });
+ * ```
+ */
+export declare function createAnnotations(props?: Annotations): Annotations;
+//# sourceMappingURL=Annotations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Annotations.d.ts","sourceRoot":"","sources":["../../src/domain/Annotations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,WAAW;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACpC,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,GAAE,WAAgB,GAAG,WAAW,CAEtE"}

package/dist/domain/Annotations.js

@@ -0,0 +1,16 @@
+import {} from './Role.js';
+/**
+ * Create Annotations from partial properties.
+ *
+ * @param props - Annotation properties (all optional)
+ * @returns An Annotations instance
+ *
+ * @example
+ * ```typescript
+ * const ann = createAnnotations({ priority: 0.5 });
+ * ```
+ */
+export function createAnnotations(props = {}) {
+    return { ...props };
+}
+//# sourceMappingURL=Annotations.js.map

package/dist/domain/Annotations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Annotations.js","sourceRoot":"","sources":["../../src/domain/Annotations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,MAAM,WAAW,CAAC;AA+BtC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAqB,EAAE;IACrD,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;AACxB,CAAC"}