@contractspec/lib.contracts 1.48.1 → 1.50.0

package/dist/types.d.ts

@@ -9,83 +9,209 @@ import { SpecVariantResolver } from "./experiments/spec-resolver.js";
 import { EventRegistry } from "./events.js";
 
 //#region src/types.d.ts
+
+/**
+ * Common runtime types for ContractSpec execution.
+ *
+ * Provides types for execution context, policy decisions, event emission,
+ * and handler context passed through the contracts runtime.
+ *
+ * @module types
+ */
 /**
- * Common runtime types: execution context, policy decision & event emission.
+ * Actor type representing the entity making a request.
+ *
+ * - `anonymous`: Unauthenticated request
+ * - `user`: Authenticated end-user
+ * - `admin`: Administrative/system user with elevated privileges
  */
 type Actor = 'anonymous' | 'user' | 'admin';
+/**
+ * Channel through which a request originates.
+ *
+ * - `web`: Browser/web application
+ * - `mobile`: Native mobile application
+ * - `job`: Background job/scheduled task
+ * - `agent`: AI agent or automated system
+ */
 type Channel = 'web' | 'mobile' | 'job' | 'agent';
+/**
+ * Discriminator for all ContractSpec specification types.
+ *
+ * Used to identify the kind of spec in registries and runtime operations.
+ */
 type ContractSpecType = 'app-config' | 'agent' | 'operation' | 'example' | 'event' | 'presentation' | 'capability' | 'integration' | 'data-view' | 'feature' | 'workflow' | 'policy' | 'theme' | 'telemetry' | 'experiment' | 'knowledge-space';
+/**
+ * Decision for a specific field access.
+ * Used for fine-grained field-level authorization.
+ */
 interface FieldLevelDecision {
+  /** The field path being evaluated. */
   field: string;
+  /** Whether access is allowed or denied. */
   effect: 'allow' | 'deny';
+  /** Human-readable reason for the decision. */
   reason?: string;
 }
+/**
+ * Result of a policy evaluation.
+ *
+ * Contains the access decision and any applicable constraints
+ * like rate limits, escalation requirements, or consent needs.
+ */
 interface PolicyDecision {
+  /** Overall access decision: allow or deny. */
   effect: 'allow' | 'deny';
+  /** Human-readable reason for the decision. */
   reason?: string;
+  /** Rate limit constraints to apply if allowed. */
   rateLimit?: Pick<RateLimitDefinition, 'rpm' | 'key' | 'windowSeconds' | 'burst'>;
+  /** Escalation requirement for manual review. */
   escalate?: 'human_review' | null;
+  /** Per-field access decisions. */
   fieldDecisions?: FieldLevelDecision[];
+  /** PII handling policy. */
   pii?: PolicySpec['pii'];
+  /** Consents required before proceeding. */
   requiredConsents?: ConsentDefinition[];
+  /** Which engine produced this decision. */
   evaluatedBy?: 'engine' | 'opa';
 }
+/**
+ * Input for policy evaluation.
+ * Contains context about the request being authorized.
+ */
 interface PolicyDeciderInput {
+  /** Service name (e.g., "sigil"). */
   service: string;
+  /** Command/operation name (e.g., "beginSignup"). */
   command: string;
+  /** Operation version. */
   version: string;
+  /** Actor type making the request. */
   actor: Actor;
+  /** Channel the request came from. */
   channel?: Channel;
+  /** Roles assigned to the actor. */
   roles?: string[];
+  /** Organization context if applicable. */
   organizationId?: string | null;
+  /** User context if authenticated. */
   userId?: string | null;
+  /** Active feature flags. */
   flags?: string[];
 }
+/**
+ * Function that evaluates policy rules and returns a decision.
+ */
 type PolicyDecider = (input: PolicyDeciderInput) => Promise<PolicyDecision>;
+/**
+ * Function that enforces rate limits.
+ *
+ * @param key - The rate limit key (e.g., user ID, IP)
+ * @param cost - Cost of this request (usually 1)
+ * @param rpm - Requests per minute limit
+ * @throws When rate limit is exceeded
+ */
 type RateLimiter = (key: string, cost: number, rpm: number) => Promise<void>;
