@contractspec/lib.contracts 1.49.0 → 1.50.0

package/dist/ownership.d.ts

@@ -2,82 +2,207 @@ import { DocId } from "./docs/registry.js";
 import "./docs/index.js";
 
 //#region src/ownership.d.ts
+
+/**
+ * Lifecycle stability stages for specs.
+ *
+ * Specs progress through these stages as they mature:
+ * - `idea`: Initial concept, not implemented
+ * - `in_creation`: Currently being built
+ * - `experimental`: Working but may change significantly
+ * - `beta`: Feature-complete, seeking feedback
+ * - `stable`: Production-ready, breaking changes require major version bump
+ * - `deprecated`: Scheduled for removal, use alternatives
+ */
 declare const StabilityEnum: {
+  /** Initial concept, not yet implemented. */
   readonly Idea: "idea";
+  /** Currently being built, not ready for use. */
   readonly InCreation: "in_creation";
+  /** Working but unstable, may change significantly. */
   readonly Experimental: "experimental";
+  /** Feature-complete, seeking feedback before stabilization. */
   readonly Beta: "beta";
+  /** Production-ready, follows semantic versioning. */
   readonly Stable: "stable";
+  /** Scheduled for removal, use alternatives. */
   readonly Deprecated: "deprecated";
 };
+/** Stability level for a spec's lifecycle stage. */
 type Stability = (typeof StabilityEnum)[keyof typeof StabilityEnum];
+/**
+ * Curated owner identifiers for business/product ownership.
+ *
+ * Used for CODEOWNERS, on-call routing, and approval workflows.
+ * Custom owner strings are also allowed for flexibility.
+ */
 declare const OwnersEnum: {
+  /** Core platform team. */
   readonly PlatformCore: "platform.core";
+  /** Sigil/auth team. */
   readonly PlatformSigil: "platform.sigil";
+  /** Marketplace team. */
   readonly PlatformMarketplace: "platform.marketplace";
+  /** Messaging/notifications team. */
   readonly PlatformMessaging: "platform.messaging";
+  /** Content/CMS team. */
   readonly PlatformContent: "platform.content";
+  /** Feature flags team. */
   readonly PlatformFeatureFlags: "platform.featureflags";
+  /** Finance/billing team. */
   readonly PlatformFinance: "platform.finance";
 };
+/**
+ * Owner identifier for a spec.
+ * Can be a predefined OwnersEnum value or any custom string.
+ */
 type Owner = (typeof OwnersEnum)[keyof typeof OwnersEnum] | (string & {});
+/** @deprecated Use OwnersEnum instead. */
 declare const Owners: {
+  /** Core platform team. */
   readonly PlatformCore: "platform.core";
+  /** Sigil/auth team. */
   readonly PlatformSigil: "platform.sigil";
+  /** Marketplace team. */
   readonly PlatformMarketplace: "platform.marketplace";
+  /** Messaging/notifications team. */
   readonly PlatformMessaging: "platform.messaging";
+  /** Content/CMS team. */
   readonly PlatformContent: "platform.content";
+  /** Feature flags team. */
   readonly PlatformFeatureFlags: "platform.featureflags";
+  /** Finance/billing team. */
   readonly PlatformFinance: "platform.finance";
 };
+/**
+ * Common tags for categorizing specs.
+ *
+ * Used for search, grouping, and documentation navigation.
+ * Custom tag strings are also allowed for flexibility.
+ */
 declare const TagsEnum: {
+  /** Spots/locations domain. */
   readonly Spots: "spots";
+  /** Collectivity/community domain. */
   readonly Collectivity: "collectivity";
+  /** Marketplace domain. */
   readonly Marketplace: "marketplace";
+  /** Seller-related features. */
   readonly Sellers: "sellers";
+  /** Authentication features. */
   readonly Auth: "auth";
+  /** Login flows. */
   readonly Login: "login";
+  /** Signup flows. */
   readonly Signup: "signup";
+  /** Onboarding/guides. */
   readonly Guide: "guide";
+  /** Documentation. */
   readonly Docs: "docs";
+  /** Internationalization. */
   readonly I18n: "i18n";
+  /** Incident management. */
   readonly Incident: "incident";
+  /** Automation/workflows. */
   readonly Automation: "automation";
+  /** Code hygiene/maintenance. */
   readonly Hygiene: "hygiene";
 };
