@lssm/lib.contracts-spec 17.3.2

package/dist/policy/opa-adapter.d.ts

@@ -0,0 +1,41 @@
+import type { PolicyDecision } from '../types.js';
+import type { DecisionContext } from './engine.js';
+import type { ConsentDefinition, PolicySpec } from './spec.js';
+export interface OPAClient {
+    evaluate<T>(decisionPath: string, input: unknown): Promise<T>;
+}
+export interface OPAEvaluationResult {
+    effect?: 'allow' | 'deny';
+    reason?: string;
+    fieldDecisions?: PolicyDecision['fieldDecisions'];
+    requiredConsents?: string[];
+}
+export interface OPAAdapterOptions<Result = OPAEvaluationResult | null> {
+    /**
+     * Path fed to the OPA client (e.g., "sigil/authz/allow").
+     */
+    decisionPath: string;
+    /**
+     * Optional mapper when the OPA client returns a non-standard payload.
+     */
+    mapResult?: (value: unknown) => Result;
+}
+export declare class OPAPolicyAdapter<Result = OPAEvaluationResult | null> {
+    private readonly client;
+    private readonly options;
+    constructor(client: OPAClient, options: OPAAdapterOptions<Result>);
+    evaluate(context: DecisionContext, policies: PolicySpec[], engineDecision: PolicyDecision): Promise<PolicyDecision>;
+}
+export declare function buildOPAInput(context: DecisionContext, policies: PolicySpec[], engineDecision: PolicyDecision): {
+    context: DecisionContext;
+    decision: PolicyDecision;
+    policies: {
+        meta: import("./spec").PolicyMeta;
+        rules: import("./spec").PolicyRule[];
+        fieldPolicies: import("./spec").FieldPolicyRule[] | undefined;
+        pii: import("./spec").PIIPolicy | undefined;
+        relationships: import("./spec").RelationshipDefinition[] | undefined;
+        consents: ConsentDefinition[] | undefined;
+        rateLimits: import("./spec").RateLimitDefinition[] | undefined;
+    }[];
+};

package/dist/policy/opa-adapter.js

@@ -0,0 +1 @@
+export class OPAPolicyAdapter{client;options;constructor(i,n){this.client=i;this.options=n}async evaluate(i,n,e){const t=buildOPAInput(i,n,e),o=await this.client.evaluate(this.options.decisionPath,t),r=this.options.mapResult?this.options.mapResult(o):o;if(!r)return{...e,evaluatedBy:e.evaluatedBy??"engine"};const s=r,l=a(n,e.requiredConsents??[],s.requiredConsents??[]);return{...e,effect:s.effect??e.effect,reason:s.reason??e.reason,fieldDecisions:s.fieldDecisions??e.fieldDecisions,requiredConsents:l.length?l:void 0,evaluatedBy:"opa"}}}export function buildOPAInput(i,n,e){return{context:i,decision:e,policies:n.map((t)=>({meta:t.meta,rules:t.rules,fieldPolicies:t.fieldPolicies,pii:t.pii,relationships:t.relationships,consents:t.consents,rateLimits:t.rateLimits}))}}function a(i,n,e){if(e.length===0)return n;const t=new Set(n.map((r)=>r.id)),o=[...n];for(const r of e){if(t.has(r))continue;const s=u(i,r);if(s){o.push(s);t.add(s.id)}}return o}function u(i,n){for(const e of i){const t=e.consents?.find((o)=>o.id===n);if(t)return t}return{id:n,scope:"unspecified",purpose:"unspecified",description:`Consent "${n}" returned by OPA`,required:!0}}

package/dist/policy/registry.d.ts

@@ -0,0 +1,5 @@
+import { SpecContractRegistry } from '../registry.js';
+import type { PolicySpec } from './spec.js';
+export declare class PolicyRegistry extends SpecContractRegistry<'policy', PolicySpec> {
+    constructor(items?: PolicySpec[]);
+}

package/dist/policy/registry.js