+/**
+ * Function that resolves translation keys to localized strings.
+ */
 type TranslationResolver = (key: MessageKey, locale?: Locale) => Promise<string | null> | string | null;
-/** Outbox/bus event publisher (after validation & guarding) */
+/**
+ * Function that publishes events to the outbox/message bus.
+ * Called after validation and guard checks pass.
+ */
 type EventPublisher = (envelope: {
+  /** Event key (e.g., "user.created"). */
   key: string;
+  /** Event version. */
   version: string;
+  /** Validated event payload. */
   payload: unknown;
+  /** Trace ID for correlation. */
   traceId?: string;
 }) => Promise<void>;
+/**
+ * Execution context passed to operation handlers.
+ *
+ * Contains all contextual information and service hooks needed
+ * during operation execution, including auth context, policy evaluation,
+ * telemetry, event publishing, and resolved configurations.
+ *
+ * @example
+ * ```typescript
+ * async function loginHandler(input: LoginInput, ctx: HandlerCtx) {
+ *   // Check policy
+ *   const decision = await ctx.decide?.({
+ *     service: 'auth',
+ *     command: 'login',
+ *     version: '1.0.0',
+ *     actor: ctx.actor ?? 'anonymous',
+ *   });
+ *
+ *   // Track telemetry
+ *   ctx.telemetry?.track('login_attempt', { userId: ctx.userId });
+ *
+ *   // Publish event
+ *   await ctx.eventPublisher?.({
+ *     key: 'user.loggedIn',
+ *     version: '1.0.0',
+ *     payload: { userId: input.email },
+ *     traceId: ctx.traceId,
+ *   });
+ * }
+ * ```
+ */
 interface HandlerCtx {
+  /** Distributed trace identifier for request correlation. */
   traceId?: string;
+  /** Idempotency key for deduplication. */
   idemKey?: string;
+  /** Organization context for multi-tenant operations. */
   organizationId?: string | null;
+  /** Authenticated user ID. */
   userId?: string | null;
+  /** Actor type making the request. */
   actor?: Actor;
+  /** Channel the request originated from. */
   channel?: Channel;
+  /** Roles assigned to the authenticated user. */
   roles?: string[];
-  /** Policy engine hook (policy.yaml) */
+  /** Policy engine for authorization decisions. */
   decide?: PolicyDecider;
-  /** Rate limiter (e.g., Redis) */
+  /** Rate limiter service (e.g., Redis-backed). */
   rateLimit?: RateLimiter;
-  /** Telemetry tracker */
+  /** Telemetry tracker for metrics and events. */
   telemetry?: TelemetryTracker;
-  /** Event publisher (outbox+bus) */
+  /** Event publisher for domain events (outbox/bus). */
   eventPublisher?: EventPublisher;
-  /** Secret provider for secure credentials */
+  /** Secret provider for secure credential access. */
   secretProvider?: SecretProvider;
-  /** Internal pipe: filled by executor to enforce declared events */
+  /**
+   * Internal emit guard for enforcing declared event emissions.
+   * Populated by the executor runtime.
+   * @internal
+   */
   __emitGuard__?: (key: string, version: string, payload: unknown) => Promise<void>;
-  /** Resolved application configuration for the current execution context */
+  /** Resolved application configuration for this execution. */
   appConfig?: ResolvedAppConfig;
-  /** Resolved integration connections available to this execution */
+  /** Resolved integration connections available to this execution. */
   integrations?: ResolvedIntegration[];
-  /** Resolved knowledge spaces available to this execution */
+  /** Resolved knowledge spaces available to this execution. */
   knowledge?: ResolvedKnowledge[];
-  /** Resolved branding context */
+  /** Resolved branding context (logos, colors, etc.). */
   branding?: ResolvedBranding;
-  /** Translation context */
+  /** Translation context with config and resolver. */
   translation?: {
+    /** Resolved translation configuration. */
     config: ResolvedTranslation;
+    /** Function to resolve translation keys. */
     resolve?: TranslationResolver;
   };
-  /** Optional spec variant resolver for experiments */
+  /** Spec variant resolver for A/B testing and experiments. */
   specVariantResolver?: SpecVariantResolver;
+  /** Event registry for runtime event spec lookup. */
   eventSpecResolver?: EventRegistry;
 }
 //#endregion

package/dist/versioning/index.d.ts

