@contractspec/lib.contracts 1.44.0

package/dist/operations/index.js

@@ -0,0 +1,4 @@
+import { defineCommand, defineQuery, isEmitDeclRef } from "./operation.js";
+import { OperationSpecRegistry, opKey } from "./registry.js";
+
+export { OperationSpecRegistry, defineCommand, defineQuery, isEmitDeclRef, opKey };

package/dist/operations/operation.d.ts

@@ -0,0 +1,186 @@
+import { OwnerShipMeta } from "../ownership.js";
+import { PolicyRef } from "../policy/spec.js";
+import { ResourceRefDescriptor } from "../resources.js";
+import { EventSpec } from "../events.js";
+import { TestSpecRef } from "../tests/spec.js";
+import { AnySchemaModel } from "@contractspec/lib.schema";
+
+//#region src/operations/operation.d.ts
+
+/**
+ * Distinguishes between state-changing operations (command) and read-only operations (query).
+ */
+type OpKind = 'command' | 'query';
+/**
+ * Type of implementation artifact.
+ */
+type ImplementationType = 'handler' | 'component' | 'form' | 'test' | 'service' | 'hook' | 'other';
+/**
+ * Reference to an implementation file for a spec.
+ * Used for explicit implementation mapping.
+ */
+interface ImplementationRef {
+  /** Path to implementation file (relative to workspace root) */
+  path: string;
+  /** Type of implementation artifact */
+  type: ImplementationType;
+  /** Optional human-readable description */
+  description?: string;
+}
+interface EmitDeclRef {
+  ref: EventSpec<AnySchemaModel>['meta'];
+  when: string;
+}
+interface EmitDeclInline {
+  key: string;
+  version: number;
+  when: string;
+  payload: AnySchemaModel;
+}
+/**
+ * Declaration of an event that an operation may emit.
+ * Can be a reference to an `EventSpec` or an inline definition.
+ */
+type EmitDecl = EmitDeclRef | EmitDeclInline;
+declare const isEmitDeclRef: (e: EmitDecl) => e is EmitDeclRef;
+interface TelemetryTrigger {
+  event: {
+    key: string;
+    version?: number;
+  };
+  properties?: (args: {
+    input: unknown;
+    output?: unknown;
+    error?: unknown;
+  }) => Record<string, unknown>;
+}
+interface OperationSpecMeta extends OwnerShipMeta {
+  kind: OpKind;
+  /** Business goal: why this exists */
+  goal: string;
+  /** Background, constraints, scope edges (feeds docs & LLM context) */
+  context: string;
+}
+/**
+ * The core specification interface for any operation (Command or Query).
+ *
+ * @template Input - The Zod-backed schema model for the input payload.
+ * @template Output - The Zod-backed schema model for the output payload, or a resource reference.
+ * @template Events - Tuple of events that this operation may emit.
+ */
+interface OperationSpec<Input extends AnySchemaModel, Output extends AnySchemaModel | ResourceRefDescriptor<boolean>, Events extends readonly EmitDecl[] | undefined = readonly EmitDecl[] | undefined> {
+  meta: OperationSpecMeta;
+  io: {
+    /** Zod schema for input body payload */
+    input: Input | null;
+    /** Zod schema for URL path parameters */
+    params?: AnySchemaModel;
+    /** Zod schema for query string parameters */
+    query?: AnySchemaModel;
+    /** Zod schema for HTTP headers */
+    headers?: AnySchemaModel;
+    /** Zod schema for output payload */
+    output: Output;
+    /** Named, typed errors this op may throw (optional) */
+    errors?: Record<string, {
+      description: string;
+      http?: number;
+      gqlCode?: string;
+      when: string;
+    }>;
+  };
+  policy: {
+    /** Minimal auth category allowed to call this op */
+    auth: 'anonymous' | 'user' | 'admin';
+    /** Idempotency hint. Queries default true; commands default false. */
+    idempotent?: boolean;
+    /** Soft rate limit suggestion; adapter enforces via limiter */
+    rateLimit?: {
+      rpm: number;
+      key: 'user' | 'org' | 'global';
+    };
+    /** Feature flags that must be ON for this op to run */
+    flags?: string[];
+    /** Whether a human must approve before action (e.g., risky commands) */
+    escalate?: 'human_review' | null;
+    /** JSONPath-like pointers to redact from logs/prompts */
+    pii?: string[];
+    /** Referenced policy specs governing access */
+    policies?: PolicyRef[];
+    /** Field-level overrides referencing policy specs */
+    fieldPolicies?: {
+      field: string;
+      actions: ('read' | 'write')[];
+      policy?: PolicyRef;
+    }[];
+  };
+  sideEffects?: {
+    /** Declared events this op may emit; runtime will guard against others */
+    emits?: Events;
+    /** Analytics intents (names); the service decides the sink */
+    analytics?: string[];
+    /** Audit intents (labels); the service decides storage */
+    audit?: string[];
+  };
+  telemetry?: {
+    success?: TelemetryTrigger;
+    failure?: TelemetryTrigger;
+  };
+  tests?: TestSpecRef[];
+  transport?: {
+    rest?: {
+      /** Override HTTP method (default: POST for commands, GET for queries) */
+      method?: 'GET' | 'POST';
+      /** Override path (default derived from meta.name/version) */
+      path?: string;
+    };
+    gql?: {
+      /** Override field name (default: dots→underscores + _vN) */
+      field?: string;
+      returns?: string;
+    };
+    mcp?: {
+      /** Override tool identifier (default: "<name>.v<version>") */
+      toolName?: string;
+    };
+  };
+  acceptance?: {
+    /** Gherkin-lite scenarios for docs & auto tests */
+    scenarios?: {
+      key: string;
+      given: string[];
+      when: string[];
+      then: string[];
+    }[];
+    /** Request/response examples (used for docs & snapshot tests) */
+    examples?: {
+      key: string;
+      input: unknown;
+      output: unknown;
+    }[];
+  };
+  /**
+   * Explicit implementation file mappings.
+   * Used for tracking and verifying that this spec is correctly implemented.
+   */
+  implementations?: ImplementationRef[];
+}
+type AnyOperationSpec = OperationSpec<AnySchemaModel, AnySchemaModel | ResourceRefDescriptor<boolean>>;
+/**
+ * Helper to define a Command (write operation).
+ * Sets `kind: 'command'` and defaults `idempotent: false`.
+ */
+declare const defineCommand: <I extends AnySchemaModel, O extends AnySchemaModel | ResourceRefDescriptor<boolean>, E extends readonly EmitDecl[] | undefined = undefined>(spec: Omit<OperationSpec<I, O, E>, "meta" | "policy"> & {
+  meta: Omit<OperationSpec<I, O, E>["meta"], "kind">;
+  policy: Omit<OperationSpec<I, O, E>["policy"], "idempotent">;
+}) => OperationSpec<I, O, E>;
+/**
+ * Helper to define a Query (read-only operation).
+ * Sets `kind: 'query'` and forces `idempotent: true`.
+ */
+declare const defineQuery: <I extends AnySchemaModel, O extends AnySchemaModel | ResourceRefDescriptor<boolean>, E extends readonly EmitDecl[] | undefined = undefined>(spec: Omit<OperationSpec<I, O, E>, "meta" | "policy"> & {
+  meta: Omit<OperationSpec<I, O, E>["meta"], "kind">;
+  policy: Omit<OperationSpec<I, O, E>["policy"], "idempotent">;
+}) => OperationSpec<I, O, E>;
+//#endregion
+export { AnyOperationSpec, EmitDecl, EmitDeclInline, EmitDeclRef, ImplementationRef, ImplementationType, OpKind, OperationSpec, OperationSpecMeta, TelemetryTrigger, defineCommand, defineQuery, isEmitDeclRef };