@@ -0,0 +1 @@
+import{SpecContractRegistry as o}from"../registry.js";export class PolicyRegistry extends o{constructor(c){super("policy",c)}}

package/dist/policy/requirements.d.ts

@@ -0,0 +1,64 @@
+import type { PolicyRegistry } from './registry.js';
+import type { PolicyRef } from './spec.js';
+export type PolicyAuthLevel = 'anonymous' | 'user' | 'admin' | 'internal';
+export type PolicyFieldAction = 'read' | 'write';
+/**
+ * Role, permission, and flag requirements shared by guards and declarative
+ * contract policy metadata.
+ */
+export interface CombinedPolicyRequirements {
+    /** All listed roles are required. */
+    roles?: string[];
+    /** At least one listed role is required. */
+    anyRole?: string[];
+    /** All listed permissions are required. */
+    permissions?: string[];
+    /** At least one listed permission is required. */
+    anyPermission?: string[];
+    /** Active feature flags required for access. */
+    flags?: string[];
+}
+/** Field-level policy requirement attached to a declarative surface. */
+export interface PolicyFieldRequirement extends CombinedPolicyRequirements {
+    field: string;
+    actions: PolicyFieldAction[];
+    policy?: PolicyRef;
+}
+/** Generic resource hint passed to policy deciders/evaluators. */
+export interface PolicyResourceRequirement {
+    type?: string;
+    idPath?: string;
+    fields?: string[];
+}
+/**
+ * Additive, shared policy requirement shape for ContractSpec surfaces.
+ *
+ * It intentionally composes the existing guard vocabulary (roles,
+ * permissions, flags) with existing policy references. Surface-specific UX
+ * behavior (for example hide/disable navigation) belongs in the consuming
+ * package, not in this shared type.
+ */
+export interface PolicyRequirement extends CombinedPolicyRequirements {
+    auth?: PolicyAuthLevel;
+    policies?: PolicyRef[];
+    pii?: string[];
+    fieldPolicies?: PolicyFieldRequirement[];
+    resource?: PolicyResourceRequirement;
+}
+/** Policy shape suitable for presentation/data-view/form style surfaces. */
+export type SurfacePolicyRequirement = PolicyRequirement;
+export interface PolicyRequirementValidationIssue {
+    level: 'error' | 'warning' | 'info';
+    message: string;
+    path?: string;
+}
+export interface PolicyRequirementValidationResult {
+    valid: boolean;
+    issues: PolicyRequirementValidationIssue[];
+}
+export interface PolicyRequirementValidationOptions {
+    registry?: PolicyRegistry;
+}
+/** Normalize legacy/light policy objects into the shared requirement shape. */
+export declare function normalizePolicyRequirement(policy: PolicyRequirement | undefined): PolicyRequirement | undefined;
+export declare function validatePolicyRequirement(requirement: PolicyRequirement | undefined, options?: PolicyRequirementValidationOptions): PolicyRequirementValidationResult;

package/dist/policy/requirements.js

