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

package/dist/policy/validation.d.ts

@@ -0,0 +1,67 @@
+import { PolicySpec } from "./spec.js";
+import { PolicyRegistry } from "./registry.js";
+import { OperationSpecRegistry } from "../operations/registry.js";
+
+//#region src/policy/validation.d.ts
+
+type PolicyValidationLevel = 'error' | 'warning' | 'info';
+interface PolicyValidationIssue {
+  level: PolicyValidationLevel;
+  message: string;
+  path?: string;
+  context?: Record<string, unknown>;
+}
+interface PolicyValidationResult {
+  valid: boolean;
+  issues: PolicyValidationIssue[];
+}
+/**
+ * Validate a policy spec for internal consistency.
+ *
+ * @param spec - Policy spec to validate
+ * @returns Validation result with any issues found
+ *
+ * @example
+ * ```typescript
+ * const result = validatePolicySpec(myPolicy);
+ * if (!result.valid) {
+ *   console.log('Issues:', result.issues);
+ * }
+ * ```
+ */
+declare function validatePolicySpec(spec: PolicySpec): PolicyValidationResult;
+interface PolicyConsistencyDeps {
+  policies: PolicyRegistry;
+  operations?: OperationSpecRegistry;
+}
+/**
+ * Validate policy consistency across registries.
+ *
+ * Checks that:
+ * - Operations reference valid policies
+ * - Policy actions align with operation kinds
+ *
+ * @param deps - Registry dependencies
+ * @returns Validation result
+ */
+declare function validatePolicyConsistency(deps: PolicyConsistencyDeps): PolicyValidationResult;
+declare class PolicyValidationError extends Error {
+  readonly issues: PolicyValidationIssue[];
+  constructor(message: string, issues: PolicyValidationIssue[]);
+}
+/**
+ * Assert that a policy spec is valid, throwing if not.
+ *
+ * @param spec - Policy spec to validate
+ * @throws {PolicyValidationError} If validation fails
+ */
+declare function assertPolicySpecValid(spec: PolicySpec): void;
+/**
+ * Assert policy consistency across registries.
+ *
+ * @param deps - Registry dependencies
+ * @throws {PolicyValidationError} If validation fails
+ */
+declare function assertPolicyConsistency(deps: PolicyConsistencyDeps): void;
+//#endregion
+export { PolicyConsistencyDeps, PolicyValidationError, PolicyValidationIssue, PolicyValidationLevel, PolicyValidationResult, assertPolicyConsistency, assertPolicySpecValid, validatePolicyConsistency, validatePolicySpec };

package/dist/policy/validation.js