package/dist/operations/operation.js

@@ -0,0 +1,35 @@
+//#region src/operations/operation.ts
+const isEmitDeclRef = (e) => "ref" in e;
+/**
+* Helper to define a Command (write operation).
+* Sets `kind: 'command'` and defaults `idempotent: false`.
+*/
+const defineCommand = (spec) => ({
+	...spec,
+	meta: {
+		...spec.meta,
+		kind: "command"
+	},
+	policy: {
+		...spec.policy,
+		idempotent: spec.policy?.["policy"]?.idempotent ?? false
+	}
+});
+/**
+* Helper to define a Query (read-only operation).
+* Sets `kind: 'query'` and forces `idempotent: true`.
+*/
+const defineQuery = (spec) => ({
+	...spec,
+	meta: {
+		...spec.meta,
+		kind: "query"
+	},
+	policy: {
+		...spec.policy,
+		idempotent: true
+	}
+});
+
+//#endregion
+export { defineCommand, defineQuery, isEmitDeclRef };

package/dist/operations/registry.d.ts

@@ -0,0 +1,103 @@
+import { GroupKeyFn, RegistryFilter } from "../registry-utils.js";
+import { ResourceRefDescriptor } from "../resources.js";
+import { HandlerCtx } from "../types.js";
+import { AnyOperationSpec, OperationSpec } from "./operation.js";
+import { HandlerForOperationSpec } from "../install.js";
+import { AnySchemaModel } from "@contractspec/lib.schema";
+
+//#region src/operations/registry.d.ts
+type OperationKey = `${string}.v${number}`;
+declare function opKey(key: string, version: number): OperationKey;
+type AnyOperationHandler = (args: unknown, ctx: HandlerCtx) => Promise<unknown>;
+/**
+ * In-memory registry for ContractSpecs and their bound handlers.
+ * Provides validation, policy enforcement, and guarded event emission at execute time.
+ */
+declare class OperationSpecRegistry {
+  private specs;
+  private handlers;
+  /**
+   * Registers a OperationSpec definition.
+   *
+   * @param spec - The contract specification to register.
+   * @returns The registry instance for chaining.
+   * @throws If a spec with the same name and version is already registered.
+   */
+  register<I extends AnySchemaModel, O extends AnySchemaModel | ResourceRefDescriptor<boolean>>(spec: OperationSpec<I, O>): this;
+  /**
+   * Binds a runtime handler implementation to a previously registered spec.
+   *
+   * @param spec - The spec to bind to.
+   * @param handler - The async function implementing the business logic.
+   * @returns The registry instance for chaining.
+   * @throws If the spec is not found or a handler is already bound.
+   */
+  bind<I extends AnySchemaModel, O extends AnySchemaModel | ResourceRefDescriptor<boolean>>(spec: OperationSpec<I, O>, handler: HandlerForOperationSpec<OperationSpec<I, O>>): this;
+  /**
+   * Retrieves a registered spec by name and version.
+   * If version is omitted, returns the highest version found.
+   *
+   * @param name - Operation name.
+   * @param version - (Optional) Specific version.
+   */
+  getSpec(key: string, version?: number): AnyOperationSpec | undefined;
+  /**
+   * Retrieves the bound handler for a spec.
+   */
+  getHandler(key: string, version?: number): AnyOperationHandler | undefined;
+  /** Iterate all registered specs. */
+  listSpecs(): AnyOperationSpec[];
+  /** Iterate all bound operations (spec+handler). */
+  listBound(): {
+    spec: AnyOperationSpec;
+    handler: AnyOperationHandler;
+  }[];
+  /**
+   * Filter specs by criteria.
+   */
+  filter(criteria: RegistryFilter): AnyOperationSpec[];
+  /**
+   * List specs with specific tag.
+   */
+  listByTag(tag: string): AnyOperationSpec[];
+  /**
+   * List specs by owner.
+   */
+  listByOwner(owner: string): AnyOperationSpec[];
+  /**
+   * Group specs by key function.
+   */
+  groupBy(keyFn: GroupKeyFn<AnyOperationSpec>): Map<string, AnyOperationSpec[]>;
+  /**
+   * Group by domain (first segment of name).
+   */
+  groupByDomain(): Map<string, AnyOperationSpec[]>;
+  /**
+   * Group by tag.
+   */
+  groupByTag(): Map<string, AnyOperationSpec[]>;
+  /**
+   * Get unique tags from all specs.
+   */
+  getUniqueTags(): string[];
+  /**
+   * Get unique owners from all specs.
+   */
+  getUniqueOwners(): string[];
+  /**
+   * Execute an operation by name/version with full runtime protections:
+   * 1. Validates input against Zod schema.
+   * 2. Enforces policy (Auth, RBAC, Rate Limits) via PDP.
+   * 3. Guards event emission to ensure only declared events are sent.
+   * 4. Validates output against Zod schema (if applicable).
+   * 5. Tracks telemetry (success/failure).
+   *
+   * @param key - Operation key.
+   * @param version - Operation version (optional, defaults to latest).
+   * @param rawInput - The raw input payload (e.g. from JSON body).
+   * @param ctx - The runtime context (actor, tenant, etc.).
+   */
+  execute(key: string, version: number | undefined, rawInput: unknown, ctx: HandlerCtx): Promise<unknown>;
+}
+//#endregion
+export { OperationKey, OperationSpecRegistry, opKey };

