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

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_schema206 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_schema206.FieldType<unknown, unknown>;
     isOptional: false;
   };
 }>;
 declare const SaveOnboardingDraftOutput: SchemaModel<{
   id: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema206.FieldType<string, string>;
     isOptional: false;
   };
   organizationId: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema206.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_schema206.FieldType<unknown, unknown>;
     isOptional: false;
   };
 }>, SchemaModel<{
   id: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema206.FieldType<string, string>;
     isOptional: false;
   };
   organizationId: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema206.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_schema206.FieldType<string, string>;
     isOptional: true;
   };
   organizationId: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema206.FieldType<string, string>;
     isOptional: true;
   };
   data: {
-    type: _lssm_lib_schema7.FieldType<unknown, unknown>;
+    type: _lssm_lib_schema206.FieldType<unknown, unknown>;
     isOptional: true;
   };
   createdAt: {
-    type: _lssm_lib_schema7.FieldType<Date, string>;
+    type: _lssm_lib_schema206.FieldType<Date, string>;
     isOptional: true;
   };
   updatedAt: {
-    type: _lssm_lib_schema7.FieldType<Date, string>;
+    type: _lssm_lib_schema206.FieldType<Date, string>;
     isOptional: true;
   };
 }>;
-declare const GetOnboardingDraftBaseSpec: ContractSpec<_lssm_lib_schema7.AnySchemaModel, SchemaModel<{
+declare const GetOnboardingDraftBaseSpec: OperationSpec<_lssm_lib_schema206.AnySchemaModel, SchemaModel<{
   id: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema206.FieldType<string, string>;
     isOptional: true;
   };
   organizationId: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema206.FieldType<string, string>;
     isOptional: true;
   };
   data: {
-    type: _lssm_lib_schema7.FieldType<unknown, unknown>;
+    type: _lssm_lib_schema206.FieldType<unknown, unknown>;
     isOptional: true;
   };
   createdAt: {
-    type: _lssm_lib_schema7.FieldType<Date, string>;
+    type: _lssm_lib_schema206.FieldType<Date, string>;
     isOptional: true;
   };
   updatedAt: {
-    type: _lssm_lib_schema7.FieldType<Date, string>;
+    type: _lssm_lib_schema206.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_schema206.FieldType<boolean, boolean>;
     isOptional: false;
   };
 }>;