@@ -0,0 +1 @@
+const y=["roles","anyRole","permissions","anyPermission","flags","policies"];export function normalizePolicyRequirement(i){if(!i)return;return{...i}}export function validatePolicyRequirement(i,r={}){const e=[];if(!i)return{valid:!0,issues:e};for(const s of y){const o=i[s];if(Array.isArray(o)&&o.length===0)e.push({level:"error",message:`${s} must be omitted instead of provided as an empty array`,path:s})}t(i.roles,"roles",e);t(i.anyRole,"anyRole",e);t(i.permissions,"permissions",e);t(i.anyPermission,"anyPermission",e);t(i.flags,"flags",e);a(i.policies,"policies",r.registry,e);if(i.auth==="anonymous"&&Boolean(i.roles?.length||i.anyRole?.length||i.permissions?.length||i.anyPermission?.length||i.policies?.length))e.push({level:"warning",message:"anonymous auth combined with roles, permissions, or policies may be ambiguous",path:"auth"});i.fieldPolicies?.forEach((s,o)=>{const n=`fieldPolicies[${o}]`;if(!s.field?.trim())e.push({level:"error",message:"Field policy must specify a field",path:`${n}.field`});if(!s.actions?.length)e.push({level:"error",message:"Field policy must specify at least one action",path:`${n}.actions`});s.actions?.forEach((l,c)=>{if(l!=="read"&&l!=="write")e.push({level:"error",message:`Invalid field policy action: ${String(l)}`,path:`${n}.actions[${c}]`})});t(s.roles,`${n}.roles`,e);t(s.anyRole,`${n}.anyRole`,e);t(s.permissions,`${n}.permissions`,e);t(s.anyPermission,`${n}.anyPermission`,e);t(s.flags,`${n}.flags`,e);a(s.policy?[s.policy]:void 0,`${n}.policy`,r.registry,e)});return{valid:!e.some((s)=>s.level==="error"),issues:e}}function t(i,r,e){if(!i?.length)return;const s=new Set;for(const o of i){if(s.has(o)){e.push({level:"error",message:`Duplicate ${r} value: ${o}`,path:r});continue}s.add(o)}}function a(i,r,e,s){if(!i?.length||!e)return;i.forEach((o,n)=>{if(!e.get(o.key,o.version))s.push({level:"error",message:`Policy reference not found: ${o.key}.v${o.version}`,path:`${r}[${n}]`})})}

package/dist/policy/spec.d.ts

@@ -0,0 +1,127 @@
+/** Effect of a policy rule: allow or deny access. */
+import type { DocBlock } from '../docs/types.js';
+import type { OwnerShipMeta } from '../ownership.js';
+import type { VersionedSpecRef } from '../versioning/index.js';
+export type PolicyEffect = 'allow' | 'deny';
+export interface RelationshipDefinition {
+    subjectType: string;
+    relation: string;
+    objectType: string;
+    description?: string;
+    transitive?: boolean;
+}
+export interface PolicyDatabaseSource {
+    sourceKey: string;
+    kind: 'relationship-tuples' | 'attribute-store' | 'audit-evidence';
+    resource: {
+        schema?: string;
+        table: string;
+    };
+    fieldMapping: Record<string, string>;
+    failClosed?: boolean;
+    provenance?: {
+        evidenceRef?: string;
+        generatedBy?: string;
+    };
+}
+export interface PolicyDatabaseEvidence {
+    sourceKey: string;
+    fields?: string[];
+    retentionDays?: number;
+    auditEventRef?: string;
+}
+export interface RelationshipMatcher {
+    relation: string;
+    objectType?: string;
+    objectId?: string;
+}
+export interface ConsentDefinition {
+    id: string;
+    scope: string;
+    purpose: string;
+    description?: string;
+    lawfulBasis?: 'consent' | 'contract' | 'legal_obligation' | 'legitimate_interest';
+    expiresInDays?: number;
+    required?: boolean;
+}
+export interface RateLimitDefinition {
+    id: string;
+    rpm: number;
+    key?: string;
+    windowSeconds?: number;
+    burst?: number;
+}
+export interface PolicyOPAConfig {
+    /** Fully-qualified package, e.g. "sigil.authz" */
+    package: string;
+    /** Optional rule within package (defaults to "allow") */
+    decision?: string;
+}
+export interface PolicyMeta extends OwnerShipMeta {
+    /** Optional scope hint used for discovery. */
+    scope?: 'global' | 'feature' | 'operation';
+}
+export interface AttributeMatcher {
+    equals?: unknown;
+    oneOf?: unknown[];
+    exists?: boolean;
+}
+export interface SubjectMatcher {
+    roles?: string[];
+    attributes?: Record<string, AttributeMatcher>;
+}
+export interface ResourceMatcher {
+    type: string;
+    fields?: string[];
+    attributes?: Record<string, AttributeMatcher>;
+}
+export interface PolicyCondition {
+    /** Simple expression evaluated against { subject, resource, context }. */
+    expression: string;
+}
+export interface PolicyRule {
+    effect: PolicyEffect;
+    actions: string[];
+    subject?: SubjectMatcher;
+    resource?: ResourceMatcher;
+    relationships?: RelationshipMatcher[];
+    databaseSource?: string;
+    requiresConsent?: string[];
+    flags?: string[];
+    rateLimit?: string | RateLimitDefinition;
+    escalate?: 'human_review' | null;
+    conditions?: PolicyCondition[];
+    reason?: string;
+}
+export interface FieldPolicyRule {
+    effect: PolicyEffect;
+    field: string;
+    actions: ('read' | 'write')[];
+    subject?: SubjectMatcher;
+    resource?: ResourceMatcher;
+    databaseEvidence?: PolicyDatabaseEvidence;
+    conditions?: PolicyCondition[];
+    reason?: string;
+}
+export interface PIIPolicy {
+    fields: string[];
+    consentRequired?: boolean;
+    retentionDays?: number;
+}
+export interface PolicySpec {
+    meta: PolicyMeta;
+    rules: PolicyRule[];
+    fieldPolicies?: FieldPolicyRule[];
+    pii?: PIIPolicy;
+    relationships?: RelationshipDefinition[];
+    databaseSources?: PolicyDatabaseSource[];
+    consents?: ConsentDefinition[];
+    rateLimits?: RateLimitDefinition[];
+    opa?: PolicyOPAConfig;
+}
+/**
+ * Reference to a policy spec.
+ * Uses key and version to identify a specific policy.
+ */
+export type PolicyRef = VersionedSpecRef;
+export declare const tech_contracts_policy_DocBlocks: DocBlock[];