@@ -1,3 +1,4 @@
+import { OptionalVersionedSpecRef, SpecKeyRef, VersionedSpecRef, createKeyRef, createOptionalRef, createVersionedRef, formatVersionedRefKey, isOptionalVersionedSpecRef, isSpecKeyRef, isVersionedSpecRef, parseVersionedRefKey } from "./refs.js";
 import { ChangeEntry, ChangeType, ChangelogDocBlock, ChangelogEntry, ChangelogJsonExport, ChangelogResult, SemanticVersion, VersionAnalysis, VersionAnalysisResult, VersionBumpType, isChangeType, isChangelogDocBlock, isVersionBumpType } from "./types.js";
 import { bumpVersion, compareVersions, determineBumpType, formatVersion, getBumpTypePriority, getMaxBumpType, isValidVersion, isVersionEqual, isVersionGreater, isVersionLess, parseVersion, parseVersionStrict, validateVersion } from "./utils.js";
-export { ChangeEntry, ChangeType, ChangelogDocBlock, ChangelogEntry, ChangelogJsonExport, ChangelogResult, SemanticVersion, VersionAnalysis, VersionAnalysisResult, VersionBumpType, bumpVersion, compareVersions, determineBumpType, formatVersion, getBumpTypePriority, getMaxBumpType, isChangeType, isChangelogDocBlock, isValidVersion, isVersionBumpType, isVersionEqual, isVersionGreater, isVersionLess, parseVersion, parseVersionStrict, validateVersion };
+export { ChangeEntry, ChangeType, ChangelogDocBlock, ChangelogEntry, ChangelogJsonExport, ChangelogResult, OptionalVersionedSpecRef, SemanticVersion, SpecKeyRef, VersionAnalysis, VersionAnalysisResult, VersionBumpType, VersionedSpecRef, bumpVersion, compareVersions, createKeyRef, createOptionalRef, createVersionedRef, determineBumpType, formatVersion, formatVersionedRefKey, getBumpTypePriority, getMaxBumpType, isChangeType, isChangelogDocBlock, isOptionalVersionedSpecRef, isSpecKeyRef, isValidVersion, isVersionBumpType, isVersionEqual, isVersionGreater, isVersionLess, isVersionedSpecRef, parseVersion, parseVersionStrict, parseVersionedRefKey, validateVersion };

package/dist/versioning/index.js

@@ -1,4 +1,5 @@
+import { createKeyRef, createOptionalRef, createVersionedRef, formatVersionedRefKey, isOptionalVersionedSpecRef, isSpecKeyRef, isVersionedSpecRef, parseVersionedRefKey } from "./refs.js";
 import { isChangeType, isChangelogDocBlock, isVersionBumpType } from "./types.js";
 import { bumpVersion, compareVersions, determineBumpType, formatVersion, getBumpTypePriority, getMaxBumpType, isValidVersion, isVersionEqual, isVersionGreater, isVersionLess, parseVersion, parseVersionStrict, validateVersion } from "./utils.js";
 
-export { bumpVersion, compareVersions, determineBumpType, formatVersion, getBumpTypePriority, getMaxBumpType, isChangeType, isChangelogDocBlock, isValidVersion, isVersionBumpType, isVersionEqual, isVersionGreater, isVersionLess, parseVersion, parseVersionStrict, validateVersion };
+export { bumpVersion, compareVersions, createKeyRef, createOptionalRef, createVersionedRef, determineBumpType, formatVersion, formatVersionedRefKey, getBumpTypePriority, getMaxBumpType, isChangeType, isChangelogDocBlock, isOptionalVersionedSpecRef, isSpecKeyRef, isValidVersion, isVersionBumpType, isVersionEqual, isVersionGreater, isVersionLess, isVersionedSpecRef, parseVersion, parseVersionStrict, parseVersionedRefKey, validateVersion };

package/dist/versioning/refs.d.ts

