@contractspec/lib.contracts 0.0.0-canary-20260119225944 → 0.0.0-canary-20260202053150

package/dist/docs/tech/report-verification-table.docblock.js

@@ -0,0 +1,50 @@
+import { registerDocBlocks } from "../registry.js";
+
+//#region src/docs/tech/report-verification-table.docblock.ts
+registerDocBlocks([{
+	id: "docs.tech.report-verification-table",
+	title: "Contract Verification Table",
+	summary: "How the impact report renders per-contract verification status.",
+	kind: "how",
+	visibility: "public",
+	route: "/docs/tech/report/verification-table",
+	tags: [
+		"report",
+		"drift",
+		"verification",
+		"impact"
+	],
+	owners: ["platform.core"],
+	domain: "report",
+	body: `# Contract Verification Table
+
+The impact report includes an optional per-contract verification table that summarises the health of each contract at a glance.
+
+## Columns
+
+| Column | Description |
+|--------|-------------|
+| Contract / Endpoint / Event | Fully qualified contract name (e.g. \`user.create\`) |
+| Drift debt | Number of mismatches currently detected |
+| Time since verified | Human-friendly elapsed time (e.g. "23 days") or "Never" |
+| Surfaces covered | Comma-separated list (API, runtime validation, UI form, docs/examples, permissions) |
+| Last verified commit | Short SHA of the last drift-free commit |
+
+## Data flow
+
+1. The drift detector produces per-contract mismatch counts.
+2. \`.contractspec/verified.json\` records the last clean commit per contract.
+3. The report script reads both sources and renders the Markdown table.
+
+## Backward compatibility
+
+When \`contracts\` is absent from the report JSON, the table is skipped and the existing report sections render unchanged.
+
+## Contracts
+
+- Query: \`report.getContractVerificationStatus\` (v1.0.0)
+- Data view: \`report.contractVerificationTable\` (v1.0.0)
+`
+}]);
+
+//#endregion

package/dist/docs/views/contractReference.dataView.d.ts

@@ -0,0 +1,7 @@
+import { DataViewSpec } from "../../data-views/spec.js";
+import "../../index.js";
+
+//#region src/docs/views/contractReference.dataView.d.ts
+declare const ContractReferenceDataView: DataViewSpec;
+//#endregion
+export { ContractReferenceDataView };

package/dist/docs/views/contractReference.dataView.js

@@ -0,0 +1,80 @@
+import { defineDataView } from "../../data-views/spec.js";
+import "../../data-views/index.js";
+import { DOCS_DOMAIN, DOCS_OWNERS, DOCS_STABILITY, DOCS_TAGS } from "../constants.js";
+import { docId } from "../registry.js";
+import "../ensure-docblocks.js";
+import { ContractReferenceQuery } from "../queries/contractReference.query.js";
+
+//#region src/docs/views/contractReference.dataView.ts
+const ContractReferenceDataView = defineDataView({
+	meta: {
+		key: "docs.contract.reference.view",
+		title: "Contract Reference",
+		version: "1.0.0",
+		description: "Detail view for a single contract reference.",
+		domain: DOCS_DOMAIN,
+		owners: DOCS_OWNERS,
+		tags: [...DOCS_TAGS, "reference"],
+		stability: DOCS_STABILITY,
+		entity: "contract-reference",
+		docId: [docId("docs.tech.docs-reference")]
+	},
+	source: { primary: {
+		key: ContractReferenceQuery.meta.key,
+		version: ContractReferenceQuery.meta.version
+	} },
+	view: {
+		kind: "detail",
+		fields: [
+			{
+				key: "key",
+				label: "Key",
+				dataPath: "reference.key"
+			},
+			{
+				key: "version",
+				label: "Version",
+				dataPath: "reference.version"
+			},
+			{
+				key: "type",
+				label: "Type",
+				dataPath: "reference.type"
+			},
+			{
+				key: "title",
+				label: "Title",
+				dataPath: "reference.title"
+			},
+			{
+				key: "description",
+				label: "Description",
+				dataPath: "reference.description"
+			},
+			{
+				key: "tags",
+				label: "Tags",
+				dataPath: "reference.tags"
+			},
+			{
+				key: "owners",
+				label: "Owners",
+				dataPath: "reference.owners"
+			},
+			{
+				key: "stability",
+				label: "Stability",
+				dataPath: "reference.stability"
+			}
+		],
+		primaryField: "title",
+		secondaryFields: ["description"]
+	},
+	policy: {
+		flags: [],
+		pii: []
+	}
+});
+
+//#endregion
+export { ContractReferenceDataView };