package/dist/operations/registry.js

@@ -0,0 +1,252 @@
+import { GroupingStrategies, filterBy, getUniqueOwners, getUniqueTags, groupBy, init_registry_utils } from "../registry-utils.js";
+import { eventKey } from "../events.js";
+import { isEmitDeclRef } from "./operation.js";
+
+//#region src/operations/registry.ts
+init_registry_utils();
+function opKey(key, version) {
+	return `${key}.v${version}`;
+}
+/**
+* In-memory registry for ContractSpecs and their bound handlers.
+* Provides validation, policy enforcement, and guarded event emission at execute time.
+*/
+var OperationSpecRegistry = class {
+	specs = /* @__PURE__ */ new Map();
+	handlers = /* @__PURE__ */ new Map();
+	/**
+	* Registers a OperationSpec definition.
+	*
+	* @param spec - The contract specification to register.
+	* @returns The registry instance for chaining.
+	* @throws If a spec with the same name and version is already registered.
+	*/
+	register(spec) {
+		const key = opKey(spec.meta.key, spec.meta.version);
+		if (this.specs.has(key)) throw new Error(`Duplicate spec ${key}`);
+		this.specs.set(key, spec);
+		return this;
+	}
+	/**
+	* Binds a runtime handler implementation to a previously registered spec.
+	*
+	* @param spec - The spec to bind to.
+	* @param handler - The async function implementing the business logic.
+	* @returns The registry instance for chaining.
+	* @throws If the spec is not found or a handler is already bound.
+	*/
+	bind(spec, handler) {
+		const key = opKey(spec.meta.key, spec.meta.version);
+		if (!this.specs.has(key)) throw new Error(`Cannot bind; spec not found: ${key}`);
+		if (this.handlers.has(key)) throw new Error(`Handler already bound for ${key}`);
+		this.handlers.set(key, handler);
+		return this;
+	}
+	/**
+	* Retrieves a registered spec by name and version.
+	* If version is omitted, returns the highest version found.
+	*
+	* @param name - Operation name.
+	* @param version - (Optional) Specific version.
+	*/
+	getSpec(key, version) {
+		if (version != null) return this.specs.get(opKey(key, version));
+		let found;
+		let maxV = -Infinity;
+		for (const [k, s] of this.specs.entries()) {
+			if (!k.startsWith(`${key}.v`)) continue;
+			if (s.meta.version > maxV) {
+				maxV = s.meta.version;
+				found = s;
+			}
+		}
+		return found;
+	}
+	/**
+	* Retrieves the bound handler for a spec.
+	*/
+	getHandler(key, version) {
+		const spec = this.getSpec(key, version);
+		if (!spec) return void 0;
+		return this.handlers.get(opKey(spec.meta.key, spec.meta.version));
+	}
+	/** Iterate all registered specs. */
+	listSpecs() {
+		return [...this.specs.values()];
+	}
+	/** Iterate all bound operations (spec+handler). */
+	listBound() {
+		const out = [];
+		for (const [k, spec] of this.specs.entries()) {
+			const h = this.handlers.get(k);
+			if (h) out.push({
+				spec,
+				handler: h
+			});
+		}
+		return out;
+	}
+	/**
+	* Filter specs by criteria.
+	*/
+	filter(criteria) {
+		return filterBy(this.listSpecs(), criteria);
+	}
+	/**
+	* List specs with specific tag.
+	*/
+	listByTag(tag) {
+		return this.listSpecs().filter((s) => s.meta.tags?.includes(tag));
+	}
+	/**
+	* List specs by owner.
+	*/
+	listByOwner(owner) {
+		return this.listSpecs().filter((s) => s.meta.owners?.includes(owner));
+	}
+	/**
+	* Group specs by key function.
+	*/
+	groupBy(keyFn) {
+		return groupBy(this.listSpecs(), keyFn);
+	}
+	/**
+	* Group by domain (first segment of name).
+	*/
+	groupByDomain() {
+		return this.groupBy(GroupingStrategies.byDomain);
+	}
+	/**
+	* Group by tag.
+	*/
+	groupByTag() {
+		return this.groupBy(GroupingStrategies.byTag);
+	}
+	/**
+	* Get unique tags from all specs.
+	*/
+	getUniqueTags() {
+		return getUniqueTags(this.listSpecs());
+	}
+	/**
+	* Get unique owners from all specs.
+	*/
+	getUniqueOwners() {
+		return getUniqueOwners(this.listSpecs());
+	}
+	/**
+	* Execute an operation by name/version with full runtime protections:
+	* 1. Validates input against Zod schema.
+	* 2. Enforces policy (Auth, RBAC, Rate Limits) via PDP.
+	* 3. Guards event emission to ensure only declared events are sent.
+	* 4. Validates output against Zod schema (if applicable).
+	* 5. Tracks telemetry (success/failure).
+	*
+	* @param key - Operation key.
+	* @param version - Operation version (optional, defaults to latest).
+	* @param rawInput - The raw input payload (e.g. from JSON body).
+	* @param ctx - The runtime context (actor, tenant, etc.).
+	*/
+	async execute(key, version, rawInput, ctx) {
+		const baseSpec = this.getSpec(key, version);
+		if (!baseSpec) throw new Error(`Spec not found for ${key}${version ? `.v${version}` : ""}`);
+		const spec = await ctx.specVariantResolver?.resolve({
+			name: baseSpec.meta.key,
+			version: baseSpec.meta.version,
+			kind: baseSpec.meta.kind
+		}, ctx) ?? baseSpec;
+		let handlerKey = opKey(spec.meta.key, spec.meta.version);
+		let handler = this.handlers.get(handlerKey);
+		if (!handler) {
+			const fallbackKey = opKey(baseSpec.meta.key, baseSpec.meta.version);
+			handler = this.handlers.get(fallbackKey);
+			handlerKey = fallbackKey;
+		}
+		if (!handler) throw new Error(`No handler bound for ${handlerKey}`);
+		const parsedInput = spec.io.input?.getZod().parse(rawInput);
+		if (ctx.decide) {
+			const [service, command] = spec.meta.key.split(".");
+			if (!service || !command) throw new Error(`Invalid spec name: ${spec.meta.key}`);
+			const decision = await ctx.decide({
+				service,
+				command,
+				version: spec.meta.version,
+				actor: ctx.actor ?? "anonymous",
+				channel: ctx.channel,
+				roles: ctx.roles,
+				organizationId: ctx.organizationId,
+				userId: ctx.userId,
+				flags: []
+			});
+			if (decision.effect === "deny") throw new Error(`PolicyDenied: ${spec.meta.key}.v${spec.meta.version}`);
+			if (decision.rateLimit && ctx.rateLimit) {
+				const key$1 = decision.rateLimit.key ?? "default";
+				const rpm = decision.rateLimit.rpm ?? 60;
+				await ctx.rateLimit(key$1, 1, rpm);
+			}
+		}
+		const allowedEvents = /* @__PURE__ */ new Map();
+		if (spec.sideEffects?.emits) for (const e of spec.sideEffects.emits) if (isEmitDeclRef(e)) {
+			const eventSpec = ctx.eventSpecResolver?.get(e.ref.key, e.ref.version);
+			if (eventSpec) allowedEvents.set(`${e.ref.key}.v${e.ref.version}`, eventSpec.payload);
+		} else allowedEvents.set(`${e.key}.v${e.version}`, e.payload);
+		const emitGuard = async (eventName, eventVersion, payload) => {
+			const key2 = eventKey(eventName, eventVersion);
+			const schema = allowedEvents.get(key2);
+			if (!schema) throw new Error(`UndeclaredEvent: ${key2} not allowed by ${opKey(spec.meta.key, spec.meta.version)}`);
+			const parsed = schema.getZod().parse(payload);
+			await ctx.eventPublisher?.({
+				key: eventName,
+				version: eventVersion,
+				payload: parsed,
+				traceId: ctx.traceId
+			});
+		};
+		if (ctx.appConfig) {
+			if (!ctx.branding) ctx.branding = ctx.appConfig.branding;
+			if (!ctx.translation) ctx.translation = { config: ctx.appConfig.translation };
+			else if (!ctx.translation.config) ctx.translation = {
+				...ctx.translation,
+				config: ctx.appConfig.translation
+			};
+		}
+		const telemetryContext = ctx.telemetry;
+		const trackTelemetry = async (trigger, details) => {
+			if (!telemetryContext || !trigger?.event) return;
+			try {
+				const props = trigger.properties?.(details) ?? {};
+				await telemetryContext.track(trigger.event.key, trigger.event.version ?? 1, props, {
+					tenantId: ctx.organizationId ?? void 0,
+					organizationId: ctx.organizationId,
+					userId: ctx.userId,
+					actor: ctx.actor,
+					channel: ctx.channel,
+					metadata: ctx.traceId ? { traceId: ctx.traceId } : void 0
+				});
+			} catch (_error) {}
+		};
+		let result;
+		try {
+			result = await handler(parsedInput, {
+				...ctx,
+				__emitGuard__: emitGuard
+			});
+		} catch (error) {
+			if (spec.telemetry?.failure) await trackTelemetry(spec.telemetry.failure, {
+				input: parsedInput ?? rawInput,
+				error
+			});
+			throw error;
+		}
+		if (spec.telemetry?.success) await trackTelemetry(spec.telemetry.success, {
+			input: parsedInput ?? rawInput,
+			output: result
+		});
+		const outputModel = spec.io.output;
+		if (outputModel?.getZod) return outputModel.getZod().parse(result);
+		return result;
+	}
+};
+
+//#endregion
+export { OperationSpecRegistry, opKey };