+/**
+ * Tag for categorizing a spec.
+ * Can be a predefined TagsEnum value or any custom string.
+ */
 type Tag = (typeof TagsEnum)[keyof typeof TagsEnum] | (string & {});
+/** @deprecated Use TagsEnum instead. */
 declare const Tags: {
+  /** Spots/locations domain. */
   readonly Spots: "spots";
+  /** Collectivity/community domain. */
   readonly Collectivity: "collectivity";
+  /** Marketplace domain. */
   readonly Marketplace: "marketplace";
+  /** Seller-related features. */
   readonly Sellers: "sellers";
+  /** Authentication features. */
   readonly Auth: "auth";
+  /** Login flows. */
   readonly Login: "login";
+  /** Signup flows. */
   readonly Signup: "signup";
+  /** Onboarding/guides. */
   readonly Guide: "guide";
+  /** Documentation. */
   readonly Docs: "docs";
+  /** Internationalization. */
   readonly I18n: "i18n";
+  /** Incident management. */
   readonly Incident: "incident";
+  /** Automation/workflows. */
   readonly Automation: "automation";
+  /** Code hygiene/maintenance. */
   readonly Hygiene: "hygiene";
 };
+/**
+ * Common metadata interface for all ContractSpec specifications.
+ *
+ * Every spec type (operations, events, presentations, etc.) extends this
+ * interface to provide consistent ownership, versioning, and discoverability.
+ *
+ * @example
+ * ```typescript
+ * const meta: OwnerShipMeta = {
+ *   key: 'auth.login',
+ *   version: '1.0.0',
+ *   description: 'Authenticates a user with email and password',
+ *   stability: StabilityEnum.Stable,
+ *   owners: [OwnersEnum.PlatformSigil],
+ *   tags: [TagsEnum.Auth, TagsEnum.Login],
+ * };
+ * ```
+ */
 interface OwnerShipMeta {
-  /** Breaking changes => bump version */
+  /**
+   * Semantic version string (e.g., "1.0.0").
+   * Bump for breaking changes according to semver rules.
+   */
   version: string;
-  /** Fully-qualified spec key (e.g., "sigil.beginSignup") */
+  /**
+   * Fully-qualified spec key (e.g., "sigil.beginSignup", "user.created").
+   * Must be unique within the spec type.
+   */
   key: string;
-  /** Human-friendly spec title (e.g., "Signup begin") */
+  /**
+   * Human-friendly title (e.g., "Begin Signup").
+   * Used in documentation and UI.
+   */
   title?: string;
-  /** Short human-friendly summary */
+  /**
+   * Short human-friendly summary of what this spec does.
+   * Should be concise (1-2 sentences).
+   */
   description: string;
+  /**
+   * Business domain this spec belongs to (e.g., "auth", "marketplace").
+   * Used for grouping and discovery.
+   */
   domain?: string;
-  /** Lifecycle marker for comms & tooling */
+  /**
+   * Lifecycle stability marker.
+   * Indicates maturity level and change expectations.
+   */
   stability: Stability;
-  /** Owners for CODEOWNERS / on-call / approvals */
+  /**
+   * Team/individual owners responsible for this spec.
+   * Used for CODEOWNERS, on-call routing, and approvals.
+   */
   owners: Owner[];
-  /** Search tags, grouping, docs navigation */
+  /**
+   * Tags for search, grouping, and documentation navigation.
+   */
   tags: Tag[];
-  /** Doc block(s) for this operation. */
+  /**
+   * Associated DocBlock identifiers for documentation linkage.
+   */
   docId?: DocId[];
 }
 //#endregion

package/dist/ownership.js

@@ -1,4 +1,15 @@
 //#region src/ownership.ts