package/dist/docs/views/docsIndex.dataView.d.ts

@@ -0,0 +1,7 @@
+import { DataViewSpec } from "../../data-views/spec.js";
+import "../../index.js";
+
+//#region src/docs/views/docsIndex.dataView.d.ts
+declare const DocsIndexDataView: DataViewSpec;
+//#endregion
+export { DocsIndexDataView };

package/dist/docs/views/docsIndex.dataView.js

@@ -0,0 +1,136 @@
+import { defineDataView } from "../../data-views/spec.js";
+import "../../data-views/index.js";
+import { DOCS_DOMAIN, DOCS_OWNERS, DOCS_STABILITY, DOCS_TAGS } from "../constants.js";
+import { docId } from "../registry.js";
+import "../ensure-docblocks.js";
+import { DocsIndexQuery } from "../queries/docsIndex.query.js";
+
+//#region src/docs/views/docsIndex.dataView.ts
+const DocsIndexDataView = defineDataView({
+	meta: {
+		key: "docs.index.view",
+		title: "Docs Index",
+		version: "1.0.0",
+		description: "List and filter documentation entries.",
+		domain: DOCS_DOMAIN,
+		owners: DOCS_OWNERS,
+		tags: [...DOCS_TAGS, "index"],
+		stability: DOCS_STABILITY,
+		entity: "docs",
+		docId: [docId("docs.tech.docs-search")]
+	},
+	source: { primary: {
+		key: DocsIndexQuery.meta.key,
+		version: DocsIndexQuery.meta.version
+	} },
+	view: {
+		kind: "list",
+		fields: [
+			{
+				key: "id",
+				label: "ID",
+				dataPath: "id"
+			},
+			{
+				key: "title",
+				label: "Title",
+				dataPath: "title"
+			},
+			{
+				key: "summary",
+				label: "Summary",
+				dataPath: "summary"
+			},
+			{
+				key: "route",
+				label: "Route",
+				dataPath: "route"
+			},
+			{
+				key: "tags",
+				label: "Tags",
+				dataPath: "tags",
+				format: "badge"
+			},
+			{
+				key: "kind",
+				label: "Kind",
+				dataPath: "kind"
+			},
+			{
+				key: "visibility",
+				label: "Visibility",
+				dataPath: "visibility"
+			}
+		],
+		primaryField: "title",
+		secondaryFields: ["summary", "route"],
+		filters: [
+			{
+				key: "query",
+				label: "Search",
+				field: "query",
+				type: "search"
+			},
+			{
+				key: "visibility",
+				label: "Visibility",
+				field: "visibility",
+				type: "enum",
+				options: [
+					{
+						value: "public",
+						label: "Public"
+					},
+					{
+						value: "internal",
+						label: "Internal"
+					},
+					{
+						value: "mixed",
+						label: "Mixed"
+					}
+				]
+			},
+			{
+				key: "kind",
+				label: "Kind",
+				field: "kind",
+				type: "enum",
+				options: [
+					{
+						value: "goal",
+						label: "Goal"
+					},
+					{
+						value: "how",
+						label: "How"
+					},
+					{
+						value: "usage",
+						label: "Usage"
+					},
+					{
+						value: "reference",
+						label: "Reference"
+					},
+					{
+						value: "faq",
+						label: "FAQ"
+					},
+					{
+						value: "changelog",
+						label: "Changelog"
+					}
+				]
+			}
+		]
+	},
+	policy: {
+		flags: [],
+		pii: []
+	}
+});
+
+//#endregion
+export { DocsIndexDataView };

package/dist/docs/views/exampleCatalog.dataView.d.ts

@@ -0,0 +1,7 @@
+import { DataViewSpec } from "../../data-views/spec.js";
+import "../../index.js";
+
+//#region src/docs/views/exampleCatalog.dataView.d.ts
+declare const ExampleCatalogDataView: DataViewSpec;
+//#endregion
+export { ExampleCatalogDataView };

package/dist/docs/views/exampleCatalog.dataView.js