package/dist/policy/spec.js

@@ -0,0 +1,150 @@
+export 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
+
+## Purpose
+
+\`PolicySpec\` gives a declarative, typed home for access-control logic covering:
+- **Who** can perform an action (ABAC/ReBAC style rules)
+- **What** they can access (resources + optional field-level overrides)
+- **When** special conditions apply (contextual expressions)
+- **How** PII should be handled (consent/retention hints)
+
+\`PolicyEngine\` evaluates one or more policies and returns an \`allow\`/\`deny\` decision, field-level outcomes, and PII metadata suitable for downstream enforcement (\`OperationSpecRegistry\` \u2192 \`ctx.decide\`).
+
+## Location
+
+- Types & registry: \`packages/libs/contracts/src/policy/spec.ts\`
+- Runtime evaluation: \`packages/libs/contracts/src/policy/engine.ts\`
+- Tests: \`packages/.../policy/engine.test.ts\`
+
+## \`PolicySpec\`
+
+\`\`\`ts
+export interface PolicySpec {
+  meta: PolicyMeta;          // ownership metadata + { name, version, scope? }
+  rules: PolicyRule[];       // allow/deny rules for actions
+  fieldPolicies?: FieldPolicyRule[];
+  pii?: { fields: string[]; consentRequired?: boolean; retentionDays?: number };
+  relationships?: RelationshipDefinition[];
+  consents?: ConsentDefinition[];
+  rateLimits?: RateLimitDefinition[];
+  opa?: { package: string; decision?: string };
+}
+\`\`\`
+
+- \`PolicyRule\`
+  - \`effect\`: \`'allow' | 'deny'\`
+  - \`actions\`: e.g., \`['read', 'write', 'delete']\` (string namespace is flexible)
+  - \`subject\`: \`{ roles?: string[]; attributes?: { attr: matcher } }\`
+  - \`resource\`: \`{ type: string; fields?: string[]; attributes?: {...} }\`
+  - \`relationships\`: \`{ relation, objectId?, objectType? }[]\` \u2192 ReBAC checks (use \`objectId: '$resource'\` to target the current resource)
+  - \`requiresConsent\`: \`['consent_id']\` \u2192 references spec-level consent definitions
+  - \`flags\`: feature flags that must be enabled (\`DecisionContext.flags\`)
+  - \`rateLimit\`: string reference to \`rateLimits\` entry or inline object \`{ rpm, key?, windowSeconds?, burst? }\`
+  - \`escalate\`: \`'human_review' | null\` to indicate manual approval
+  - \`conditions\`: optional expression snippets evaluated against \`{ subject, resource, context }\`
+- \`FieldPolicyRule\`
+  - \`field\`: dot-path string (e.g., \`contact.email\`)
+  - \`actions\`: subset of \`['read', 'write']\`
+  - Same \`subject\` / \`resource\` / \`conditions\` shape
+  - Useful for redacting specific fields, even when the global action is allowed
+- \`RelationshipDefinition\`
+  - Canonical tuples for relationship graph (\`subjectType\`, \`relation\`, \`objectType\`, \`transitive?\`)
+- \`ConsentDefinition\`
+  - \`{ id, scope, purpose, lawfulBasis?, expiresInDays?, required? }\`
+- \`RateLimitDefinition\`
+  - \`{ id, rpm, key?, windowSeconds?, burst? }\`
+- \`PolicyRef\`
+  - \`{ name: string; version: string }\` \u2192 attach to contract specs / workflows
+
+## Registry
+
+\`\`\`ts
+const registry = new PolicyRegistry();
+registry.register(CorePolicySpec);
+const spec = registry.get('core.default', 1);
+\`\`\`
+
+Guarantees uniqueness per \`(name, version)\` and exposes helpers to resolve highest versions.
+
+## Engine
+
+\`\`\`ts
+const engine = new PolicyEngine(policyRegistry);
+
+const decision = engine.decide({
+  action: 'read',
+  subject: { roles: ['admin'] },
+  resource: { type: 'resident', fields: ['contact.email'] },
+  policies: [{ name: 'core.default', version: '1.0.0' }],
+});
+/*
+{
+  effect: 'allow',
+  reason: 'core.default',
+  fieldDecisions: [{ field: 'contact.email', effect: 'allow' }],
+  pii: { fields: ['contact.email'], consentRequired: true }
+}
+*/
+\`\`\`
+
+- First matching **deny** wins; otherwise the first **allow** is returned.
+- Field policies are aggregated across referenced policies:
+  - Later denies override earlier allows for a given field.
+  - Returned as \`fieldDecisions\` to simplify downstream masking.
+- PII metadata is surfaced when defined to help adapt logging/telemetry.
+
+### Expression Support
+
+Conditions 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.
+
+### ReBAC & Relationships
+
+- Provide relationship tuples via \`PolicySpec.relationships\` for documentation/validation.
+- Reference them inside rules with \`relationships: [{ relation: 'manager_of', objectType: 'resident', objectId: '$resource' }]\`.
+- The execution context must populate \`subject.relationships\` (\`[{ relation, object, objectType }]\`) for the engine to evaluate ReBAC guards.
+
+### Consent & Rate Limits
+
+- 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.
+- 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.
+
+### OPA Adapter
+
+- \`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\`).
+- 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'\`.
+- OPA inputs include meta, rules, relationships, rate limits, and consent catalogs to simplify policy authoring on the OPA side.
+
+## Contract Integration
+
+\`ContractSpec.policy\` now supports:
+
+\`\`\`ts
+policy: {
+  auth: 'anonymous' | 'user' | 'admin';
+  ...
+  policies?: PolicyRef[];                // policies evaluated before execution
+  fieldPolicies?: {                      // field hints (read/write) per policy
+    field: string;
+    actions: ('read' | 'write')[];
+    policy?: PolicyRef;
+  }[];
+}
+\`\`\`
+
+Adapters can resolve refs through a shared \`PolicyEngine\` and populate \`ctx.decide\` so \`OperationSpecRegistry.execute\` benefits from centralized enforcement.
+
+## Authoring Guidelines
+
+1. Prefer **allow-by-default** policies but explicitly deny sensitive flows (defense-in-depth).
+2. Keep rule scopes narrow (per feature/operation) and compose multiple \`PolicyRef\`s when necessary.
+3. Store PII field lists here to avoid duplication across logs/telemetry.
+4. Use explicit rule reasons for auditability and better developer feedback.
+5. Treat versioning seriously; bump \`meta.version\` whenever behavior changes.
+
+## Future Enhancements
+
+- Richer expression language (composable predicates, time-based conditions).
+- Multi-tenant relationship graph services (store/resolve relationships at scale).
+- Tooling that auto-generates docs/tests for policies referenced in specs.
+
+`}];

