@lssm/lib.contracts 0.0.0-canary-20251220041653 → 0.0.0-canary-20251221114240

package/dist/onboarding-base.d.ts

@@ -1,135 +1,135 @@
-import { ContractSpec } from "./spec.js";
-import * as _lssm_lib_schema7 from "@lssm/lib.schema";
+import { OperationSpec } from "./operation.js";
+import * as _lssm_lib_schema61 from "@lssm/lib.schema";
 import { SchemaModel } from "@lssm/lib.schema";
 
 //#region src/onboarding-base.d.ts
 /** Save/update onboarding draft (auto-save during flow) */
 declare const SaveOnboardingDraftInput: SchemaModel<{
   data: {
-    type: _lssm_lib_schema7.FieldType<unknown, unknown>;
+    type: _lssm_lib_schema61.FieldType<unknown, unknown>;
     isOptional: false;
   };
 }>;
 declare const SaveOnboardingDraftOutput: SchemaModel<{
   id: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema61.FieldType<string, string>;
     isOptional: false;
   };
   organizationId: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema61.FieldType<string, string>;
     isOptional: false;
   };
 }>;
-declare const SaveOnboardingDraftBaseSpec: ContractSpec<SchemaModel<{
+declare const SaveOnboardingDraftBaseSpec: OperationSpec<SchemaModel<{
   data: {
-    type: _lssm_lib_schema7.FieldType<unknown, unknown>;
+    type: _lssm_lib_schema61.FieldType<unknown, unknown>;
     isOptional: false;
   };
 }>, SchemaModel<{
   id: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema61.FieldType<string, string>;
     isOptional: false;
   };
   organizationId: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema61.FieldType<string, string>;
     isOptional: false;
   };
 }>, undefined>;
 /** Get current onboarding draft (on mount/restore) */
 declare const GetOnboardingDraftOutput: SchemaModel<{
   id: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema61.FieldType<string, string>;
     isOptional: true;
   };
   organizationId: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema61.FieldType<string, string>;
     isOptional: true;
   };
   data: {
-    type: _lssm_lib_schema7.FieldType<unknown, unknown>;
+    type: _lssm_lib_schema61.FieldType<unknown, unknown>;
     isOptional: true;
   };
   createdAt: {
-    type: _lssm_lib_schema7.FieldType<Date, string>;
+    type: _lssm_lib_schema61.FieldType<Date, string>;
     isOptional: true;
   };
   updatedAt: {
-    type: _lssm_lib_schema7.FieldType<Date, string>;
+    type: _lssm_lib_schema61.FieldType<Date, string>;
     isOptional: true;
   };
 }>;
-declare const GetOnboardingDraftBaseSpec: ContractSpec<_lssm_lib_schema7.AnySchemaModel, SchemaModel<{
+declare const GetOnboardingDraftBaseSpec: OperationSpec<_lssm_lib_schema61.AnySchemaModel, SchemaModel<{
   id: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema61.FieldType<string, string>;
     isOptional: true;
   };
   organizationId: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema61.FieldType<string, string>;
     isOptional: true;
   };
   data: {
-    type: _lssm_lib_schema7.FieldType<unknown, unknown>;
+    type: _lssm_lib_schema61.FieldType<unknown, unknown>;
     isOptional: true;
   };
   createdAt: {
-    type: _lssm_lib_schema7.FieldType<Date, string>;
+    type: _lssm_lib_schema61.FieldType<Date, string>;
     isOptional: true;
   };
   updatedAt: {
-    type: _lssm_lib_schema7.FieldType<Date, string>;
+    type: _lssm_lib_schema61.FieldType<Date, string>;
     isOptional: true;
   };
 }>, undefined>;
 /** Delete onboarding draft (cleanup after completion or cancel) */
 declare const DeleteOnboardingDraftOutput: SchemaModel<{
   ok: {
-    type: _lssm_lib_schema7.FieldType<boolean, boolean>;
+    type: _lssm_lib_schema61.FieldType<boolean, boolean>;
     isOptional: false;
   };
 }>;