@@ -0,0 +1,91 @@
+import { defineDataView } from "../../data-views/spec.js";
+import "../../data-views/index.js";
+import { DOCS_DOMAIN, DOCS_OWNERS, DOCS_STABILITY, DOCS_TAGS } from "../constants.js";
+import { docId } from "../registry.js";
+import "../ensure-docblocks.js";
+import { DocsIndexQuery } from "../queries/docsIndex.query.js";
+
+//#region src/docs/views/exampleCatalog.dataView.ts
+const ExampleCatalogDataView = defineDataView({
+	meta: {
+		key: "docs.examples.catalog.view",
+		title: "Examples Catalog",
+		version: "1.0.0",
+		description: "Catalog view of ContractSpec examples and demos.",
+		domain: DOCS_DOMAIN,
+		owners: DOCS_OWNERS,
+		tags: [...DOCS_TAGS, "examples"],
+		stability: DOCS_STABILITY,
+		entity: "docs-examples",
+		docId: [docId("docs.tech.docs-examples")]
+	},
+	source: { primary: {
+		key: DocsIndexQuery.meta.key,
+		version: DocsIndexQuery.meta.version
+	} },
+	view: {
+		kind: "grid",
+		fields: [
+			{
+				key: "id",
+				label: "ID",
+				dataPath: "id"
+			},
+			{
+				key: "title",
+				label: "Title",
+				dataPath: "title"
+			},
+			{
+				key: "summary",
+				label: "Summary",
+				dataPath: "summary"
+			},
+			{
+				key: "route",
+				label: "Route",
+				dataPath: "route"
+			},
+			{
+				key: "tags",
+				label: "Tags",
+				dataPath: "tags",
+				format: "badge"
+			}
+		],
+		primaryField: "title",
+		secondaryFields: ["summary"],
+		filters: [{
+			key: "query",
+			label: "Search",
+			field: "query",
+			type: "search"
+		}, {
+			key: "tags",
+			label: "Tags",
+			field: "tag",
+			type: "enum",
+			options: [
+				{
+					value: "examples",
+					label: "Examples"
+				},
+				{
+					value: "templates",
+					label: "Templates"
+				},
+				{
+					value: "sandbox",
+					label: "Sandbox"
+				}
+			]
+		}]
+	},
+	policy: {
+		flags: [],
+		pii: []
+	}
+});
+
+//#endregion
+export { ExampleCatalogDataView };

package/dist/docs/views/index.d.ts

@@ -0,0 +1,4 @@
+import { DocsIndexDataView } from "./docsIndex.dataView.js";
+import { ContractReferenceDataView } from "./contractReference.dataView.js";
+import { ExampleCatalogDataView } from "./exampleCatalog.dataView.js";
+export { ContractReferenceDataView, DocsIndexDataView, ExampleCatalogDataView };

package/dist/docs/views/index.js

@@ -0,0 +1,5 @@
+import { DocsIndexDataView } from "./docsIndex.dataView.js";
+import { ContractReferenceDataView } from "./contractReference.dataView.js";
+import { ExampleCatalogDataView } from "./exampleCatalog.dataView.js";
+
+export { ContractReferenceDataView, DocsIndexDataView, ExampleCatalogDataView };

package/dist/events.d.ts

@@ -1,45 +1,111 @@
+import { CapabilityRef } from "./capabilities/capabilities.js";
+import { SpecContractRegistry } from "./registry.js";
 import { DocId } from "./docs/registry.js";
 import { OwnerShipMeta } from "./ownership.js";
-import { SpecContractRegistry } from "./registry.js";
 import { AnySchemaModel } from "@contractspec/lib.schema";
 
 //#region src/events.d.ts
+
+/**
+ * Metadata for an event specification.
+ * Extends OwnerShipMeta with event-specific documentation.
+ */
 interface EventSpecMeta extends Omit<OwnerShipMeta, 'docId'> {
-  /** Doc block(s) for this operation. */
+  /** Associated DocBlock identifiers for this event. */
   docId?: DocId[];
 }
 /**
- * Typed event specification. Declare once, validate payloads at publish time,
- * and guard emissions via the contracts runtime.
+ * Typed event specification.
+ *
+ * Declare once, validate payloads at publish time, and guard emissions
+ * via the contracts runtime. Events are the backbone of event-driven
+ * architectures in ContractSpec.
+ *
+ * @typeParam T - The SchemaModel type defining the event payload structure
  */
 interface EventSpec<T extends AnySchemaModel> {
+  /** Event metadata including key, version, and ownership. */
   meta: EventSpecMeta;
-  /** JSON-like paths to redact from logs/exports. */
+  /**
+   * Optional reference to the capability that provides this event.
+   * Used for bidirectional linking between capabilities and events.
+   */
+  capability?: CapabilityRef;
+  /**
+   * JSON paths to PII fields that should be redacted in logs/exports.
+   * @example ['email', 'user.phone', 'billing.address']
+   */
   pii?: string[];
   /** Event payload schema from @contractspec/lib.schema. */
   payload: T;
 }