package/dist/policy/validation.d.ts

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

package/dist/policy/validation.js

@@ -0,0 +1 @@
+export function validatePolicySpec(t){const i=[];p(t,i);f(t,i);d(t,i);y(t,i);h(t,i);u(t,i);c(t,i);return{valid:i.filter((s)=>s.level==="error").length===0,issues:i}}function c(t,i){if(!t.databaseSources?.length)return;const s=new Set;t.databaseSources.forEach((e,a)=>{const o=`databaseSources[${a}]`;if(!e.sourceKey?.trim())i.push({level:"error",message:"Database policy source must have a sourceKey",path:`${o}.sourceKey`});else if(s.has(e.sourceKey))i.push({level:"error",message:`Duplicate database policy source: ${e.sourceKey}`,path:`${o}.sourceKey`});else s.add(e.sourceKey);if(!e.resource?.table?.trim())i.push({level:"error",message:"Database policy source must reference a table",path:`${o}.resource.table`});if(!Object.keys(e.fieldMapping??{}).length)i.push({level:"error",message:"Database policy source must map fields",path:`${o}.fieldMapping`})});t.rules.forEach((e,a)=>{if(e.databaseSource&&!s.has(e.databaseSource))i.push({level:"error",message:`Database source "${e.databaseSource}" referenced but not defined`,path:`rules[${a}].databaseSource`})});t.fieldPolicies?.forEach((e,a)=>{const o=e.databaseEvidence?.sourceKey;if(o&&!s.has(o))i.push({level:"error",message:`Database source "${o}" referenced but not defined`,path:`fieldPolicies[${a}].databaseEvidence.sourceKey`})})}function p(t,i){const{meta:s}=t;if(!s.key?.trim())i.push({level:"error",message:"Policy must have a non-empty key",path:"meta.key"});if(!s.version?.trim())i.push({level:"error",message:"Policy must have a non-empty version",path:"meta.version"});if(!s.owners?.length)i.push({level:"warning",message:"Policy should specify owners",path:"meta.owners"})}function f(t,i){if(!t.rules?.length){i.push({level:"warning",message:"Policy has no rules defined",path:"rules"});return}const s=new Set;t.rules.forEach((e,a)=>{const o=`rules[${a}]`;if(!e.actions?.length)i.push({level:"error",message:"Rule must specify at least one action",path:`${o}.actions`});if(!["allow","deny"].includes(e.effect))i.push({level:"error",message:`Invalid rule effect: ${e.effect}`,path:`${o}.effect`});if(typeof e.rateLimit==="string"){s.add(e.rateLimit);if(!t.rateLimits?.some((n)=>n.id===e.rateLimit))i.push({level:"error",message:`Rate limit "${e.rateLimit}" referenced but not defined`,path:`${o}.rateLimit`})}if(e.requiresConsent?.length){for(const n of e.requiresConsent)if(!t.consents?.some((r)=>r.id===n))i.push({level:"error",message:`Consent "${n}" referenced but not defined`,path:`${o}.requiresConsent`})}l(e.conditions,`${o}.conditions`,i)});if(t.rateLimits?.length){for(const e of t.rateLimits)if(!s.has(e.id)){if(!t.rules.some((o)=>typeof o.rateLimit==="object"&&o.rateLimit.id===e.id))i.push({level:"info",message:`Rate limit "${e.id}" is defined but not referenced`,path:"rateLimits"})}}}function d(t,i){if(!t.fieldPolicies?.length)return;const s=new Map;t.fieldPolicies.forEach((e,a)=>{const o=`fieldPolicies[${a}]`;if(!e.field?.trim())i.push({level:"error",message:"Field policy must specify a field",path:`${o}.field`});if(!e.actions?.length)i.push({level:"error",message:"Field policy must specify at least one action",path:`${o}.actions`});for(const r of e.actions)if(!["read","write"].includes(r))i.push({level:"error",message:`Invalid field action: ${r}`,path:`${o}.actions`});const n=s.get(e.field)??[];n.push(e);s.set(e.field,n);l(e.conditions,`${o}.conditions`,i)});for(const[e,a]of s.entries())if(a.length>1){if(a.some((n)=>n.effect==="allow")&&a.some((n)=>n.effect==="deny"))i.push({level:"warning",message:`Field "${e}" has potentially conflicting allow/deny policies`,path:"fieldPolicies",context:{field:e,ruleCount:a.length}})}}function y(t,i){if(!t.rateLimits?.length)return;const s=new Set;t.rateLimits.forEach((e,a)=>{const o=`rateLimits[${a}]`;if(!e.id?.trim())i.push({level:"error",message:"Rate limit must have an id",path:`${o}.id`});else if(s.has(e.id))i.push({level:"error",message:`Duplicate rate limit id: ${e.id}`,path:`${o}.id`});else s.add(e.id);if(typeof e.rpm!=="number"||e.rpm<=0)i.push({level:"error",message:"Rate limit rpm must be a positive number",path:`${o}.rpm`});if(e.windowSeconds!==void 0&&e.windowSeconds<=0)i.push({level:"error",message:"Rate limit windowSeconds must be positive if specified",path:`${o}.windowSeconds`});if(e.burst!==void 0&&e.burst<0)i.push({level:"error",message:"Rate limit burst must be non-negative if specified",path:`${o}.burst`})})}function h(t,i){if(!t.consents?.length)return;const s=new Set;t.consents.forEach((e,a)=>{const o=`consents[${a}]`;if(!e.id?.trim())i.push({level:"error",message:"Consent must have an id",path:`${o}.id`});else if(s.has(e.id))i.push({level:"error",message:`Duplicate consent id: ${e.id}`,path:`${o}.id`});else s.add(e.id);if(!e.scope?.trim())i.push({level:"error",message:"Consent must specify a scope",path:`${o}.scope`});if(!e.purpose?.trim())i.push({level:"error",message:"Consent must specify a purpose",path:`${o}.purpose`});if(e.expiresInDays!==void 0&&e.expiresInDays<=0)i.push({level:"error",message:"Consent expiresInDays must be positive if specified",path:`${o}.expiresInDays`})})}function u(t,i){if(!t.relationships?.length)return;const s=new Set;t.relationships.forEach((e,a)=>{const o=`relationships[${a}]`,n=`${e.subjectType}:${e.relation}:${e.objectType}`;if(!e.subjectType?.trim())i.push({level:"error",message:"Relationship must specify subjectType",path:`${o}.subjectType`});if(!e.relation?.trim())i.push({level:"error",message:"Relationship must specify relation",path:`${o}.relation`});if(!e.objectType?.trim())i.push({level:"error",message:"Relationship must specify objectType",path:`${o}.objectType`});if(s.has(n))i.push({level:"warning",message:`Duplicate relationship definition: ${n}`,path:o});else s.add(n)})}function l(t,i,s){if(!t?.length)return;t.forEach((e,a)=>{if(!e.expression?.trim())s.push({level:"error",message:"Condition must have a non-empty expression",path:`${i}[${a}].expression`})})}export function validatePolicyConsistency(t){const i=[];for(const s of t.policies.list()){const e=validatePolicySpec(s);i.push(...e.issues.map((a)=>({...a,path:`${s.meta.key}.v${s.meta.version}${a.path?`.${a.path}`:""}`})))}if(t.operations)for(const s of t.operations.list()){const e=s.policy.policies??[];for(const o of e)if(!t.policies.get(o.key,o.version))i.push({level:"error",message:`Operation "${s.meta.key}.v${s.meta.version}" references unknown policy "${o.key}.v${o.version}"`,path:`operations.${s.meta.key}.policy.policies`});const a=s.policy.fieldPolicies??[];for(const o of a)if(o.policy){if(!t.policies.get(o.policy.key,o.policy.version))i.push({level:"error",message:`Operation "${s.meta.key}.v${s.meta.version}" references unknown field policy "${o.policy.key}.v${o.policy.version}"`,path:`operations.${s.meta.key}.policy.fieldPolicies`})}}return{valid:i.filter((s)=>s.level==="error").length===0,issues:i}}export class PolicyValidationError extends Error{issues;constructor(t,i){super(t);this.issues=i;this.name="PolicyValidationError"}}export function assertPolicySpecValid(t){const i=validatePolicySpec(t);if(!i.valid)throw new PolicyValidationError(`Policy ${t.meta.key}.v${t.meta.version} is invalid`,i.issues)}export function assertPolicyConsistency(t){const i=validatePolicyConsistency(t);if(!i.valid)throw new PolicyValidationError("Policy consistency check failed",i.issues)}