@@ -0,0 +1,179 @@
+//#region src/versioning/refs.d.ts
+/**
+ * Base reference types for ContractSpec versioning.
+ *
+ * Provides canonical reference types for linking between specs.
+ * Domain-specific refs (OpRef, EventRef, etc.) should alias these
+ * base types for consistency and maintainability.
+ *
+ * @module versioning/refs
+ */
+/**
+ * Base reference type for versioned specs.
+ * Used to reference any spec by its key and version.
+ *
+ * @example
+ * ```typescript
+ * const opRef: VersionedSpecRef = { key: 'auth.login', version: '1.0.0' };
+ * ```
+ */
+interface VersionedSpecRef {
+  /** Unique key identifying the spec (e.g., "auth.login", "user.created"). */
+  key: string;
+  /** Semantic version of the spec (e.g., "1.0.0", "2.1.0"). */
+  version: string;
+}
+/**
+ * Base reference type for specs with optional version.
+ * When version is omitted, typically refers to the latest version.
+ *
+ * @example
+ * ```typescript
+ * // Reference to latest version
+ * const latestRef: OptionalVersionedSpecRef = { key: 'auth.login' };
+ *
+ * // Reference to specific version
+ * const specificRef: OptionalVersionedSpecRef = { key: 'auth.login', version: '1.0.0' };
+ * ```
+ */
+interface OptionalVersionedSpecRef {
+  /** Unique key identifying the spec. */
+  key: string;
+  /** Optional semantic version. When omitted, refers to the latest version. */
+  version?: string;
+}
+/**
+ * Base reference type for unversioned spec keys.
+ * Used when only the key is needed without version information.
+ *
+ * @example
+ * ```typescript
+ * const featureRef: SpecKeyRef = { key: 'premium-features' };
+ * ```
+ */
+interface SpecKeyRef {
+  /** Unique key identifying the spec. */
+  key: string;
+}
+/**
+ * Checks if a value is a valid VersionedSpecRef.
+ *
+ * @param ref - The value to check
+ * @returns True if the value has both key and version as strings
+ *
+ * @example
+ * ```typescript
+ * const ref = { key: 'auth.login', version: '1.0.0' };
+ * if (isVersionedSpecRef(ref)) {
+ *   console.log(`Spec: ${ref.key}@${ref.version}`);
+ * }
+ * ```
+ */
+declare function isVersionedSpecRef(ref: unknown): ref is VersionedSpecRef;
+/**
+ * Checks if a value is a valid OptionalVersionedSpecRef.
+ *
+ * @param ref - The value to check
+ * @returns True if the value has a key string and optional version string
+ *
+ * @example
+ * ```typescript
+ * const ref = { key: 'auth.login' };
+ * if (isOptionalVersionedSpecRef(ref)) {
+ *   console.log(`Spec: ${ref.key}${ref.version ? `@${ref.version}` : ''}`);
+ * }
+ * ```
+ */
+declare function isOptionalVersionedSpecRef(ref: unknown): ref is OptionalVersionedSpecRef;
+/**
+ * Checks if a value is a valid SpecKeyRef.
+ *
+ * @param ref - The value to check
+ * @returns True if the value has a key string
+ *
+ * @example
+ * ```typescript
+ * const ref = { key: 'premium-features' };
+ * if (isSpecKeyRef(ref)) {
+ *   console.log(`Feature: ${ref.key}`);
+ * }
+ * ```
+ */
+declare function isSpecKeyRef(ref: unknown): ref is SpecKeyRef;
+/**
+ * Creates a versioned spec reference.
+ *
+ * @param key - The spec key (e.g., "auth.login")
+ * @param version - The semantic version (e.g., "1.0.0")
+ * @returns A VersionedSpecRef object
+ * @throws {Error} If key or version is empty
+ *
+ * @example
+ * ```typescript
+ * const ref = createVersionedRef('auth.login', '1.0.0');
+ * // { key: 'auth.login', version: '1.0.0' }
+ * ```
+ */
+declare function createVersionedRef(key: string, version: string): VersionedSpecRef;
+/**
+ * Creates an optional versioned spec reference.
+ *
+ * @param key - The spec key (e.g., "auth.login")
+ * @param version - Optional semantic version
+ * @returns An OptionalVersionedSpecRef object
+ * @throws {Error} If key is empty
+ *
+ * @example
+ * ```typescript
+ * // Reference to latest version
+ * const latestRef = createOptionalRef('auth.login');
+ * // { key: 'auth.login' }
+ *
+ * // Reference to specific version
+ * const specificRef = createOptionalRef('auth.login', '1.0.0');
+ * // { key: 'auth.login', version: '1.0.0' }
+ * ```
+ */
+declare function createOptionalRef(key: string, version?: string): OptionalVersionedSpecRef;
+/**
+ * Creates a spec key reference.
+ *
+ * @param key - The spec key (e.g., "premium-features")
+ * @returns A SpecKeyRef object
+ * @throws {Error} If key is empty
+ *
+ * @example
+ * ```typescript
+ * const ref = createKeyRef('premium-features');
+ * // { key: 'premium-features' }
+ * ```
+ */
+declare function createKeyRef(key: string): SpecKeyRef;
+/**
+ * Formats a versioned ref as a string key.
+ *
+ * @param ref - The versioned spec reference
+ * @returns A string in the format "key.vversion"
+ *
+ * @example
+ * ```typescript
+ * const str = formatVersionedRefKey({ key: 'auth.login', version: '1.0.0' });
+ * // "auth.login.v1.0.0"
+ * ```
+ */
+declare function formatVersionedRefKey(ref: VersionedSpecRef): string;
+/**
+ * Parses a versioned ref string back into a ref object.
+ *
+ * @param refKey - A string in the format "key.vversion"
+ * @returns A VersionedSpecRef or undefined if parsing fails
+ *
+ * @example
+ * ```typescript
+ * const ref = parseVersionedRefKey('auth.login.v1.0.0');
+ * // { key: 'auth.login', version: '1.0.0' }
+ * ```
+ */
+declare function parseVersionedRefKey(refKey: string): VersionedSpecRef | undefined;
+//#endregion
+export { OptionalVersionedSpecRef, SpecKeyRef, VersionedSpecRef, createKeyRef, createOptionalRef, createVersionedRef, formatVersionedRefKey, isOptionalVersionedSpecRef, isSpecKeyRef, isVersionedSpecRef, parseVersionedRefKey };