+/**
+* Lifecycle stability stages for specs.
+*
+* Specs progress through these stages as they mature:
+* - `idea`: Initial concept, not implemented
+* - `in_creation`: Currently being built
+* - `experimental`: Working but may change significantly
+* - `beta`: Feature-complete, seeking feedback
+* - `stable`: Production-ready, breaking changes require major version bump
+* - `deprecated`: Scheduled for removal, use alternatives
+*/
 const StabilityEnum = {
 	Idea: "idea",
 	InCreation: "in_creation",
@@ -7,6 +18,12 @@ const StabilityEnum = {
 	Stable: "stable",
 	Deprecated: "deprecated"
 };
+/**
+* Curated owner identifiers for business/product ownership.
+*
+* Used for CODEOWNERS, on-call routing, and approval workflows.
+* Custom owner strings are also allowed for flexibility.
+*/
 const OwnersEnum = {
 	PlatformCore: "platform.core",
 	PlatformSigil: "platform.sigil",
@@ -16,7 +33,14 @@ const OwnersEnum = {
 	PlatformFeatureFlags: "platform.featureflags",
 	PlatformFinance: "platform.finance"
 };
+/** @deprecated Use OwnersEnum instead. */
 const Owners = OwnersEnum;
+/**
+* Common tags for categorizing specs.
+*
+* Used for search, grouping, and documentation navigation.
+* Custom tag strings are also allowed for flexibility.
+*/
 const TagsEnum = {
 	Spots: "spots",
 	Collectivity: "collectivity",
@@ -32,6 +56,7 @@ const TagsEnum = {
 	Automation: "automation",
 	Hygiene: "hygiene"
 };
+/** @deprecated Use TagsEnum instead. */
 const Tags = TagsEnum;
 
 //#endregion

package/dist/policy/spec.d.ts

@@ -1,6 +1,8 @@
 import { OwnerShipMeta } from "../ownership.js";
+import { VersionedSpecRef } from "../versioning/refs.js";
 
 //#region src/policy/spec.d.ts
+/** Effect of a policy rule: allow or deny access. */
 type PolicyEffect = 'allow' | 'deny';
 interface RelationshipDefinition {
   subjectType: string;
@@ -95,9 +97,10 @@ interface PolicySpec {
   rateLimits?: RateLimitDefinition[];
   opa?: PolicyOPAConfig;
 }
-interface PolicyRef {
-  key: string;
-  version: string;
-}
+/**
+ * Reference to a policy spec.
+ * Uses key and version to identify a specific policy.
+ */
+type PolicyRef = VersionedSpecRef;
 //#endregion
 export { AttributeMatcher, ConsentDefinition, FieldPolicyRule, PIIPolicy, PolicyCondition, PolicyEffect, PolicyMeta, PolicyOPAConfig, PolicyRef, PolicyRule, PolicySpec, RateLimitDefinition, RelationshipDefinition, RelationshipMatcher, ResourceMatcher, SubjectMatcher };

package/dist/tests/spec.d.ts

@@ -1,14 +1,18 @@
 import { OwnerShipMeta } from "../ownership.js";
+import { OptionalVersionedSpecRef } from "../versioning/refs.js";
 
 //#region src/tests/spec.d.ts
-interface OperationTargetRef {
-  key: string;
-  version?: string;
-}
-interface WorkflowTargetRef {
-  key: string;
-  version?: string;
-}
+
+/**
+ * Reference to an operation to be tested.
+ * Version is optional; when omitted, refers to the latest version.
+ */
+type OperationTargetRef = OptionalVersionedSpecRef;
+/**
+ * Reference to a workflow to be tested.
+ * Version is optional; when omitted, refers to the latest version.
+ */
+type WorkflowTargetRef = OptionalVersionedSpecRef;
 type TestTarget = {
   type: 'operation';
   operation: OperationTargetRef;
@@ -66,10 +70,11 @@ interface TestSpec {
   scenarios: TestScenario[];
   coverage?: CoverageRequirement;
 }
-interface TestSpecRef {
-  key: string;
-  version?: string;
-}
+/**
+ * Reference to a test spec.
+ * Version is optional; when omitted, refers to the latest version.
+ */
+type TestSpecRef = OptionalVersionedSpecRef;
 declare class TestRegistry {
   private readonly items;
   register(spec: TestSpec): this;

package/dist/themes.d.ts

@@ -1,7 +1,9 @@
 import { OwnerShipMeta } from "./ownership.js";
+import { VersionedSpecRef } from "./versioning/refs.js";
 import { SpecContractRegistry } from "./registry.js";
 
 //#region src/themes.d.ts
+/** Scope at which a theme can be applied. */
 type ThemeScope = 'global' | 'tenant' | 'user';
 interface ThemeToken<T> {
   value: T;
@@ -39,10 +41,11 @@ interface ThemeSpec {
   components?: ComponentVariantSpec[];
   overrides?: ThemeOverride[];
 }
-interface ThemeRef {
-  key: string;
-  version: string;
-}
+/**
+ * Reference to a theme spec.
+ * Uses key and version to identify a specific theme.
+ */
+type ThemeRef = VersionedSpecRef;
 declare class ThemeRegistry extends SpecContractRegistry<'theme', ThemeSpec> {
   constructor(items?: ThemeSpec[]);
 }

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 };