-declare const DeleteOnboardingDraftBaseSpec: ContractSpec<_lssm_lib_schema7.AnySchemaModel, SchemaModel<{
+declare const DeleteOnboardingDraftBaseSpec: OperationSpec<_lssm_lib_schema61.AnySchemaModel, SchemaModel<{
   ok: {
-    type: _lssm_lib_schema7.FieldType<boolean, boolean>;
+    type: _lssm_lib_schema61.FieldType<boolean, boolean>;
     isOptional: false;
   };
 }>, undefined>;
 /** Complete onboarding (final submit, creates entities) */
 declare const CompleteOnboardingBaseInput: SchemaModel<{
   data: {
-    type: _lssm_lib_schema7.FieldType<unknown, unknown>;
+    type: _lssm_lib_schema61.FieldType<unknown, unknown>;
     isOptional: false;
   };
 }>;
 declare const CompleteOnboardingBaseOutput: SchemaModel<{
   success: {
-    type: _lssm_lib_schema7.FieldType<boolean, boolean>;
+    type: _lssm_lib_schema61.FieldType<boolean, boolean>;
     isOptional: false;
   };
   userId: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema61.FieldType<string, string>;
     isOptional: true;
   };
   organizationId: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema61.FieldType<string, string>;
     isOptional: true;
   };
 }>;
-declare const CompleteOnboardingBaseSpec: ContractSpec<SchemaModel<{
+declare const CompleteOnboardingBaseSpec: OperationSpec<SchemaModel<{
   data: {
-    type: _lssm_lib_schema7.FieldType<unknown, unknown>;
+    type: _lssm_lib_schema61.FieldType<unknown, unknown>;
     isOptional: false;
   };
 }>, SchemaModel<{
   success: {
-    type: _lssm_lib_schema7.FieldType<boolean, boolean>;
+    type: _lssm_lib_schema61.FieldType<boolean, boolean>;
     isOptional: false;
   };
   userId: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema61.FieldType<string, string>;
     isOptional: true;
   };
   organizationId: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema61.FieldType<string, string>;
     isOptional: true;
   };
 }>, undefined>;

package/dist/onboarding-base.js

@@ -1,5 +1,5 @@
 import { E5, x8 } from "./schema/dist/index.js";
-import { defineCommand, defineQuery } from "./spec.js";
+import { defineCommand, defineQuery } from "./operation.js";
 import { OwnersEnum, StabilityEnum } from "./ownership.js";
 
 //#region src/onboarding-base.ts

package/dist/openapi.d.ts

@@ -1,4 +1,4 @@
-import { SpecRegistry } from "./registry.js";
+import { OperationSpecRegistry } from "./registry.js";
 
 //#region src/openapi.d.ts
 
@@ -26,6 +26,6 @@ interface OpenApiDocument {
     schemas: Record<string, OpenApiSchemaObject>;
   };
 }
-declare function openApiForRegistry(registry: SpecRegistry, options?: OpenApiExportOptions): OpenApiDocument;
+declare function openApiForRegistry(registry: OperationSpecRegistry, options?: OpenApiExportOptions): OpenApiDocument;
 //#endregion
 export { OpenApiDocument, OpenApiExportOptions, OpenApiServer, openApiForRegistry };

package/dist/{spec.d.ts → operation.d.ts}

@@ -6,7 +6,7 @@ import { PolicyRef } from "./policy/spec.js";
 import { TestSpecRef } from "./tests/spec.js";
 import { AnySchemaModel } from "@lssm/lib.schema";
 
-//#region src/spec.d.ts
+//#region src/operation.d.ts
 
 /**
  * Distinguishes between state-changing operations (command) and read-only operations (query).
@@ -62,7 +62,7 @@ interface TelemetryTrigger {
  * @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 ContractSpec<Input extends AnySchemaModel, Output extends AnySchemaModel | ResourceRefDescriptor<boolean>, Events extends readonly EmitDecl[] | undefined = readonly EmitDecl[] | undefined> {
+interface OperationSpec<Input extends AnySchemaModel, Output extends AnySchemaModel | ResourceRefDescriptor<boolean>, Events extends readonly EmitDecl[] | undefined = readonly EmitDecl[] | undefined> {
   meta: {
     /** Fully-qualified op name (e.g., "sigil.beginSignup") */
     name: string;