@@ -0,0 +1,307 @@
+//#region src/policy/validation.ts
+/**
+* Validate a policy spec for internal consistency.
+*
+* @param spec - Policy spec to validate
+* @returns Validation result with any issues found
+*
+* @example
+* ```typescript
+* const result = validatePolicySpec(myPolicy);
+* if (!result.valid) {
+*   console.log('Issues:', result.issues);
+* }
+* ```
+*/
+function validatePolicySpec(spec) {
+	const issues = [];
+	validateMeta(spec, issues);
+	validateRules(spec, issues);
+	validateFieldPolicies(spec, issues);
+	validateRateLimits(spec, issues);
+	validateConsents(spec, issues);
+	validateRelationships(spec, issues);
+	return {
+		valid: issues.filter((i) => i.level === "error").length === 0,
+		issues
+	};
+}
+function validateMeta(spec, issues) {
+	const { meta } = spec;
+	if (!meta.key?.trim()) issues.push({
+		level: "error",
+		message: "Policy must have a non-empty key",
+		path: "meta.key"
+	});
+	if (!meta.version?.trim()) issues.push({
+		level: "error",
+		message: "Policy must have a non-empty version",
+		path: "meta.version"
+	});
+	if (!meta.owners?.length) issues.push({
+		level: "warning",
+		message: "Policy should specify owners",
+		path: "meta.owners"
+	});
+}
+function validateRules(spec, issues) {
+	if (!spec.rules?.length) {
+		issues.push({
+			level: "warning",
+			message: "Policy has no rules defined",
+			path: "rules"
+		});
+		return;
+	}
+	const seenRateRefs = /* @__PURE__ */ new Set();
+	spec.rules.forEach((rule, index) => {
+		const path = `rules[${index}]`;
+		if (!rule.actions?.length) issues.push({
+			level: "error",
+			message: "Rule must specify at least one action",
+			path: `${path}.actions`
+		});
+		if (!["allow", "deny"].includes(rule.effect)) issues.push({
+			level: "error",
+			message: `Invalid rule effect: ${rule.effect}`,
+			path: `${path}.effect`
+		});
+		if (typeof rule.rateLimit === "string") {
+			seenRateRefs.add(rule.rateLimit);
+			if (!spec.rateLimits?.some((rl) => rl.id === rule.rateLimit)) issues.push({
+				level: "error",
+				message: `Rate limit "${rule.rateLimit}" referenced but not defined`,
+				path: `${path}.rateLimit`
+			});
+		}
+		if (rule.requiresConsent?.length) {
+			for (const consentId of rule.requiresConsent) if (!spec.consents?.some((c) => c.id === consentId)) issues.push({
+				level: "error",
+				message: `Consent "${consentId}" referenced but not defined`,
+				path: `${path}.requiresConsent`
+			});
+		}
+		validateConditions(rule.conditions, `${path}.conditions`, issues);
+	});
+	if (spec.rateLimits?.length) {
+		for (const rl of spec.rateLimits) if (!seenRateRefs.has(rl.id)) {
+			if (!spec.rules.some((r) => typeof r.rateLimit === "object" && r.rateLimit.id === rl.id)) issues.push({
+				level: "info",
+				message: `Rate limit "${rl.id}" is defined but not referenced`,
+				path: `rateLimits`
+			});
+		}
+	}
+}
+function validateFieldPolicies(spec, issues) {
+	if (!spec.fieldPolicies?.length) return;
+	const seenFields = /* @__PURE__ */ new Map();
+	spec.fieldPolicies.forEach((rule, index) => {
+		const path = `fieldPolicies[${index}]`;
+		if (!rule.field?.trim()) issues.push({
+			level: "error",
+			message: "Field policy must specify a field",
+			path: `${path}.field`
+		});
+		if (!rule.actions?.length) issues.push({
+			level: "error",
+			message: "Field policy must specify at least one action",
+			path: `${path}.actions`
+		});
+		for (const action of rule.actions) if (!["read", "write"].includes(action)) issues.push({
+			level: "error",
+			message: `Invalid field action: ${action}`,
+			path: `${path}.actions`
+		});
+		const existing = seenFields.get(rule.field) ?? [];
+		existing.push(rule);
+		seenFields.set(rule.field, existing);
+		validateConditions(rule.conditions, `${path}.conditions`, issues);
+	});
+	for (const [field, rules] of seenFields.entries()) if (rules.length > 1) {
+		if (rules.some((r) => r.effect === "allow") && rules.some((r) => r.effect === "deny")) issues.push({
+			level: "warning",
+			message: `Field "${field}" has potentially conflicting allow/deny policies`,
+			path: "fieldPolicies",
+			context: {
+				field,
+				ruleCount: rules.length
+			}
+		});
+	}
+}
+function validateRateLimits(spec, issues) {
+	if (!spec.rateLimits?.length) return;
+	const seenIds = /* @__PURE__ */ new Set();
+	spec.rateLimits.forEach((rl, index) => {
+		const path = `rateLimits[${index}]`;
+		if (!rl.id?.trim()) issues.push({
+			level: "error",
+			message: "Rate limit must have an id",
+			path: `${path}.id`
+		});
+		else if (seenIds.has(rl.id)) issues.push({
+			level: "error",
+			message: `Duplicate rate limit id: ${rl.id}`,
+			path: `${path}.id`
+		});
+		else seenIds.add(rl.id);
+		if (typeof rl.rpm !== "number" || rl.rpm <= 0) issues.push({
+			level: "error",
+			message: "Rate limit rpm must be a positive number",
+			path: `${path}.rpm`
+		});
+		if (rl.windowSeconds !== void 0 && rl.windowSeconds <= 0) issues.push({
+			level: "error",
+			message: "Rate limit windowSeconds must be positive if specified",
+			path: `${path}.windowSeconds`
+		});
+		if (rl.burst !== void 0 && rl.burst < 0) issues.push({
+			level: "error",
+			message: "Rate limit burst must be non-negative if specified",
+			path: `${path}.burst`
+		});
+	});
+}
+function validateConsents(spec, issues) {
+	if (!spec.consents?.length) return;
+	const seenIds = /* @__PURE__ */ new Set();
+	spec.consents.forEach((consent, index) => {
+		const path = `consents[${index}]`;
+		if (!consent.id?.trim()) issues.push({
+			level: "error",
+			message: "Consent must have an id",
+			path: `${path}.id`
+		});
+		else if (seenIds.has(consent.id)) issues.push({
+			level: "error",
+			message: `Duplicate consent id: ${consent.id}`,
+			path: `${path}.id`
+		});
+		else seenIds.add(consent.id);
+		if (!consent.scope?.trim()) issues.push({
+			level: "error",
+			message: "Consent must specify a scope",
+			path: `${path}.scope`
+		});
+		if (!consent.purpose?.trim()) issues.push({
+			level: "error",
+			message: "Consent must specify a purpose",
+			path: `${path}.purpose`
+		});
+		if (consent.expiresInDays !== void 0 && consent.expiresInDays <= 0) issues.push({
+			level: "error",
+			message: "Consent expiresInDays must be positive if specified",
+			path: `${path}.expiresInDays`
+		});
+	});
+}
+function validateRelationships(spec, issues) {
+	if (!spec.relationships?.length) return;
+	const seenRelations = /* @__PURE__ */ new Set();
+	spec.relationships.forEach((rel, index) => {
+		const path = `relationships[${index}]`;
+		const key = `${rel.subjectType}:${rel.relation}:${rel.objectType}`;
+		if (!rel.subjectType?.trim()) issues.push({
+			level: "error",
+			message: "Relationship must specify subjectType",
+			path: `${path}.subjectType`
+		});
+		if (!rel.relation?.trim()) issues.push({
+			level: "error",
+			message: "Relationship must specify relation",
+			path: `${path}.relation`
+		});
+		if (!rel.objectType?.trim()) issues.push({
+			level: "error",
+			message: "Relationship must specify objectType",
+			path: `${path}.objectType`
+		});
+		if (seenRelations.has(key)) issues.push({
+			level: "warning",
+			message: `Duplicate relationship definition: ${key}`,
+			path
+		});
+		else seenRelations.add(key);
+	});
+}
+function validateConditions(conditions, path, issues) {
+	if (!conditions?.length) return;
+	conditions.forEach((cond, index) => {
+		if (!cond.expression?.trim()) issues.push({
+			level: "error",
+			message: "Condition must have a non-empty expression",
+			path: `${path}[${index}].expression`
+		});
+	});
+}
+/**
+* Validate policy consistency across registries.
+*
+* Checks that:
+* - Operations reference valid policies
+* - Policy actions align with operation kinds
+*
+* @param deps - Registry dependencies
+* @returns Validation result
+*/
+function validatePolicyConsistency(deps) {
+	const issues = [];
+	for (const policy of deps.policies.list()) {
+		const specResult = validatePolicySpec(policy);
+		issues.push(...specResult.issues.map((i) => ({
+			...i,
+			path: `${policy.meta.key}.v${policy.meta.version}${i.path ? `.${i.path}` : ""}`
+		})));
+	}
+	if (deps.operations) for (const operation of deps.operations.list()) {
+		const policyRefs = operation.policy.policies ?? [];
+		for (const ref of policyRefs) if (!deps.policies.get(ref.key, ref.version)) issues.push({
+			level: "error",
+			message: `Operation "${operation.meta.key}.v${operation.meta.version}" references unknown policy "${ref.key}.v${ref.version}"`,
+			path: `operations.${operation.meta.key}.policy.policies`
+		});
+		const fieldPolicies = operation.policy.fieldPolicies ?? [];
+		for (const fp of fieldPolicies) if (fp.policy) {
+			if (!deps.policies.get(fp.policy.key, fp.policy.version)) issues.push({
+				level: "error",
+				message: `Operation "${operation.meta.key}.v${operation.meta.version}" references unknown field policy "${fp.policy.key}.v${fp.policy.version}"`,
+				path: `operations.${operation.meta.key}.policy.fieldPolicies`
+			});
+		}
+	}
+	return {
+		valid: issues.filter((i) => i.level === "error").length === 0,
+		issues
+	};
+}
+var PolicyValidationError = class extends Error {
+	constructor(message, issues) {
+		super(message);
+		this.issues = issues;
+		this.name = "PolicyValidationError";
+	}
+};
+/**
+* Assert that a policy spec is valid, throwing if not.
+*
+* @param spec - Policy spec to validate
+* @throws {PolicyValidationError} If validation fails
+*/
+function assertPolicySpecValid(spec) {
+	const result = validatePolicySpec(spec);
+	if (!result.valid) throw new PolicyValidationError(`Policy ${spec.meta.key}.v${spec.meta.version} is invalid`, result.issues);
+}
+/**
+* Assert policy consistency across registries.
+*
+* @param deps - Registry dependencies
+* @throws {PolicyValidationError} If validation fails
+*/
+function assertPolicyConsistency(deps) {
+	const result = validatePolicyConsistency(deps);
+	if (!result.valid) throw new PolicyValidationError("Policy consistency check failed", result.issues);
+}
+
+//#endregion
+export { PolicyValidationError, assertPolicyConsistency, assertPolicySpecValid, validatePolicyConsistency, validatePolicySpec };