package/dist/versioning/refs.js

@@ -0,0 +1,161 @@
+//#region src/versioning/refs.ts
+/**
+* Checks if a value is a valid VersionedSpecRef.
+*
+* @param ref - The value to check
+* @returns True if the value has both key and version as strings
+*
+* @example
+* ```typescript
+* const ref = { key: 'auth.login', version: '1.0.0' };
+* if (isVersionedSpecRef(ref)) {
+*   console.log(`Spec: ${ref.key}@${ref.version}`);
+* }
+* ```
+*/
+function isVersionedSpecRef(ref) {
+	return typeof ref === "object" && ref !== null && "key" in ref && typeof ref.key === "string" && ref.key.length > 0 && "version" in ref && typeof ref.version === "string" && ref.version.length > 0;
+}
+/**
+* Checks if a value is a valid OptionalVersionedSpecRef.
+*
+* @param ref - The value to check
+* @returns True if the value has a key string and optional version string
+*
+* @example
+* ```typescript
+* const ref = { key: 'auth.login' };
+* if (isOptionalVersionedSpecRef(ref)) {
+*   console.log(`Spec: ${ref.key}${ref.version ? `@${ref.version}` : ''}`);
+* }
+* ```
+*/
+function isOptionalVersionedSpecRef(ref) {
+	if (typeof ref !== "object" || ref === null) return false;
+	if (!("key" in ref)) return false;
+	if (typeof ref.key !== "string" || ref.key.length === 0) return false;
+	if ("version" in ref && ref.version != null) return typeof ref.version === "string";
+	return true;
+}
+/**
+* Checks if a value is a valid SpecKeyRef.
+*
+* @param ref - The value to check
+* @returns True if the value has a key string
+*
+* @example
+* ```typescript
+* const ref = { key: 'premium-features' };
+* if (isSpecKeyRef(ref)) {
+*   console.log(`Feature: ${ref.key}`);
+* }
+* ```
+*/
+function isSpecKeyRef(ref) {
+	return typeof ref === "object" && ref !== null && "key" in ref && typeof ref.key === "string" && ref.key.length > 0;
+}
+/**
+* Creates a versioned spec reference.
+*
+* @param key - The spec key (e.g., "auth.login")
+* @param version - The semantic version (e.g., "1.0.0")
+* @returns A VersionedSpecRef object
+* @throws {Error} If key or version is empty
+*
+* @example
+* ```typescript
+* const ref = createVersionedRef('auth.login', '1.0.0');
+* // { key: 'auth.login', version: '1.0.0' }
+* ```
+*/
+function createVersionedRef(key, version) {
+	if (!key || key.trim().length === 0) throw new Error("Spec key cannot be empty");
+	if (!version || version.trim().length === 0) throw new Error("Spec version cannot be empty");
+	return {
+		key: key.trim(),
+		version: version.trim()
+	};
+}
+/**
+* Creates an optional versioned spec reference.
+*
+* @param key - The spec key (e.g., "auth.login")
+* @param version - Optional semantic version
+* @returns An OptionalVersionedSpecRef object
+* @throws {Error} If key is empty
+*
+* @example
+* ```typescript
+* // Reference to latest version
+* const latestRef = createOptionalRef('auth.login');
+* // { key: 'auth.login' }
+*
+* // Reference to specific version
+* const specificRef = createOptionalRef('auth.login', '1.0.0');
+* // { key: 'auth.login', version: '1.0.0' }
+* ```
+*/
+function createOptionalRef(key, version) {
+	if (!key || key.trim().length === 0) throw new Error("Spec key cannot be empty");
+	const ref = { key: key.trim() };
+	if (version != null && version.trim().length > 0) ref.version = version.trim();
+	return ref;
+}
+/**
+* Creates a spec key reference.
+*
+* @param key - The spec key (e.g., "premium-features")
+* @returns A SpecKeyRef object
+* @throws {Error} If key is empty
+*
+* @example
+* ```typescript
+* const ref = createKeyRef('premium-features');
+* // { key: 'premium-features' }
+* ```
+*/
+function createKeyRef(key) {
+	if (!key || key.trim().length === 0) throw new Error("Spec key cannot be empty");
+	return { key: key.trim() };
+}
+/**
+* Formats a versioned ref as a string key.
+*
+* @param ref - The versioned spec reference
+* @returns A string in the format "key.vversion"
+*
+* @example
+* ```typescript
+* const str = formatVersionedRefKey({ key: 'auth.login', version: '1.0.0' });
+* // "auth.login.v1.0.0"
+* ```
+*/
+function formatVersionedRefKey(ref) {
+	return `${ref.key}.v${ref.version}`;
+}
+/**
+* Parses a versioned ref string back into a ref object.
+*
+* @param refKey - A string in the format "key.vversion"
+* @returns A VersionedSpecRef or undefined if parsing fails
+*
+* @example
+* ```typescript
+* const ref = parseVersionedRefKey('auth.login.v1.0.0');
+* // { key: 'auth.login', version: '1.0.0' }
+* ```
+*/
+function parseVersionedRefKey(refKey) {
+	const match = refKey.match(/^(.+)\.v(\d+\.\d+\.\d+(?:-.+)?)$/);
+	if (!match) return void 0;
+	const key = match[1];
+	const version = match[2];
+	if (!key || !version) return void 0;
+	return {
+		key,
+		version
+	};
+}
+
+//#endregion
+export { createKeyRef, createOptionalRef, createVersionedRef, formatVersionedRefKey, isOptionalVersionedSpecRef, isSpecKeyRef, isVersionedSpecRef, parseVersionedRefKey };