@@ -174,22 +174,22 @@ interface ContractSpec<Input extends AnySchemaModel, Output extends AnySchemaMod
    */
   implementations?: ImplementationRef[];
 }
-type AnyContractSpec = ContractSpec<AnySchemaModel, AnySchemaModel | ResourceRefDescriptor<boolean>>;
+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<ContractSpec<I, O, E>, "meta" | "policy"> & {
-  meta: Omit<ContractSpec<I, O, E>["meta"], "kind">;
-  policy: Omit<ContractSpec<I, O, E>["policy"], "idempotent">;
-}) => ContractSpec<I, O, E>;
+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<ContractSpec<I, O, E>, "meta" | "policy"> & {
-  meta: Omit<ContractSpec<I, O, E>["meta"], "kind">;
-  policy: Omit<ContractSpec<I, O, E>["policy"], "idempotent">;
-}) => ContractSpec<I, O, E>;
+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 { AnyContractSpec, ContractSpec, EmitDecl, EmitDeclInline, EmitDeclRef, ImplementationRef, ImplementationType, OpKind, TelemetryTrigger, defineCommand, defineQuery, isEmitDeclRef };
+export { AnyOperationSpec, EmitDecl, EmitDeclInline, EmitDeclRef, ImplementationRef, ImplementationType, OpKind, OperationSpec, TelemetryTrigger, defineCommand, defineQuery, isEmitDeclRef };

package/dist/{spec.js → operation.js}

@@ -1,4 +1,4 @@
-//#region src/spec.ts
+//#region src/operation.ts
 const isEmitDeclRef = (e) => "ref" in e;
 /**
 * Helper to define a Command (write operation).

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

@@ -14,7 +14,7 @@ const tech_contracts_policy_DocBlocks = [{
 		"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 (`SpecRegistry` → `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: number }` → 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 }],\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 `SpecRegistry.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"
+	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: number }` → 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 }],\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);
 

package/dist/presentations.d.ts

@@ -1,6 +1,6 @@
 import { Stability } from "./ownership.js";
 import z from "zod";
-import * as _lssm_lib_schema89 from "@lssm/lib.schema";
+import * as _lssm_lib_schema234 from "@lssm/lib.schema";
 import { AnySchemaModel } from "@lssm/lib.schema";
 
 //#region src/presentations.d.ts
@@ -62,7 +62,7 @@ declare class PresentationRegistry {
 declare function jsonSchemaForPresentation(p: PresentationSpec): {
   framework: "react";
   componentKey: string;
-  props: z.core.ZodStandardJSONSchemaPayload<_lssm_lib_schema89.TopLevelZodFromModel<_lssm_lib_schema89.SchemaModelFieldsAnyConfig<AnySchemaModel | _lssm_lib_schema89.AnyFieldType | _lssm_lib_schema89.AnyEnumType>>>;
+  props: z.core.ZodStandardJSONSchemaPayload<_lssm_lib_schema234.TopLevelZodFromModel<_lssm_lib_schema234.SchemaModelFieldsAnyConfig<AnySchemaModel | _lssm_lib_schema234.AnyFieldType | _lssm_lib_schema234.AnyEnumType>>>;
   meta: {
     readonly name: string;
     readonly version: number;
@@ -84,7 +84,7 @@ declare function jsonSchemaForPresentation(p: PresentationSpec): {
   kind: PresentationKind;
 } | {
   mimeType: string;
-  model: z.core.ZodStandardJSONSchemaPayload<_lssm_lib_schema89.TopLevelZodFromModel<_lssm_lib_schema89.SchemaModelFieldsAnyConfig<AnySchemaModel | _lssm_lib_schema89.AnyFieldType | _lssm_lib_schema89.AnyEnumType>>>;
+  model: z.core.ZodStandardJSONSchemaPayload<_lssm_lib_schema234.TopLevelZodFromModel<_lssm_lib_schema234.SchemaModelFieldsAnyConfig<AnySchemaModel | _lssm_lib_schema234.AnyFieldType | _lssm_lib_schema234.AnyEnumType>>>;
   meta: {
     readonly name: string;
     readonly version: number;

package/dist/registry.d.ts

@@ -1,31 +1,30 @@
 import { defaultDocRegistry, docId, registerDocBlocks } from "./docs/registry.js";
 import { ResourceRefDescriptor } from "./resources.js";
-import { ContractSpec } from "./spec.js";
+import { AnyOperationSpec, OperationSpec } from "./operation.js";
 import { HandlerCtx } from "./types.js";
-import { HandlerFor } from "./install.js";
+import { HandlerForOperationSpec } from "./install.js";
 import { AnySchemaModel } from "@lssm/lib.schema";
 
 //#region src/registry.d.ts
 
 type OperationKey = `${string}.v${number}`;
 declare function opKey(name: string, version: number): OperationKey;
-type AnySpec = ContractSpec<AnySchemaModel, AnySchemaModel | ResourceRefDescriptor<boolean>>;
-type AnyHandler = (args: unknown, ctx: HandlerCtx) => Promise<unknown>;
+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 SpecRegistry {
+declare class OperationSpecRegistry {
   private specs;
   private handlers;
   /**
-   * Registers a ContractSpec definition.
+   * 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: ContractSpec<I, O>): this;
+  register<I extends AnySchemaModel, O extends AnySchemaModel | ResourceRefDescriptor<boolean>>(spec: OperationSpec<I, O>): this;
   /**
    * Binds a runtime handler implementation to a previously registered spec.
    *
@@ -34,7 +33,7 @@ declare class SpecRegistry {
    * @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: ContractSpec<I, O>, handler: HandlerFor<ContractSpec<I, O>>): this;
+  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.
@@ -42,17 +41,17 @@ declare class SpecRegistry {
    * @param name - Operation name.
    * @param version - (Optional) Specific version.
    */
