@contractspec/lib.contracts 0.0.0-canary-20260113162409

package/dist/operations/index.d.ts

@@ -0,0 +1,3 @@
+import { AnyOperationSpec, EmitDecl, EmitDeclInline, EmitDeclRef, ImplementationRef, ImplementationType, OpKind, OperationSpec, OperationSpecMeta, TelemetryTrigger, defineCommand, defineQuery, isEmitDeclRef } from "./operation.js";
+import { OperationKey, OperationSpecRegistry, opKey } from "./registry.js";
+export { AnyOperationSpec, EmitDecl, EmitDeclInline, EmitDeclRef, ImplementationRef, ImplementationType, OpKind, OperationKey, OperationSpec, OperationSpecMeta, OperationSpecRegistry, TelemetryTrigger, defineCommand, defineQuery, isEmitDeclRef, opKey };

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 { TestSpecRef } from "../tests/spec.js";
+import { EventSpec } from "../events.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: string;
+  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?: string;
+  };
+  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,54 @@
+import { ResourceRefDescriptor } from "../resources.js";
+import { AnyOperationSpec, OperationSpec } from "./operation.js";
+import { HandlerForOperationSpec } from "../install.js";
+import { HandlerCtx } from "../types.js";
+import { SpecContractRegistry } from "../registry.js";
+import { AnySchemaModel } from "@contractspec/lib.schema";
+
+//#region src/operations/registry.d.ts
+
+type OperationKey = `${string}.v${string}`;
+declare function opKey(key: string, version: string): 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 extends SpecContractRegistry<'operation', AnyOperationSpec> {
+  private handlers;
+  constructor(items?: AnyOperationSpec[]);
+  /**
+   * 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 the bound handler for a spec.
+   */
+  getHandler(key: string, version?: string): AnyOperationHandler | undefined;
+  /** Iterate all bound operations (spec+handler). */
+  listBound(): {
+    spec: AnyOperationSpec;
+    handler: AnyOperationHandler;
+  }[];
+  /**
+   * 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: string | undefined, rawInput: unknown, ctx: HandlerCtx): Promise<unknown>;
+}
+//#endregion
+export { OperationKey, OperationSpecRegistry, opKey };

package/dist/operations/registry.js

@@ -0,0 +1,176 @@
+import { SpecContractRegistry } from "../registry.js";
+import { eventKey } from "../events.js";
+import { isEmitDeclRef } from "./operation.js";
+
+//#region src/operations/registry.ts
+/**
+* OperationSpecRegistry:
+* - Registers ContractSpecs (unique by name+version)
+* - Binds runtime handlers to specs
+* - Provides lookup, iteration, and a safe execute() with validation/policy/enforcement
+*
+* Includes a minimal OpRegistry shim for backward-compat (deprecated).
+*/
+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 extends SpecContractRegistry {
+	handlers = /* @__PURE__ */ new Map();
+	constructor(items) {
+		super("operation", items);
+	}
+	/**
+	* 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.items.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 the bound handler for a spec.
+	*/
+	getHandler(key, version) {
+		const spec = this.get(key, version);
+		if (!spec) return void 0;
+		return this.handlers.get(opKey(spec.meta.key, spec.meta.version));
+	}
+	/** Iterate all bound operations (spec+handler). */
+	listBound() {
+		const out = [];
+		for (const [k, spec] of this.items.entries()) {
+			const h = this.handlers.get(k);
+			if (h) out.push({
+				spec,
+				handler: h
+			});
+		}
+		return out;
+	}
+	/**
+	* 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.get(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.0.0", 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: string;
+  /** 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 };

package/dist/ownership.js

@@ -0,0 +1,38 @@
+//#region src/ownership.ts
+const StabilityEnum = {
+	Idea: "idea",
+	InCreation: "in_creation",
+	Experimental: "experimental",
+	Beta: "beta",
+	Stable: "stable",
+	Deprecated: "deprecated"
+};
+const OwnersEnum = {
+	PlatformCore: "platform.core",
+	PlatformSigil: "platform.sigil",
+	PlatformMarketplace: "platform.marketplace",
+	PlatformMessaging: "platform.messaging",
+	PlatformContent: "platform.content",
+	PlatformFeatureFlags: "platform.featureflags",
+	PlatformFinance: "platform.finance"
+};
+const Owners = OwnersEnum;
+const TagsEnum = {
+	Spots: "spots",
+	Collectivity: "collectivity",
+	Marketplace: "marketplace",
+	Sellers: "sellers",
+	Auth: "auth",
+	Login: "login",
+	Signup: "signup",
+	Guide: "guide",
+	Docs: "docs",
+	I18n: "i18n",
+	Incident: "incident",
+	Automation: "automation",
+	Hygiene: "hygiene"
+};
+const Tags = TagsEnum;
+
+//#endregion
+export { Owners, OwnersEnum, StabilityEnum, Tags, TagsEnum };

package/dist/policy/docs/policy.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/policy/docs/policy.docblock.d.ts
+declare const tech_contracts_policy_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_policy_DocBlocks };

package/dist/policy/docs/policy.docblock.js

@@ -0,0 +1,21 @@
+import { registerDocBlocks } from "../../docs/registry.js";
+
+//#region src/policy/docs/policy.docblock.ts
+const tech_contracts_policy_DocBlocks = [{
+	id: "docs.tech.contracts.policy",
+	title: "PolicySpec & PolicyEngine",
+	summary: "`PolicySpec` gives a declarative, typed home for access-control logic covering:",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/policy",
+	tags: [
+		"tech",
+		"contracts",
+		"policy"
+	],
+	body: "# PolicySpec & PolicyEngine\n\n## Purpose\n\n`PolicySpec` gives a declarative, typed home for access-control logic covering:\n- **Who** can perform an action (ABAC/ReBAC style rules)\n- **What** they can access (resources + optional field-level overrides)\n- **When** special conditions apply (contextual expressions)\n- **How** PII should be handled (consent/retention hints)\n\n`PolicyEngine` evaluates one or more policies and returns an `allow`/`deny` decision, field-level outcomes, and PII metadata suitable for downstream enforcement (`OperationSpecRegistry` → `ctx.decide`).\n\n## Location\n\n- Types & registry: `packages/libs/contracts/src/policy/spec.ts`\n- Runtime evaluation: `packages/libs/contracts/src/policy/engine.ts`\n- Tests: `packages/.../policy/engine.test.ts`\n\n## `PolicySpec`\n\n```ts\nexport interface PolicySpec {\n  meta: PolicyMeta;          // ownership metadata + { name, version, scope? }\n  rules: PolicyRule[];       // allow/deny rules for actions\n  fieldPolicies?: FieldPolicyRule[];\n  pii?: { fields: string[]; consentRequired?: boolean; retentionDays?: number };\n  relationships?: RelationshipDefinition[];\n  consents?: ConsentDefinition[];\n  rateLimits?: RateLimitDefinition[];\n  opa?: { package: string; decision?: string };\n}\n```\n\n- `PolicyRule`\n  - `effect`: `'allow' | 'deny'`\n  - `actions`: e.g., `['read', 'write', 'delete']` (string namespace is flexible)\n  - `subject`: `{ roles?: string[]; attributes?: { attr: matcher } }`\n  - `resource`: `{ type: string; fields?: string[]; attributes?: {...} }`\n  - `relationships`: `{ relation, objectId?, objectType? }[]` → ReBAC checks (use `objectId: '$resource'` to target the current resource)\n  - `requiresConsent`: `['consent_id']` → references spec-level consent definitions\n  - `flags`: feature flags that must be enabled (`DecisionContext.flags`)\n  - `rateLimit`: string reference to `rateLimits` entry or inline object `{ rpm, key?, windowSeconds?, burst? }`\n  - `escalate`: `'human_review' | null` to indicate manual approval\n  - `conditions`: optional expression snippets evaluated against `{ subject, resource, context }`\n- `FieldPolicyRule`\n  - `field`: dot-path string (e.g., `contact.email`)\n  - `actions`: subset of `['read', 'write']`\n  - Same `subject` / `resource` / `conditions` shape\n  - Useful for redacting specific fields, even when the global action is allowed\n- `RelationshipDefinition`\n  - Canonical tuples for relationship graph (`subjectType`, `relation`, `objectType`, `transitive?`)\n- `ConsentDefinition`\n  - `{ id, scope, purpose, lawfulBasis?, expiresInDays?, required? }`\n- `RateLimitDefinition`\n  - `{ id, rpm, key?, windowSeconds?, burst? }`\n- `PolicyRef`\n  - `{ name: string; version: string }` → attach to contract specs / workflows\n\n## Registry\n\n```ts\nconst registry = new PolicyRegistry();\nregistry.register(CorePolicySpec);\nconst spec = registry.get('core.default', 1);\n```\n\nGuarantees uniqueness per `(name, version)` and exposes helpers to resolve highest versions.\n\n## Engine\n\n```ts\nconst engine = new PolicyEngine(policyRegistry);\n\nconst decision = engine.decide({\n  action: 'read',\n  subject: { roles: ['admin'] },\n  resource: { type: 'resident', fields: ['contact.email'] },\n  policies: [{ name: 'core.default', version: '1.0.0' }],\n});\n/*\n{\n  effect: 'allow',\n  reason: 'core.default',\n  fieldDecisions: [{ field: 'contact.email', effect: 'allow' }],\n  pii: { fields: ['contact.email'], consentRequired: true }\n}\n*/\n```\n\n- First matching **deny** wins; otherwise the first **allow** is returned.\n- Field policies are aggregated across referenced policies:\n  - Later denies override earlier allows for a given field.\n  - Returned as `fieldDecisions` to simplify downstream masking.\n- PII metadata is surfaced when defined to help adapt logging/telemetry.\n\n### Expression Support\n\nConditions accept small JS snippets (e.g., `subject.attributes.orgId === context.orgId`). The engine runs them in a constrained scope (`subject`, `resource`, `context`) without access to global state.\n\n### ReBAC & Relationships\n\n- Provide relationship tuples via `PolicySpec.relationships` for documentation/validation.\n- Reference them inside rules with `relationships: [{ relation: 'manager_of', objectType: 'resident', objectId: '$resource' }]`.\n- The execution context must populate `subject.relationships` (`[{ relation, object, objectType }]`) for the engine to evaluate ReBAC guards.\n\n### Consent & Rate Limits\n\n- Declare reusable consent definitions under `consents`. Rules list the IDs they require; if a user session lacks the consent (`DecisionContext.consents`), the engine returns `effect: 'deny'` with `reason: 'consent_required'` and enumerates missing consents.\n- Attach rate limits either inline or via `rateLimits` references. When a rule matches, the engine surfaces `{ rpm, key, windowSeconds?, burst? }` so callers can feed it to shared limiters.\n\n### OPA Adapter\n\n- `OPAPolicyAdapter` bridges engine decisions to Open Policy Agent (OPA). It forwards the evaluation context + policies to OPA and merges any override result (`effect`, `reason`, `fieldDecisions`, `requiredConsents`).\n- Use when migrating to OPA policies or running defense-in-depth: call `engine.decide()`, then pass the preliminary decision to `adapter.evaluate(...)`. The adapter marks merged decisions with `evaluatedBy: 'opa'`.\n- OPA inputs include meta, rules, relationships, rate limits, and consent catalogs to simplify policy authoring on the OPA side.\n\n## Contract Integration\n\n`ContractSpec.policy` now supports:\n\n```ts\npolicy: {\n  auth: 'anonymous' | 'user' | 'admin';\n  ...\n  policies?: PolicyRef[];                // policies evaluated before execution\n  fieldPolicies?: {                      // field hints (read/write) per policy\n    field: string;\n    actions: ('read' | 'write')[];\n    policy?: PolicyRef;\n  }[];\n}\n```\n\nAdapters can resolve refs through a shared `PolicyEngine` and populate `ctx.decide` so `OperationSpecRegistry.execute` benefits from centralized enforcement.\n\n## Authoring Guidelines\n\n1. Prefer **allow-by-default** policies but explicitly deny sensitive flows (defense-in-depth).\n2. Keep rule scopes narrow (per feature/operation) and compose multiple `PolicyRef`s when necessary.\n3. Store PII field lists here to avoid duplication across logs/telemetry.\n4. Use explicit rule reasons for auditability and better developer feedback.\n5. Treat versioning seriously; bump `meta.version` whenever behavior changes.\n\n## Future Enhancements\n\n- Richer expression language (composable predicates, time-based conditions).\n- Multi-tenant relationship graph services (store/resolve relationships at scale).\n- Tooling that auto-generates docs/tests for policies referenced in specs.\n\n"
+}];
+registerDocBlocks(tech_contracts_policy_DocBlocks);
+
+//#endregion
+export { tech_contracts_policy_DocBlocks };

package/dist/policy/engine.d.ts

@@ -0,0 +1,40 @@
+import { PolicyRef } from "./spec.js";
+import { PolicyRegistry } from "./registry.js";
+import { PolicyDecision } from "../types.js";
+
+//#region src/policy/engine.d.ts
+interface SubjectRelationship {
+  relation: string;
+  object: string;
+  objectType?: string;
+}
+interface SubjectContext {
+  roles?: string[];
+  attributes?: Record<string, unknown>;
+  relationships?: SubjectRelationship[];
+}
+interface ResourceContext {
+  type: string;
+  id?: string;
+  fields?: string[];
+  attributes?: Record<string, unknown>;
+}
+interface DecisionContext {
+  subject: SubjectContext;
+  resource: ResourceContext;
+  context?: Record<string, unknown>;
+  action: string;
+  policies: PolicyRef[];
+  consents?: string[];
+  flags?: string[];
+}
+declare class PolicyEngine {
+  private readonly registry;
+  constructor(registry: PolicyRegistry);
+  decide(input: DecisionContext): PolicyDecision;
+  private resolvePolicies;
+  private matchRuleSet;
+  private evaluateFields;
+}
+//#endregion
+export { DecisionContext, PolicyEngine, ResourceContext, SubjectContext, SubjectRelationship };