-declare const DeleteOnboardingDraftBaseSpec: ContractSpec<_lssm_lib_schema7.AnySchemaModel, SchemaModel<{
+declare const DeleteOnboardingDraftBaseSpec: OperationSpec<_lssm_lib_schema206.AnySchemaModel, SchemaModel<{
   ok: {
-    type: _lssm_lib_schema7.FieldType<boolean, boolean>;
+    type: _lssm_lib_schema206.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_schema206.FieldType<unknown, unknown>;
     isOptional: false;
   };
 }>;
 declare const CompleteOnboardingBaseOutput: SchemaModel<{
   success: {
-    type: _lssm_lib_schema7.FieldType<boolean, boolean>;
+    type: _lssm_lib_schema206.FieldType<boolean, boolean>;
     isOptional: false;
   };
   userId: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema206.FieldType<string, string>;
     isOptional: true;
   };
   organizationId: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema206.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_schema206.FieldType<unknown, unknown>;
     isOptional: false;
   };
 }>, SchemaModel<{
   success: {
-    type: _lssm_lib_schema7.FieldType<boolean, boolean>;
+    type: _lssm_lib_schema206.FieldType<boolean, boolean>;
     isOptional: false;
   };
   userId: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema206.FieldType<string, string>;
     isOptional: true;
   };
   organizationId: {
-    type: _lssm_lib_schema7.FieldType<string, string>;
+    type: _lssm_lib_schema206.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,7 @@
 import { Stability } from "./ownership.js";
+import { GroupKeyFn, RegistryFilter } from "./registry-utils.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
@@ -58,11 +59,21 @@ declare class PresentationRegistry {
   register(p: PresentationSpec): this;
   list(): PresentationSpec[];
   get(name: string, version?: number): PresentationSpec | undefined;
+  /** Filter presentations by criteria. */
+  filter(criteria: RegistryFilter): PresentationSpec[];
+  /** List presentations with specific tag. */
+  listByTag(tag: string): PresentationSpec[];
+  /** List presentations by owner. */
+  listByOwner(owner: string): PresentationSpec[];
+  /** Group presentations by key function. */
+  groupBy(keyFn: GroupKeyFn<PresentationSpec>): Map<string, PresentationSpec[]>;
+  /** Get unique tags from all presentations. */
+  getUniqueTags(): string[];
 }
 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<_lssm_lib_schema234.AnyFieldType | _lssm_lib_schema234.AnyEnumType | AnySchemaModel>>>;
   meta: {
     readonly name: string;
     readonly version: number;
@@ -84,7 +95,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<_lssm_lib_schema234.AnyFieldType | _lssm_lib_schema234.AnyEnumType | AnySchemaModel>>>;
   meta: {
     readonly name: string;
     readonly version: number;

package/dist/presentations.js

@@ -1,3 +1,5 @@
+import { __toCommonJS } from "./_virtual/rolldown_runtime.js";
+import { init_registry_utils, registry_utils_exports } from "./registry-utils.js";
 import z from "zod";
 
 //#region src/presentations.ts
@@ -32,6 +34,29 @@ var PresentationRegistry = class {
 		}
 		return candidate;
 	}
+	/** Filter presentations by criteria. */
+	filter(criteria) {
+		const { filterBy } = (init_registry_utils(), __toCommonJS(registry_utils_exports));
+		return filterBy(this.list(), criteria);
+	}
+	/** List presentations with specific tag. */
+	listByTag(tag) {
+		return this.list().filter((p) => p.meta.tags?.includes(tag));
+	}
+	/** List presentations by owner. */
+	listByOwner(owner) {
+		return this.list().filter((p) => p.meta.owners?.includes(owner));
+	}
+	/** Group presentations by key function. */
+	groupBy(keyFn) {
+		const { groupBy } = (init_registry_utils(), __toCommonJS(registry_utils_exports));
+		return groupBy(this.list(), keyFn);
+	}
+	/** Get unique tags from all presentations. */
+	getUniqueTags() {
+		const { getUniqueTags } = (init_registry_utils(), __toCommonJS(registry_utils_exports));
+		return getUniqueTags(this.list());
+	}
 };
 function jsonSchemaForPresentation(p) {
 	const base = {

package/dist/registry-utils.d.ts

@@ -0,0 +1,107 @@
+import { Stability } from "./ownership.js";
+
+//#region src/registry-utils.d.ts
+
+/**
+ * Filter criteria for registry items.
+ * All criteria are optional and combined with AND logic.
+ */
+interface RegistryFilter {
+  /** Filter by tags (item must have at least one matching tag) */
+  tags?: string[];
+  /** Filter by owners (item must have at least one matching owner) */
+  owners?: string[];
+  /** Filter by stability levels */
+  stability?: Stability[];
+  /** Filter by domain (first segment of name) */
+  domain?: string;
+  /** Filter by name pattern (glob or regex) */
+  namePattern?: string;
+}
+/**
+ * Item with standard metadata for filtering.
+ */
+interface FilterableItem {
+  meta: {
+    name?: string;
+    key?: string;
+    tags?: string[];
+    owners?: string[];
+    stability?: Stability;
+    domain?: string;
+  };
+}
+/**
+ * Grouping key function type.
+ */
+type GroupKeyFn<T> = (item: T) => string;
+/**
+ * Grouped items result.
+ */
+interface GroupedItems<T> {
+  key: string;
+  items: T[];
+}
+/**
+ * Pre-built grouping strategies for common use cases.
+ */
+declare const GroupingStrategies: {
+  /**
+   * Group by first tag.
+   */
+  byTag: <T extends FilterableItem>(item: T) => string;
+  /**
+   * Group by all tags (item appears in multiple groups).
+   */
+  byAllTags: <T extends FilterableItem>(item: T) => string[];
+  /**
+   * Group by first owner.
+   */
+  byOwner: <T extends FilterableItem>(item: T) => string;
+  /**
+   * Group by domain (first segment of name).
+   */
+  byDomain: <T extends FilterableItem>(item: T) => string;
+  /**
+   * Group by stability level.
+   */
+  byStability: <T extends FilterableItem>(item: T) => string;
+  /**
+   * Create URL path grouping strategy with configurable depth.
+   */
+  byUrlPath: (level: number) => (item: {
+    path?: string;
+  }) => string;
+};
+/**
+ * Filter items by criteria.
+ * All criteria are combined with AND logic.
+ */
+declare function filterBy<T extends FilterableItem>(items: T[], filter: RegistryFilter): T[];
+/**
+ * Group items by key function.
+ */
+declare function groupBy<T>(items: T[], keyFn: GroupKeyFn<T>): Map<string, T[]>;
+/**
+ * Group items by key function, returning array format.
+ */
+declare function groupByToArray<T>(items: T[], keyFn: GroupKeyFn<T>): GroupedItems<T>[];
+/**
+ * Group items where one item can belong to multiple groups.
+ * Useful for byAllTags grouping.
+ */
+declare function groupByMultiple<T>(items: T[], keysFn: (item: T) => string[]): Map<string, T[]>;
+/**
+ * Get unique tags from a collection of items.
+ */
+declare function getUniqueTags<T extends FilterableItem>(items: T[]): string[];
+/**
+ * Get unique owners from a collection of items.
+ */
+declare function getUniqueOwners<T extends FilterableItem>(items: T[]): string[];
+/**
+ * Get unique domains from a collection of items.
+ */
+declare function getUniqueDomains<T extends FilterableItem>(items: T[]): string[];
+//#endregion
+export { FilterableItem, GroupKeyFn, GroupedItems, GroupingStrategies, RegistryFilter, filterBy, getUniqueDomains, getUniqueOwners, getUniqueTags, groupBy, groupByMultiple, groupByToArray };

package/dist/registry-utils.js

@@ -0,0 +1,122 @@
+import { __esmMin, __export } from "./_virtual/rolldown_runtime.js";
+
+//#region src/registry-utils.ts
+var registry_utils_exports = /* @__PURE__ */ __export({
+	GroupingStrategies: () => GroupingStrategies,
+	filterBy: () => filterBy,
+	getUniqueDomains: () => getUniqueDomains,
+	getUniqueOwners: () => getUniqueOwners,
+	getUniqueTags: () => getUniqueTags,
+	groupBy: () => groupBy,
+	groupByMultiple: () => groupByMultiple,
+	groupByToArray: () => groupByToArray
+});
+/**
+* Filter items by criteria.
+* All criteria are combined with AND logic.
+*/
+function filterBy(items, filter) {
+	return items.filter((item) => {
+		if (filter.tags?.length) {
+			if (!filter.tags.some((tag) => item.meta.tags?.includes(tag))) return false;
+		}
+		if (filter.owners?.length) {
+			if (!filter.owners.some((owner) => item.meta.owners?.includes(owner))) return false;
+		}
+		if (filter.stability?.length) {
+			if (!filter.stability.includes(item.meta.stability ?? "stable")) return false;
+		}
+		if (filter.domain) {
+			if (GroupingStrategies.byDomain(item) !== filter.domain) return false;
+		}
+		if (filter.namePattern) {
+			const name = item.meta.name ?? item.meta.key ?? "";
+			const pattern = filter.namePattern.replace(/\*/g, ".*").replace(/\?/g, ".");
+			if (!new RegExp(`^${pattern}$`, "i").test(name)) return false;
+		}
+		return true;
+	});
+}
+/**
+* Group items by key function.
+*/
+function groupBy(items, keyFn) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const item of items) {
+		const key = keyFn(item);
+		const existing = groups.get(key);
+		if (existing) existing.push(item);
+		else groups.set(key, [item]);
+	}
+	return groups;
+}
+/**
+* Group items by key function, returning array format.
+*/
+function groupByToArray(items, keyFn) {
+	const map = groupBy(items, keyFn);
+	return Array.from(map.entries()).map(([key, items$1]) => ({
+		key,
+		items: items$1
+	}));
+}
+/**
+* Group items where one item can belong to multiple groups.
+* Useful for byAllTags grouping.
+*/
+function groupByMultiple(items, keysFn) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const item of items) {
+		const keys = keysFn(item);
+		for (const key of keys) {
+			const existing = groups.get(key);
+			if (existing) existing.push(item);
+			else groups.set(key, [item]);
+		}
+	}
+	return groups;
+}
+/**
+* Get unique tags from a collection of items.
+*/
+function getUniqueTags(items) {
+	const tags = /* @__PURE__ */ new Set();
+	for (const item of items) for (const tag of item.meta.tags ?? []) tags.add(tag);
+	return Array.from(tags).sort();
+}
+/**
+* Get unique owners from a collection of items.
+*/
+function getUniqueOwners(items) {
+	const owners = /* @__PURE__ */ new Set();
+	for (const item of items) for (const owner of item.meta.owners ?? []) owners.add(owner);
+	return Array.from(owners).sort();
+}
+/**
+* Get unique domains from a collection of items.
+*/
+function getUniqueDomains(items) {
+	const domains = /* @__PURE__ */ new Set();
+	for (const item of items) domains.add(GroupingStrategies.byDomain(item));
+	return Array.from(domains).sort();
+}
+var GroupingStrategies;
+var init_registry_utils = __esmMin(() => {
+	GroupingStrategies = {
+		byTag: (item) => item.meta.tags?.[0] ?? "untagged",
+		byAllTags: (item) => item.meta.tags?.length ? item.meta.tags : ["untagged"],
+		byOwner: (item) => item.meta.owners?.[0] ?? "unowned",
+		byDomain: (item) => {
+			return (item.meta.name ?? item.meta.key ?? "").split(".")[0] ?? "default";
+		},
+		byStability: (item) => item.meta.stability ?? "stable",
+		byUrlPath: (level) => (item) => {
+			if (!item.path) return "root";
+			return item.path.split("/").filter(Boolean).slice(0, level).join("/") || "root";
+		}
+	};
+});
+
+//#endregion
+init_registry_utils();
+export { GroupingStrategies, filterBy, getUniqueDomains, getUniqueOwners, getUniqueTags, groupBy, groupByMultiple, groupByToArray, init_registry_utils, registry_utils_exports };