-  getSpec(name: string, version?: number): AnySpec | undefined;
+  getSpec(name: string, version?: number): AnyOperationSpec | undefined;
   /**
    * Retrieves the bound handler for a spec.
    */
-  getHandler(name: string, version?: number): AnyHandler | undefined;
+  getHandler(name: string, version?: number): AnyOperationHandler | undefined;
   /** Iterate all registered specs. */
-  listSpecs(): AnySpec[];
+  listSpecs(): AnyOperationSpec[];
   /** Iterate all bound operations (spec+handler). */
   listBound(): {
-    spec: AnySpec;
-    handler: AnyHandler;
+    spec: AnyOperationSpec;
+    handler: AnyOperationHandler;
   }[];
   /**
    * Execute an operation by name/version with full runtime protections:
@@ -70,4 +69,4 @@ declare class SpecRegistry {
   execute(name: string, version: number | undefined, rawInput: unknown, ctx: HandlerCtx): Promise<unknown>;
 }
 //#endregion
-export { OperationKey, SpecRegistry, defaultDocRegistry, docId, opKey, registerDocBlocks };
+export { OperationKey, OperationSpecRegistry, defaultDocRegistry, docId, opKey, registerDocBlocks };

package/dist/registry.js

@@ -1,10 +1,10 @@
 import { eventKey } from "./events.js";
-import { isEmitDeclRef } from "./spec.js";
+import { isEmitDeclRef } from "./operation.js";
 import { defaultDocRegistry, docId, registerDocBlocks } from "./docs/registry.js";
 
 //#region src/registry.ts
 /**
-* SpecRegistry:
+* OperationSpecRegistry:
 * - Registers ContractSpecs (unique by name+version)
 * - Binds runtime handlers to specs
 * - Provides lookup, iteration, and a safe execute() with validation/policy/enforcement
@@ -18,11 +18,11 @@ function opKey(name, version) {
 * In-memory registry for ContractSpecs and their bound handlers.
 * Provides validation, policy enforcement, and guarded event emission at execute time.
 */