package/dist/ownership.d.ts

@@ -0,0 +1,84 @@
+import { DocId } from "./docs/registry.js";
+import "./docs/index.js";
+
+//#region src/ownership.d.ts
+declare const StabilityEnum: {
+  readonly Idea: "idea";
+  readonly InCreation: "in_creation";
+  readonly Experimental: "experimental";
+  readonly Beta: "beta";
+  readonly Stable: "stable";
+  readonly Deprecated: "deprecated";
+};
+type Stability = (typeof StabilityEnum)[keyof typeof StabilityEnum];
+declare const OwnersEnum: {
+  readonly PlatformCore: "platform.core";
+  readonly PlatformSigil: "platform.sigil";
+  readonly PlatformMarketplace: "platform.marketplace";
+  readonly PlatformMessaging: "platform.messaging";
+  readonly PlatformContent: "platform.content";
+  readonly PlatformFeatureFlags: "platform.featureflags";
+  readonly PlatformFinance: "platform.finance";
+};
+type Owner = (typeof OwnersEnum)[keyof typeof OwnersEnum] | (string & {});
+declare const Owners: {
+  readonly PlatformCore: "platform.core";
+  readonly PlatformSigil: "platform.sigil";
+  readonly PlatformMarketplace: "platform.marketplace";
+  readonly PlatformMessaging: "platform.messaging";
+  readonly PlatformContent: "platform.content";
+  readonly PlatformFeatureFlags: "platform.featureflags";
+  readonly PlatformFinance: "platform.finance";
+};
+declare const TagsEnum: {
+  readonly Spots: "spots";
+  readonly Collectivity: "collectivity";
+  readonly Marketplace: "marketplace";
+  readonly Sellers: "sellers";
+  readonly Auth: "auth";
+  readonly Login: "login";
+  readonly Signup: "signup";
+  readonly Guide: "guide";
+  readonly Docs: "docs";
+  readonly I18n: "i18n";
+  readonly Incident: "incident";
+  readonly Automation: "automation";
+  readonly Hygiene: "hygiene";
+};
+type Tag = (typeof TagsEnum)[keyof typeof TagsEnum] | (string & {});
+declare const Tags: {
+  readonly Spots: "spots";
+  readonly Collectivity: "collectivity";
+  readonly Marketplace: "marketplace";
+  readonly Sellers: "sellers";
+  readonly Auth: "auth";
+  readonly Login: "login";
+  readonly Signup: "signup";
+  readonly Guide: "guide";
+  readonly Docs: "docs";
+  readonly I18n: "i18n";
+  readonly Incident: "incident";
+  readonly Automation: "automation";
+  readonly Hygiene: "hygiene";
+};
+interface OwnerShipMeta {
+  /** Breaking changes => bump version */
+  version: number;
+  /** Fully-qualified spec key (e.g., "sigil.beginSignup") */
+  key: string;
+  /** Human-friendly spec title (e.g., "Signup begin") */
+  title?: string;
+  /** Short human-friendly summary */
+  description: string;
+  domain?: string;
+  /** Lifecycle marker for comms & tooling */
+  stability: Stability;
+  /** Owners for CODEOWNERS / on-call / approvals */
+  owners: Owner[];
+  /** Search tags, grouping, docs navigation */
+  tags: Tag[];
+  /** Doc block(s) for this operation. */
+  docId?: DocId[];
+}
+//#endregion
+export { Owner, OwnerShipMeta, Owners, OwnersEnum, Stability, StabilityEnum, Tag, Tags, TagsEnum };