package/dist/workflow/index.d.ts

@@ -1,4 +1,5 @@
-import { CompensationStep, CompensationStrategy, FormRef, GuardCondition, GuardConditionKind, RetryPolicy, SLA, Step, StepAction, StepType, Transition, WorkflowDefinition, WorkflowMeta, WorkflowRegistry, WorkflowSpec, WorkflowStatus } from "./spec.js";
+import { FormRef } from "../features/types.js";
+import { CompensationStep, CompensationStrategy, GuardCondition, GuardConditionKind, RetryPolicy, SLA, Step, StepAction, StepType, Transition, WorkflowDefinition, WorkflowMeta, WorkflowRegistry, WorkflowSpec, WorkflowStatus } from "./spec.js";
 import { ValidateWorkflowSpecOptions, WorkflowValidationError, WorkflowValidationIssue, WorkflowValidationLevel, assertWorkflowSpecValid, validateWorkflowSpec } from "./validation.js";
 import { StateStore, StepExecution, WorkflowState, WorkflowStateFilters } from "./state.js";
 import { GuardContext, GuardEvaluator, OperationExecutor, OperationExecutorContext, WorkflowPreFlightError, WorkflowPreFlightIssue, WorkflowPreFlightIssueSeverity, WorkflowPreFlightIssueType, WorkflowPreFlightResult, WorkflowRunner, WorkflowRunnerConfig } from "./runner.js";