-var SpecRegistry = class {
+var OperationSpecRegistry = class {
 	specs = /* @__PURE__ */ new Map();
 	handlers = /* @__PURE__ */ new Map();
 	/**
-	* Registers a ContractSpec definition.
+	* Registers a OperationSpec definition.
 	*
 	* @param spec - The contract specification to register.
 	* @returns The registry instance for chaining.
@@ -206,4 +206,4 @@ var SpecRegistry = class {
 };
 
 //#endregion
-export { SpecRegistry, defaultDocRegistry, docId, opKey, registerDocBlocks };
+export { OperationSpecRegistry, defaultDocRegistry, docId, opKey, registerDocBlocks };

package/dist/server/graphql-pothos.d.ts

@@ -1,5 +1,5 @@
 import { ResourceRegistry } from "../resources.js";
-import { SpecRegistry } from "../registry.js";
+import { OperationSpecRegistry } from "../registry.js";
 import "@pothos/plugin-prisma";
 import "@pothos/plugin-complexity";
 import "@pothos/plugin-relay";
@@ -10,22 +10,22 @@ import { SchemaTypes } from "@pothos/core";
 //#region src/server/graphql-pothos.d.ts
 
 /**
- * Registers all ContractSpecs from a SpecRegistry onto a Pothos SchemaBuilder.
+ * Registers all ContractSpecs from a OperationSpecRegistry onto a Pothos SchemaBuilder.
  *
  * This adapter:
  * 1. Discovers output types from specs and registers them as Pothos object types.
- * 2. Maps `ContractSpec` inputs to Pothos input types.
+ * 2. Maps `ContractSpec` (OperationSpec) inputs to Pothos input types.
  * 3. Mounts `query` specs as `Query` fields and `command` specs as `Mutation` fields.
  * 4. Wraps the resolver to:
  *    - Enforce auth policies (basic check).
  *    - Build a `HandlerCtx`.
- *    - Execute via `SpecRegistry`.
+ *    - Execute via `OperationSpecRegistry`.
  *    - Hydrate resource references if applicable.
  *
  * @param builder - The Pothos SchemaBuilder instance.
- * @param reg - The SpecRegistry containing operations.
+ * @param reg - The OperationSpecRegistry containing operations.
  * @param resources - (Optional) ResourceRegistry for hydrating resource references.
  */
-declare function registerContractsOnBuilder<T extends SchemaTypes>(builder: PothosSchemaTypes.SchemaBuilder<T>, reg: SpecRegistry, resources?: ResourceRegistry): void;
+declare function registerContractsOnBuilder<T extends SchemaTypes>(builder: PothosSchemaTypes.SchemaBuilder<T>, reg: OperationSpecRegistry, resources?: ResourceRegistry): void;
 //#endregion
 export { registerContractsOnBuilder };

package/dist/server/graphql-pothos.js

@@ -9,20 +9,20 @@ import "@pothos/plugin-tracing";
 
 //#region src/server/graphql-pothos.ts
 /**
-* Registers all ContractSpecs from a SpecRegistry onto a Pothos SchemaBuilder.
+* Registers all ContractSpecs from a OperationSpecRegistry onto a Pothos SchemaBuilder.
 *
 * This adapter:
 * 1. Discovers output types from specs and registers them as Pothos object types.
-* 2. Maps `ContractSpec` inputs to Pothos input types.
+* 2. Maps `ContractSpec` (OperationSpec) inputs to Pothos input types.
 * 3. Mounts `query` specs as `Query` fields and `command` specs as `Mutation` fields.
 * 4. Wraps the resolver to:
 *    - Enforce auth policies (basic check).
 *    - Build a `HandlerCtx`.
-*    - Execute via `SpecRegistry`.
+*    - Execute via `OperationSpecRegistry`.
 *    - Hydrate resource references if applicable.
 *
 * @param builder - The Pothos SchemaBuilder instance.
-* @param reg - The SpecRegistry containing operations.
+* @param reg - The OperationSpecRegistry containing operations.
 * @param resources - (Optional) ResourceRegistry for hydrating resource references.
 */
 function registerContractsOnBuilder(builder, reg, resources) {

package/dist/server/mcp/createMcpServer.d.ts

@@ -1,5 +1,5 @@
 import { ResourceRegistry } from "../../resources.js";
-import { SpecRegistry } from "../../registry.js";
+import { OperationSpecRegistry } from "../../registry.js";
 import { PromptRegistry } from "../../promptRegistry.js";
 import { McpCtxFactories } from "./mcpTypes.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -9,7 +9,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 /**
  * Creates a unified Model Context Protocol (MCP) server exposing operations, resources, prompts,
  * and (optionally) presentations.\n+ *
- * ContractSpec exposes:\n+ * - Tools: `command` operations from `SpecRegistry`.\n+ * - Resources: templates from `ResourceRegistry`.\n+ * - Prompts: templates from `PromptRegistry`.\n+ * - Presentations: V1 registry and/or V2 descriptors as read-only resources.\n+ */
-declare function createMcpServer(server: McpServer, ops: SpecRegistry, resources: ResourceRegistry, prompts: PromptRegistry, ctxFactories: McpCtxFactories): McpServer;
+ * ContractSpec exposes:\n+ * - Tools: `command` operations from `OperationSpecRegistry`.\n+ * - Resources: templates from `ResourceRegistry`.\n+ * - Prompts: templates from `PromptRegistry`.\n+ * - Presentations: V1 registry and/or V2 descriptors as read-only resources.\n+ */
+declare function createMcpServer(server: McpServer, ops: OperationSpecRegistry, resources: ResourceRegistry, prompts: PromptRegistry, ctxFactories: McpCtxFactories): McpServer;
 //#endregion
 export { createMcpServer };

package/dist/server/mcp/createMcpServer.js

@@ -7,7 +7,7 @@ import { registerMcpPresentations } from "./registerPresentations.js";
 /**
 * Creates a unified Model Context Protocol (MCP) server exposing operations, resources, prompts,
 * and (optionally) presentations.\n+ *
-* ContractSpec exposes:\n+ * - Tools: `command` operations from `SpecRegistry`.\n+ * - Resources: templates from `ResourceRegistry`.\n+ * - Prompts: templates from `PromptRegistry`.\n+ * - Presentations: V1 registry and/or V2 descriptors as read-only resources.\n+ */
+* ContractSpec exposes:\n+ * - Tools: `command` operations from `OperationSpecRegistry`.\n+ * - Resources: templates from `ResourceRegistry`.\n+ * - Prompts: templates from `PromptRegistry`.\n+ * - Presentations: V1 registry and/or V2 descriptors as read-only resources.\n+ */
 function createMcpServer(server, ops, resources, prompts, ctxFactories) {
 	ctxFactories.logger.info("Creating MCP server");
 	registerMcpTools(server, ops, { toolCtx: ctxFactories.toolCtx });

package/dist/server/mcp/registerTools.d.ts

@@ -1,8 +1,8 @@
-import { SpecRegistry } from "../../registry.js";
+import { OperationSpecRegistry } from "../../registry.js";
 import { McpCtxFactories } from "./mcpTypes.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 //#region src/server/mcp/registerTools.d.ts
-declare function registerMcpTools(server: McpServer, ops: SpecRegistry, ctx: Pick<McpCtxFactories, 'toolCtx'>): void;
+declare function registerMcpTools(server: McpServer, ops: OperationSpecRegistry, ctx: Pick<McpCtxFactories, 'toolCtx'>): void;
 //#endregion
 export { registerMcpTools };

package/dist/server/rest-elysia.d.ts

@@ -1,11 +1,11 @@
 import { HandlerCtx } from "../types.js";
-import { SpecRegistry } from "../registry.js";
+import { OperationSpecRegistry } from "../registry.js";
 import { RestOptions } from "./rest-generic.js";
 import { Elysia } from "elysia";
 
 //#region src/server/rest-elysia.d.ts
 /** Mount routes on an Elysia instance */
-declare function elysiaPlugin(app: Elysia, reg: SpecRegistry, ctxFactory: (c: {
+declare function elysiaPlugin(app: Elysia, reg: OperationSpecRegistry, ctxFactory: (c: {
   request: Request;
   store: unknown;
 }) => HandlerCtx, options?: RestOptions): Elysia<"", {

package/dist/server/rest-express.d.ts

@@ -1,5 +1,5 @@
 import { HandlerCtx } from "../types.js";
-import { SpecRegistry } from "../registry.js";
+import { OperationSpecRegistry } from "../registry.js";
 import { RestOptions } from "./rest-generic.js";
 import { Request, Router } from "express";
 
@@ -11,6 +11,6 @@ import { Request, Router } from "express";
  */
 declare function expressRouter(express: {
   Router: () => Router;
-}, reg: SpecRegistry, ctxFactory: (req: Request) => HandlerCtx, options?: RestOptions): Router;
+}, reg: OperationSpecRegistry, ctxFactory: (req: Request) => HandlerCtx, options?: RestOptions): Router;
 //#endregion
 export { expressRouter };

package/dist/server/rest-generic.d.ts

@@ -1,5 +1,5 @@
 import { HandlerCtx } from "../types.js";
-import { SpecRegistry } from "../registry.js";
+import { OperationSpecRegistry } from "../registry.js";
 
 //#region src/server/rest-generic.d.ts
 interface RestOptions {
@@ -23,10 +23,10 @@ interface RestOptions {
 }
 /**
  * Build a single Fetch-style handler: (req) => Response
- * - Discovers routes from SpecRegistry
+ * - Discovers routes from OperationSpecRegistry
  * - Validates with zod via registry.execute()
  * - Handles CORS (optional)
  */
-declare function createFetchHandler(reg: SpecRegistry, ctxFactory: (req: Request) => HandlerCtx, options?: RestOptions): (req: Request) => Promise<Response>;
+declare function createFetchHandler(reg: OperationSpecRegistry, ctxFactory: (req: Request) => HandlerCtx, options?: RestOptions): (req: Request) => Promise<Response>;
 //#endregion
 export { RestOptions, createFetchHandler };

package/dist/server/rest-generic.js

@@ -22,7 +22,7 @@ function joinPath(a, b) {
 }
 /**
 * Build a single Fetch-style handler: (req) => Response
-* - Discovers routes from SpecRegistry
+* - Discovers routes from OperationSpecRegistry
 * - Validates with zod via registry.execute()
 * - Handles CORS (optional)
 */

package/dist/server/rest-next-app.d.ts

@@ -1,5 +1,5 @@
 import { HandlerCtx } from "../types.js";
-import { SpecRegistry } from "../registry.js";
+import { OperationSpecRegistry } from "../registry.js";
 import { RestOptions } from "./rest-generic.js";
 
 //#region src/server/rest-next-app.d.ts
@@ -12,10 +12,10 @@ import { RestOptions } from "./rest-generic.js";
  * - Path parsing to determine the operation name and version.
  * - Body parsing (JSON).
  * - Context creation via `ctxFactory`.
- * - Execution via `SpecRegistry`.
+ * - Execution via `OperationSpecRegistry`.
  * - Response formatting (JSON success/error).
  *
- * @param reg - The SpecRegistry containing the operations.
+ * @param reg - The OperationSpecRegistry containing the operations.
  * @param ctxFactory - A factory function to build the `HandlerCtx` (e.g., auth, tenant) from the request.
  * @param options - Optional configuration for the REST handler.
  * @returns A function `(req: Request) => Promise<Response>`.
@@ -30,6 +30,6 @@ import { RestOptions } from "./rest-generic.js";
  * export { handler as GET, handler as POST };
  * ```
  */
-declare function makeNextAppHandler(reg: SpecRegistry, ctxFactory: (req: Request) => HandlerCtx, options?: RestOptions): (req: Request) => Promise<Response>;
+declare function makeNextAppHandler(reg: OperationSpecRegistry, ctxFactory: (req: Request) => HandlerCtx, options?: RestOptions): (req: Request) => Promise<Response>;
 //#endregion
 export { makeNextAppHandler };

package/dist/server/rest-next-app.js

@@ -9,10 +9,10 @@ import { createFetchHandler } from "./rest-generic.js";
 * - Path parsing to determine the operation name and version.
 * - Body parsing (JSON).
 * - Context creation via `ctxFactory`.
-* - Execution via `SpecRegistry`.
+* - Execution via `OperationSpecRegistry`.
 * - Response formatting (JSON success/error).
 *
-* @param reg - The SpecRegistry containing the operations.
+* @param reg - The OperationSpecRegistry containing the operations.
 * @param ctxFactory - A factory function to build the `HandlerCtx` (e.g., auth, tenant) from the request.
 * @param options - Optional configuration for the REST handler.
 * @returns A function `(req: Request) => Promise<Response>`.