+/**
+ * Type alias for any EventSpec regardless of payload type.
+ * Useful for collections and registries.
+ */
 type AnyEventSpec<T extends AnySchemaModel = AnySchemaModel> = EventSpec<T>;
-/** Identity function to keep type inference when declaring events. */
+/**
+ * Identity function to define an event spec with full type inference.
+ *
+ * @param e - The event specification
+ * @returns The same event specification with preserved types
+ *
+ * @example
+ * ```typescript
+ * const MyEvent = defineEvent({
+ *   meta: { key: 'my.event', version: '1.0.0', ... },
+ *   payload: myPayloadSchema,
+ * });
+ * ```
+ */
 declare function defineEvent<T extends AnySchemaModel>(e: EventSpec<T>): EventSpec<T>;
+/**
+ * Wrapper for a published event with metadata.
+ *
+ * Used when events are serialized for transport or storage.
+ * Contains the validated payload plus envelope metadata.
+ *
+ * @typeParam T - The payload type
+ */
 interface EventEnvelope<T> {
-  /** Unique identifier for the published event (UUID recommended). */
+  /** Unique identifier for this event instance (UUID recommended). */
   id: string;
-  /** ISO timestamp when the event occurred. */
+  /** ISO 8601 timestamp when the event occurred. */
   occurredAt: string;
-  /** Optional trace identifier for correlating across services. */
+  /** Trace identifier for correlating across services. */
   traceId?: string;
-  /** Event name as published (should match spec.name). */
+  /** Event key (should match spec.meta.key). */
   key: string;
-  /** Event version as published (should match spec.version). */
+  /** Event version (should match spec.meta.version). */
   version: string;
-  /** Validated payload. */
+  /** Validated event payload. */
   payload: T;
 }
+/**
+ * Template literal type for event keys.
+ * Format: "key.vversion" (e.g., "user.created.v1.0.0")
+ */
 type EventKey = `${string}.v${string}`;
-/** Build a stable string key for an event name/version pair. */
+/**
+ * Builds a stable string key for an event name/version pair.
+ *
+ * @param key - The event key (e.g., "user.created")
+ * @param version - The event version (e.g., "1.0.0")
+ * @returns A string in format "key.vversion"
+ *
+ * @example
+ * ```typescript
+ * const key = eventKey('user.created', '1.0.0');
+ * // "user.created.v1.0.0"
+ * ```
+ */
 declare const eventKey: (key: string, version: string) => EventKey;
-/** In-memory registry for EventSpec. */
+/**
+ * In-memory registry for EventSpec instances.
+ *
+ * Provides registration, lookup, and listing of event specifications.
+ * Used by the contracts runtime to validate event emissions.
+ */
 declare class EventRegistry extends SpecContractRegistry<'event', AnyEventSpec> {
   constructor(items?: AnyEventSpec[]);
 }

package/dist/events.js

@@ -2,13 +2,43 @@ import { SpecContractRegistry } from "./registry.js";
 import "@contractspec/lib.schema";
 
 //#region src/events.ts
-/** Identity function to keep type inference when declaring events. */
+/**
+* Identity function to define an event spec with full type inference.
+*
+* @param e - The event specification
+* @returns The same event specification with preserved types
+*
+* @example
+* ```typescript
+* const MyEvent = defineEvent({
+*   meta: { key: 'my.event', version: '1.0.0', ... },
+*   payload: myPayloadSchema,
+* });
+* ```
+*/
 function defineEvent(e) {
 	return e;
 }
-/** Build a stable string key for an event name/version pair. */
+/**
+* Builds a stable string key for an event name/version pair.
+*
+* @param key - The event key (e.g., "user.created")
+* @param version - The event version (e.g., "1.0.0")
+* @returns A string in format "key.vversion"
+*
+* @example
+* ```typescript
+* const key = eventKey('user.created', '1.0.0');
+* // "user.created.v1.0.0"
+* ```
+*/
 const eventKey = (key, version) => `${key}.v${version}`;