package/dist/presentations/index.d.js

@@ -0,0 +1 @@
+export*from"./presentations.js";export*from"./registry.js";

package/dist/presentations/index.d.ts

@@ -0,0 +1,2 @@
+export * from './presentations.js';
+export * from './registry.js';

package/dist/presentations/index.js

@@ -0,0 +1 @@
+export*from"./presentations.js";export*from"./registry.js";

package/dist/presentations/presentations.d.ts

@@ -0,0 +1,54 @@
+import type { AnySchemaModel } from '@lssm/lib.schema';
+import type { CapabilityRef } from '../capabilities/capabilities.js';
+import type { DocBlock } from '../docs/types.js';
+import type { OwnerShipMeta } from '../ownership.js';
+import type { SurfacePolicyRequirement } from '../policy/requirements.js';
+import type { BlockConfig } from './shim-blocknotejs.js';
+export type { BlockConfig } from './shim-blocknotejs.js';
+/** Supported render targets for the transform engine and descriptors. */
+export type PresentationTarget = 'react' | 'markdown' | 'application/json' | 'application/xml';
+export interface PresentationSpecMeta extends OwnerShipMeta {
+    /** Business goal: why this exists */
+    goal: string;
+    /** Background, constraints, scope edges (feeds docs & LLM context) */
+    context: string;
+}
+/** React component presentation source. */
+export interface PresentationSourceComponentReact {
+    /** Source marker for React component presentations. */
+    type: 'component';
+    /** Framework for the component source (currently only 'react'). */
+    framework: 'react';
+    /** Component key resolved by host `componentMap`. */
+    componentKey: string;
+    /** Optional props schema to validate against. */
+    props?: AnySchemaModel;
+}
+/** BlockNoteJS document presentation source. */
+export interface PresentationSourceBlocknotejs {
+    /** Source marker for BlockNoteJS document presentations. */
+    type: 'blocknotejs';
+    /** BlockNoteJS JSON document. */
+    docJson: unknown;
+    /** Optional BlockNote config to guide rendering. */
+    blockConfig?: BlockConfig;
+}
+export type PresentationSource = PresentationSourceComponentReact | PresentationSourceBlocknotejs;
+/**
+ * Normalized presentation spec decoupled from framework/adapters.
+ * Renderers and validators are provided via TransformEngine.
+ */
+export interface PresentationSpec {
+    meta: PresentationSpecMeta;
+    /**
+     * Optional reference to the capability that provides this presentation.
+     * Used for bidirectional linking between capabilities and presentations.
+     */
+    capability?: CapabilityRef;
+    policy?: SurfacePolicyRequirement;
+    source: PresentationSource;
+    targets: PresentationTarget[];
+}
+export declare const definePresentation: (spec: PresentationSpec) => PresentationSpec;
+export declare const tech_contracts_presentations_conventions_DocBlocks: DocBlock[];
+export declare const techContractsDocs: DocBlock[];