package/dist/workflow/spec.d.ts

@@ -2,18 +2,11 @@ import { OwnerShipMeta } from "../ownership.js";
 import { CapabilityRef } from "../capabilities/capabilities.js";
 import "../capabilities/index.js";
 import { ExperimentRef } from "../experiments/spec.js";
-import { OpRef } from "../features/types.js";
+import { FormRef, OpRef } from "../features/types.js";
 import "../features/index.js";
 import { SpecContractRegistry } from "../registry.js";
 
 //#region src/workflow/spec.d.ts
-/**
- * Reference to a form spec declared in {@link FormRegistry}.
- */
-interface FormRef {
-  key: string;
-  version: string;
-}
 type StepType = 'human' | 'automation' | 'decision';
 type WorkflowStatus = 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
 type GuardConditionKind = 'policy' | 'expression';
@@ -90,4 +83,4 @@ declare class WorkflowRegistry extends SpecContractRegistry<'workflow', Workflow
   constructor(items?: WorkflowSpec[]);
 }
 //#endregion
-export { CompensationStep, CompensationStrategy, FormRef, GuardCondition, GuardConditionKind, RetryPolicy, SLA, Step, StepAction, StepType, Transition, WorkflowDefinition, WorkflowMeta, WorkflowRegistry, WorkflowSpec, WorkflowStatus };
+export { CompensationStep, CompensationStrategy, type FormRef, GuardCondition, GuardConditionKind, RetryPolicy, SLA, Step, StepAction, StepType, Transition, WorkflowDefinition, WorkflowMeta, WorkflowRegistry, WorkflowSpec, WorkflowStatus };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/lib.contracts",
-  "version": "1.48.1",
+  "version": "1.50.0",
   "description": "Core contract specification definitions and runtime",
   "keywords": [
     "contractspec",
@@ -25,8 +25,8 @@
     "test": "bun test"
   },
   "devDependencies": {
-    "@contractspec/tool.tsdown": "1.48.0",
-    "@contractspec/tool.typescript": "1.48.0",
+    "@contractspec/tool.tsdown": "1.50.0",
+    "@contractspec/tool.typescript": "1.50.0",
     "@types/express": "^5.0.3",
     "@types/turndown": "^5.0.6",
     "tsdown": "^0.19.0",
@@ -35,8 +35,8 @@
   "dependencies": {
     "@aws-sdk/client-secrets-manager": "^3.966.0",
     "@aws-sdk/client-sqs": "^3.966.0",
-    "@contractspec/lib.logger": "1.48.0",
-    "@contractspec/lib.schema": "1.48.0",
+    "@contractspec/lib.logger": "1.50.0",
+    "@contractspec/lib.schema": "1.50.0",
     "@elevenlabs/elevenlabs-js": "^2.30.0",
     "@google-cloud/secret-manager": "^6.1.1",
     "@google-cloud/storage": "^7.18.0",
@@ -306,6 +306,9 @@
     "./registry-utils": "./dist/registry-utils.js",
     "./resources": "./dist/resources.js",
     "./schema-to-markdown": "./dist/schema-to-markdown.js",
+    "./serialization": "./dist/serialization/index.js",
+    "./serialization/serializers": "./dist/serialization/serializers.js",
+    "./serialization/types": "./dist/serialization/types.js",
     "./server": "./dist/server/index.js",
     "./server/contracts-adapter-hydration": "./dist/server/contracts-adapter-hydration.js",
     "./server/contracts-adapter-input": "./dist/server/contracts-adapter-input.js",
@@ -336,6 +339,7 @@
     "./translations/tenant": "./dist/translations/tenant.js",
     "./types": "./dist/types.js",
     "./versioning": "./dist/versioning/index.js",
+    "./versioning/refs": "./dist/versioning/refs.js",
     "./versioning/types": "./dist/versioning/types.js",
     "./versioning/utils": "./dist/versioning/utils.js",
     "./workflow": "./dist/workflow/index.js",