-/** In-memory registry for EventSpec. */
+/**
+* In-memory registry for EventSpec instances.
+*
+* Provides registration, lookup, and listing of event specifications.
+* Used by the contracts runtime to validate event emissions.
+*/
 var EventRegistry = class extends SpecContractRegistry {
 	constructor(items) {
 		super("event", items);

package/dist/examples/schema.d.ts

@@ -3,11 +3,11 @@ import { z as z$1 } from "zod";
 
 //#region src/examples/schema.d.ts
 declare const ExampleKindSchema: z$1.ZodEnum<{
+  integration: "integration";
+  knowledge: "knowledge";
   library: "library";
   workflow: "workflow";
-  knowledge: "knowledge";
   template: "template";
-  integration: "integration";
   blueprint: "blueprint";
   ui: "ui";
   script: "script";
@@ -18,10 +18,10 @@ declare const ExampleVisibilitySchema: z$1.ZodEnum<{
   internal: "internal";
 }>;
 declare const ExampleSandboxModeSchema: z$1.ZodEnum<{
+  markdown: "markdown";
   playground: "playground";
   specs: "specs";
   builder: "builder";
-  markdown: "markdown";
   evolution: "evolution";
 }>;
 declare const StabilitySchema: z$1.ZodEnum<{
@@ -42,10 +42,10 @@ declare const ExampleDocumentationSchema: z$1.ZodObject<{
 declare const ExampleSandboxSupportSchema: z$1.ZodObject<{
   enabled: z$1.ZodBoolean;
   modes: z$1.ZodArray<z$1.ZodEnum<{
+    markdown: "markdown";
     playground: "playground";
     specs: "specs";
     builder: "builder";
-    markdown: "markdown";
     evolution: "evolution";
   }>>;
 }, z$1.core.$strip>;
@@ -61,10 +61,10 @@ declare const ExampleSurfacesSchema: z$1.ZodObject<{
   sandbox: z$1.ZodObject<{
     enabled: z$1.ZodBoolean;
     modes: z$1.ZodArray<z$1.ZodEnum<{
+      markdown: "markdown";
       playground: "playground";
       specs: "specs";
       builder: "builder";
-      markdown: "markdown";
       evolution: "evolution";
     }>>;
   }, z$1.core.$strip>;
@@ -104,11 +104,11 @@ declare const ExampleMetaSchema: z$1.ZodObject<{
   tags: z$1.ZodArray<z$1.ZodString>;
   docId: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
   kind: z$1.ZodEnum<{
+    integration: "integration";
+    knowledge: "knowledge";
     library: "library";
     workflow: "workflow";
-    knowledge: "knowledge";
     template: "template";
-    integration: "integration";
     blueprint: "blueprint";
     ui: "ui";
     script: "script";
@@ -152,11 +152,11 @@ declare const ExampleSpecSchema: z$1.ZodObject<{
     tags: z$1.ZodArray<z$1.ZodString>;
     docId: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
     kind: z$1.ZodEnum<{
+      integration: "integration";
+      knowledge: "knowledge";
       library: "library";
       workflow: "workflow";
-      knowledge: "knowledge";
       template: "template";
-      integration: "integration";
       blueprint: "blueprint";
       ui: "ui";
       script: "script";
@@ -180,10 +180,10 @@ declare const ExampleSpecSchema: z$1.ZodObject<{
     sandbox: z$1.ZodObject<{
       enabled: z$1.ZodBoolean;
       modes: z$1.ZodArray<z$1.ZodEnum<{
+        markdown: "markdown";
         playground: "playground";
         specs: "specs";
         builder: "builder";
-        markdown: "markdown";
         evolution: "evolution";
       }>>;
     }, z$1.core.$strip>;
@@ -224,7 +224,7 @@ declare function safeParseExampleSpec(data: unknown): z$1.ZodSafeParseResult<{
     stability: "deprecated" | "idea" | "in_creation" | "experimental" | "beta" | "stable";
     owners: string[];
     tags: string[];
-    kind: "library" | "workflow" | "knowledge" | "template" | "integration" | "blueprint" | "ui" | "script";
+    kind: "integration" | "knowledge" | "library" | "workflow" | "template" | "blueprint" | "ui" | "script";
     visibility: "experimental" | "public" | "internal";
     title?: string | undefined;
     domain?: string | undefined;
@@ -235,7 +235,7 @@ declare function safeParseExampleSpec(data: unknown): z$1.ZodSafeParseResult<{
     templates: boolean;
     sandbox: {
       enabled: boolean;
-      modes: ("playground" | "specs" | "builder" | "markdown" | "evolution")[];
+      modes: ("markdown" | "playground" | "specs" | "builder" | "evolution")[];
     };
     studio: {
       enabled: boolean;

package/dist/examples/types.d.ts

@@ -1,7 +1,7 @@
-import { OwnerShipMeta } from "../ownership.js";
 import { FeatureModuleSpec, FeatureRef } from "../features/types.js";
 import "../features/index.js";
 import { AppBlueprintSpec, SpecPointer } from "../app-config/spec.js";
+import { OwnerShipMeta } from "../ownership.js";
 
 //#region src/examples/types.d.ts
 /** Kind of example - determines how it's presented in catalogs */