package/dist/presentations/presentations.d.ts

@@ -1,3 +1,4 @@
+import { CapabilityRef } from "../capabilities/capabilities.js";
 import { OwnerShipMeta } from "../ownership.js";
 import { AnySchemaModel } from "@contractspec/lib.schema";
 import { BlockConfig } from "@blocknote/core";
@@ -38,6 +39,11 @@ type PresentationSource = PresentationSourceComponentReact | PresentationSourceB
  */
 interface PresentationSpec {
   meta: PresentationSpecMeta;
+  /**
+   * Optional reference to the capability that provides this presentation.
+   * Used for bidirectional linking between capabilities and presentations.
+   */
+  capability?: CapabilityRef;
   policy?: {
     flags?: string[];
     pii?: string[];

package/dist/presentations/registry.d.ts

@@ -1,5 +1,5 @@
-import { PresentationSpec } from "./presentations.js";
 import { SpecContractRegistry } from "../registry.js";
+import { PresentationSpec } from "./presentations.js";
 
 //#region src/presentations/registry.d.ts
 /** In-memory registry for PresentationSpec. */

package/dist/registry.d.ts

@@ -1,6 +1,6 @@
-import { OwnerShipMeta } from "./ownership.js";
 import { GroupKeyFn, RegistryFilter } from "./registry-utils.js";
 import { ContractSpecType } from "./types.js";
+import { OwnerShipMeta } from "./ownership.js";
 
 //#region src/registry.d.ts
 interface AnySpecContract {

package/dist/serialization/index.d.ts

@@ -0,0 +1,3 @@
+import { SerializedDataViewSpec, SerializedEventSpec, SerializedFieldConfig, SerializedFormSpec, SerializedOperationSpec, SerializedPresentationSpec, SerializedSchemaModel } from "./types.js";
+import { serializeDataViewSpec, serializeEventSpec, serializeFormSpec, serializeOperationSpec, serializePresentationSpec, serializeSchemaModel } from "./serializers.js";
+export { SerializedDataViewSpec, SerializedEventSpec, SerializedFieldConfig, SerializedFormSpec, SerializedOperationSpec, SerializedPresentationSpec, SerializedSchemaModel, serializeDataViewSpec, serializeEventSpec, serializeFormSpec, serializeOperationSpec, serializePresentationSpec, serializeSchemaModel };

package/dist/serialization/index.js

@@ -0,0 +1,3 @@
+import { serializeDataViewSpec, serializeEventSpec, serializeFormSpec, serializeOperationSpec, serializePresentationSpec, serializeSchemaModel } from "./serializers.js";
+
+export { serializeDataViewSpec, serializeEventSpec, serializeFormSpec, serializeOperationSpec, serializePresentationSpec, serializeSchemaModel };

package/dist/serialization/serializers.d.ts

@@ -0,0 +1,40 @@
+import { ResourceRefDescriptor } from "../resources.js";
+import { AnyOperationSpec } from "../operations/operation.js";
+import { PresentationSpec } from "../presentations/presentations.js";
+import "../presentations/index.js";
+import { DataViewSpec } from "../data-views/spec.js";
+import "../data-views/index.js";
+import "../operations/index.js";
+import { FormSpec } from "../forms/forms.js";
+import "../forms/index.js";
+import { AnyEventSpec } from "../events.js";
+import { SerializedDataViewSpec, SerializedEventSpec, SerializedFormSpec, SerializedOperationSpec, SerializedPresentationSpec, SerializedSchemaModel } from "./types.js";
+import { AnySchemaModel } from "@contractspec/lib.schema";
+
+//#region src/serialization/serializers.d.ts
+/**
+ * Serialize a SchemaModel to a plain JSON object.
+ */
+declare function serializeSchemaModel(model: AnySchemaModel | ResourceRefDescriptor<boolean> | null | undefined): SerializedSchemaModel | null;
+/**
+ * Serialize an OperationSpec to a plain JSON object.
+ */
+declare function serializeOperationSpec(spec: AnyOperationSpec | null | undefined): SerializedOperationSpec | null;
+/**
+ * Serialize an EventSpec to a plain JSON object.
+ */
+declare function serializeEventSpec(spec: AnyEventSpec | null | undefined): SerializedEventSpec | null;
+/**
+ * Serialize a PresentationSpec to a plain JSON object.
+ */
+declare function serializePresentationSpec(spec: PresentationSpec | null | undefined): SerializedPresentationSpec | null;
+/**
+ * Serialize a DataViewSpec to a plain JSON object.
+ */
+declare function serializeDataViewSpec(spec: DataViewSpec | null | undefined): SerializedDataViewSpec | null;
+/**
+ * Serialize a FormSpec to a plain JSON object.
+ */
+declare function serializeFormSpec(spec: FormSpec | null | undefined): SerializedFormSpec | null;
+//#endregion
+export { serializeDataViewSpec, serializeEventSpec, serializeFormSpec, serializeOperationSpec, serializePresentationSpec, serializeSchemaModel };

package/dist/serialization/serializers.js

@@ -0,0 +1,148 @@
+//#region src/serialization/serializers.ts
+/**
+* Type guard to check if a value is a ResourceRefDescriptor.
+*/
+function isResourceRefDescriptor(value) {
+	return typeof value === "object" && value !== null && "kind" in value && value.kind === "resource_ref";
+}
+function getTypeName(type) {
+	if (!type) return "unknown";
+	if (typeof type === "string") return type;
+	if (typeof type === "object") {
+		if ("config" in type && type.config?.name) return type.config.name;
+		if ("name" in type && typeof type.name === "string") return type.name;
+	}
+	return "unknown";
+}
+/**
+* Serialize a SchemaModel to a plain JSON object.
+*/
+function serializeSchemaModel(model) {
+	if (!model) return null;
+	if (isResourceRefDescriptor(model)) return {
+		name: `ResourceRef<${model.graphQLType}>`,
+		description: `Reference to ${model.graphQLType} resource (${model.uriTemplate})`,
+		fields: {}
+	};
+	if ("config" in model && model.config) {
+		const config = model.config;
+		return {
+			name: config.name,
+			description: config.description,
+			fields: Object.fromEntries(Object.entries(config.fields).map(([key, field]) => [key, {
+				typeName: getTypeName(field.type),
+				isOptional: field.isOptional,
+				isArray: field.isArray
+			}]))
+		};
+	}
+	return {
+		name: "unknown",
+		fields: {}
+	};
+}
+/**
+* Serialize an OperationSpec to a plain JSON object.
+*/
+function serializeOperationSpec(spec) {
+	if (!spec) return null;
+	return {
+		meta: {
+			key: spec.meta.key,
+			version: spec.meta.version,
+			stability: spec.meta.stability,
+			owners: spec.meta.owners,
+			tags: spec.meta.tags,
+			description: spec.meta.description,
+			goal: spec.meta.goal,
+			context: spec.meta.context
+		},
+		io: {
+			input: serializeSchemaModel(spec.io.input),
+			output: serializeSchemaModel(spec.io.output)
+		},
+		policy: spec.policy ? { auth: spec.policy.auth } : void 0
+	};
+}
+/**
+* Serialize an EventSpec to a plain JSON object.
+*/
+function serializeEventSpec(spec) {
+	if (!spec) return null;
+	return {
+		meta: {
+			key: spec.meta.key,
+			version: spec.meta.version,
+			stability: spec.meta.stability,
+			owners: spec.meta.owners,
+			tags: spec.meta.tags,
+			description: spec.meta.description
+		},
+		payload: serializeSchemaModel(spec.payload)
+	};
+}
+/**
+* Serialize a PresentationSpec to a plain JSON object.
+*/
+function serializePresentationSpec(spec) {
+	if (!spec) return null;
+	return {
+		meta: {
+			key: spec.meta.key,
+			version: spec.meta.version,
+			stability: spec.meta.stability,
+			owners: spec.meta.owners,
+			tags: spec.meta.tags,
+			description: spec.meta.description,
+			goal: spec.meta.goal,
+			context: spec.meta.context
+		},
+		source: {
+			type: spec.source.type,
+			framework: spec.source.type === "component" ? spec.source.framework : void 0,
+			componentKey: spec.source.type === "component" ? spec.source.componentKey : void 0
+		},
+		targets: spec.targets
+	};
+}
+/**
+* Serialize a DataViewSpec to a plain JSON object.
+*/
+function serializeDataViewSpec(spec) {
+	if (!spec) return null;
+	return {
+		meta: {
+			key: spec.meta.key,
+			version: spec.meta.version,
+			stability: spec.meta.stability,
+			owners: spec.meta.owners,
+			tags: spec.meta.tags,
+			description: spec.meta.description,
+			title: spec.meta.title
+		},
+		source: spec.source,
+		view: spec.view
+	};
+}
+/**
+* Serialize a FormSpec to a plain JSON object.
+*/
+function serializeFormSpec(spec) {
+	if (!spec) return null;
+	return {
+		meta: {
+			key: spec.meta.key,
+			version: spec.meta.version,
+			stability: spec.meta.stability,
+			owners: spec.meta.owners,
+			tags: spec.meta.tags,
+			description: spec.meta.description,
+			title: spec.meta.title
+		},
+		fields: spec.fields,
+		actions: spec.actions
+	};
+}
+
+//#endregion
+export { serializeDataViewSpec, serializeEventSpec, serializeFormSpec, serializeOperationSpec, serializePresentationSpec, serializeSchemaModel };