@vorionsys/contracts 0.1.0

package/dist/aci/effective-permission.d.ts

@@ -0,0 +1,371 @@
+/**
+ * @fileoverview Effective Permission Calculation
+ *
+ * Provides types and functions for calculating effective permissions based on
+ * multiple inputs including certification tier, competence level, runtime tier,
+ * observability ceiling, and context policy ceiling.
+ *
+ * The effective permission is the minimum of all applicable ceilings, ensuring
+ * that agents can never exceed the most restrictive constraint in any dimension.
+ *
+ * @module @vorion/contracts/aci/effective-permission
+ */
+import { z } from 'zod';
+import { CapabilityLevel } from './levels.js';
+import { CertificationTier, RuntimeTier } from './tiers.js';
+/**
+ * Context for calculating effective permissions.
+ *
+ * This combines all factors that influence what an agent is permitted to do:
+ * - certificationTier: External attestation status
+ * - competenceLevel: Agent's declared capability level
+ * - runtimeTier: Deployment-specific autonomy level
+ * - observabilityCeiling: Maximum level based on observability requirements
+ * - contextPolicyCeiling: Maximum level based on current context policy
+ */
+export interface EffectivePermissionContext {
+    /** ACI certification tier (external attestation status) */
+    certificationTier: CertificationTier;
+    /** Agent's competence/capability level */
+    competenceLevel: CapabilityLevel;
+    /** Vorion runtime tier (deployment autonomy) */
+    runtimeTier: RuntimeTier;
+    /** Maximum level based on observability requirements (0-7) */
+    observabilityCeiling: number;
+    /** Maximum level based on context policy (0-7) */
+    contextPolicyCeiling: number;
+}
+/**
+ * Zod schema for EffectivePermissionContext.
+ */
+export declare const effectivePermissionContextSchema: z.ZodObject<{
+    certificationTier: z.ZodNativeEnum<typeof CertificationTier>;
+    competenceLevel: z.ZodNativeEnum<typeof CapabilityLevel>;
+    runtimeTier: z.ZodNativeEnum<typeof RuntimeTier>;
+    observabilityCeiling: z.ZodNumber;
+    contextPolicyCeiling: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    certificationTier: CertificationTier;
+    competenceLevel: CapabilityLevel;
+    runtimeTier: RuntimeTier;
+    observabilityCeiling: number;
+    contextPolicyCeiling: number;
+}, {
+    certificationTier: CertificationTier;
+    competenceLevel: CapabilityLevel;
+    runtimeTier: RuntimeTier;
+    observabilityCeiling: number;
+    contextPolicyCeiling: number;
+}>;
+/**
+ * Result of effective permission calculation.
+ */
+export interface EffectivePermission {
+    /** The effective permission level (minimum of all ceilings) */
+    level: CapabilityLevel;
+    /** Whether the effective level was constrained */
+    constrained: boolean;
+    /** The factor that caused the constraint (if constrained) */
+    constrainingFactor?: ConstrainingFactor;
+    /** Details about each ceiling that was applied */
+    ceilings: PermissionCeilings;
+    /** Recommendations for increasing effective permission */
+    recommendations?: string[];
+}
+/**
+ * Factors that can constrain effective permission.
+ */
+export type ConstrainingFactor = 'certification_tier' | 'competence_level' | 'runtime_tier' | 'observability_ceiling' | 'context_policy_ceiling' | 'multiple';
+/**
+ * Individual ceiling values applied to permission calculation.
+ */
+export interface PermissionCeilings {
+    /** Ceiling from certification tier */
+    certificationCeiling: CapabilityLevel;
+    /** Ceiling from competence level */
+    competenceCeiling: CapabilityLevel;
+    /** Ceiling from runtime tier */
+    runtimeCeiling: CapabilityLevel;
+    /** Ceiling from observability requirements */
+    observabilityCeiling: CapabilityLevel;
+    /** Ceiling from context policy */
+    contextPolicyCeiling: CapabilityLevel;
+}
+/**
+ * Zod schema for ConstrainingFactor.
+ */
+export declare const constrainingFactorSchema: z.ZodEnum<["certification_tier", "competence_level", "runtime_tier", "observability_ceiling", "context_policy_ceiling", "multiple"]>;
+/**
+ * Zod schema for PermissionCeilings.
+ */
+export declare const permissionCeilingsSchema: z.ZodObject<{
+    certificationCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
+    competenceCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
+    runtimeCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
+    observabilityCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
+    contextPolicyCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
+}, "strip", z.ZodTypeAny, {
+    observabilityCeiling: CapabilityLevel;
+    contextPolicyCeiling: CapabilityLevel;
+    certificationCeiling: CapabilityLevel;
+    competenceCeiling: CapabilityLevel;
+    runtimeCeiling: CapabilityLevel;
+}, {
+    observabilityCeiling: CapabilityLevel;
+    contextPolicyCeiling: CapabilityLevel;
+    certificationCeiling: CapabilityLevel;
+    competenceCeiling: CapabilityLevel;
+    runtimeCeiling: CapabilityLevel;
+}>;
+/**
+ * Zod schema for EffectivePermission.
+ */
+export declare const effectivePermissionSchema: z.ZodObject<{
+    level: z.ZodNativeEnum<typeof CapabilityLevel>;
+    constrained: z.ZodBoolean;
+    constrainingFactor: z.ZodOptional<z.ZodEnum<["certification_tier", "competence_level", "runtime_tier", "observability_ceiling", "context_policy_ceiling", "multiple"]>>;
+    ceilings: z.ZodObject<{
+        certificationCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
+        competenceCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
+        runtimeCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
+        observabilityCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
+        contextPolicyCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
+    }, "strip", z.ZodTypeAny, {
+        observabilityCeiling: CapabilityLevel;
+        contextPolicyCeiling: CapabilityLevel;
+        certificationCeiling: CapabilityLevel;
+        competenceCeiling: CapabilityLevel;
+        runtimeCeiling: CapabilityLevel;
+    }, {
+        observabilityCeiling: CapabilityLevel;
+        contextPolicyCeiling: CapabilityLevel;
+        certificationCeiling: CapabilityLevel;
+        competenceCeiling: CapabilityLevel;
+        runtimeCeiling: CapabilityLevel;
+    }>;
+    recommendations: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    level: CapabilityLevel;
+    constrained: boolean;
+    ceilings: {
+        observabilityCeiling: CapabilityLevel;
+        contextPolicyCeiling: CapabilityLevel;
+        certificationCeiling: CapabilityLevel;
+        competenceCeiling: CapabilityLevel;
+        runtimeCeiling: CapabilityLevel;
+    };
+    constrainingFactor?: "certification_tier" | "competence_level" | "runtime_tier" | "observability_ceiling" | "context_policy_ceiling" | "multiple" | undefined;
+    recommendations?: string[] | undefined;
+}, {
+    level: CapabilityLevel;
+    constrained: boolean;
+    ceilings: {
+        observabilityCeiling: CapabilityLevel;
+        contextPolicyCeiling: CapabilityLevel;
+        certificationCeiling: CapabilityLevel;
+        competenceCeiling: CapabilityLevel;
+        runtimeCeiling: CapabilityLevel;
+    };
+    constrainingFactor?: "certification_tier" | "competence_level" | "runtime_tier" | "observability_ceiling" | "context_policy_ceiling" | "multiple" | undefined;
+    recommendations?: string[] | undefined;
+}>;
+/**
+ * Calculates the effective permission from the context.
+ *
+ * The effective permission is the minimum of all applicable ceilings:
+ * - Certification tier ceiling
+ * - Competence level (agent's declared capability)
+ * - Runtime tier ceiling
+ * - Observability ceiling
+ * - Context policy ceiling
+ *
+ * @param ctx - Permission context
+ * @returns Effective permission result
+ *
+ * @example
+ * ```typescript
+ * const result = calculateEffectivePermission({
+ *   certificationTier: CertificationTier.T3_MONITORED,
+ *   competenceLevel: CapabilityLevel.L4_STANDARD,
+ *   runtimeTier: RuntimeTier.T3_MONITORED,
+ *   observabilityCeiling: 4,
+ *   contextPolicyCeiling: 3,
+ * });
+ * // result.level === CapabilityLevel.L3_EXECUTE
+ * // result.constrained === true
+ * // result.constrainingFactor === 'context_policy_ceiling'
+ * ```
+ */
+export declare function calculateEffectivePermission(ctx: EffectivePermissionContext): EffectivePermission;
+/**
+ * Checks if an effective permission allows a specific capability level.
+ *
+ * @param permission - Effective permission
+ * @param requiredLevel - Required capability level
+ * @returns True if the permission allows the required level
+ */
+export declare function permissionAllowsLevel(permission: EffectivePermission, requiredLevel: CapabilityLevel): boolean;
+/**
+ * Checks if a context allows a specific capability level.
+ *
+ * @param ctx - Permission context
+ * @param requiredLevel - Required capability level
+ * @returns True if the context allows the required level
+ */
+export declare function contextAllowsLevel(ctx: EffectivePermissionContext, requiredLevel: CapabilityLevel): boolean;
+/**
+ * Result of a permission check with detailed information.
+ */
+export interface PermissionCheckResult {
+    /** Whether the requested level is allowed */
+    allowed: boolean;
+    /** The effective permission level */
+    effectiveLevel: CapabilityLevel;
+    /** The requested level */
+    requestedLevel: CapabilityLevel;
+    /** Gap between requested and effective (0 if allowed) */
+    levelGap: number;
+    /** Full effective permission details */
+    permission: EffectivePermission;
+}
+/**
+ * Performs a detailed permission check.
+ *
+ * @param ctx - Permission context
+ * @param requiredLevel - Required capability level
+ * @returns Detailed permission check result
+ */
+export declare function checkPermission(ctx: EffectivePermissionContext, requiredLevel: CapabilityLevel): PermissionCheckResult;
+/**
+ * Zod schema for PermissionCheckResult.
+ */
+export declare const permissionCheckResultSchema: z.ZodObject<{
+    allowed: z.ZodBoolean;
+    effectiveLevel: z.ZodNativeEnum<typeof CapabilityLevel>;
+    requestedLevel: z.ZodNativeEnum<typeof CapabilityLevel>;
+    levelGap: z.ZodNumber;
+    permission: z.ZodObject<{
+        level: z.ZodNativeEnum<typeof CapabilityLevel>;
+        constrained: z.ZodBoolean;
+        constrainingFactor: z.ZodOptional<z.ZodEnum<["certification_tier", "competence_level", "runtime_tier", "observability_ceiling", "context_policy_ceiling", "multiple"]>>;
+        ceilings: z.ZodObject<{
+            certificationCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
+            competenceCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
+            runtimeCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
+            observabilityCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
+            contextPolicyCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
+        }, "strip", z.ZodTypeAny, {
+            observabilityCeiling: CapabilityLevel;
+            contextPolicyCeiling: CapabilityLevel;
+            certificationCeiling: CapabilityLevel;
+            competenceCeiling: CapabilityLevel;
+            runtimeCeiling: CapabilityLevel;
+        }, {
+            observabilityCeiling: CapabilityLevel;
+            contextPolicyCeiling: CapabilityLevel;
+            certificationCeiling: CapabilityLevel;
+            competenceCeiling: CapabilityLevel;
+            runtimeCeiling: CapabilityLevel;
+        }>;
+        recommendations: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        level: CapabilityLevel;
+        constrained: boolean;
+        ceilings: {
+            observabilityCeiling: CapabilityLevel;
+            contextPolicyCeiling: CapabilityLevel;
+            certificationCeiling: CapabilityLevel;
+            competenceCeiling: CapabilityLevel;
+            runtimeCeiling: CapabilityLevel;
+        };
+        constrainingFactor?: "certification_tier" | "competence_level" | "runtime_tier" | "observability_ceiling" | "context_policy_ceiling" | "multiple" | undefined;
+        recommendations?: string[] | undefined;
+    }, {
+        level: CapabilityLevel;
+        constrained: boolean;
+        ceilings: {
+            observabilityCeiling: CapabilityLevel;
+            contextPolicyCeiling: CapabilityLevel;
+            certificationCeiling: CapabilityLevel;
+            competenceCeiling: CapabilityLevel;
+            runtimeCeiling: CapabilityLevel;
+        };
+        constrainingFactor?: "certification_tier" | "competence_level" | "runtime_tier" | "observability_ceiling" | "context_policy_ceiling" | "multiple" | undefined;
+        recommendations?: string[] | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    allowed: boolean;
+    effectiveLevel: CapabilityLevel;
+    requestedLevel: CapabilityLevel;
+    levelGap: number;
+    permission: {
+        level: CapabilityLevel;
+        constrained: boolean;
+        ceilings: {
+            observabilityCeiling: CapabilityLevel;
+            contextPolicyCeiling: CapabilityLevel;
+            certificationCeiling: CapabilityLevel;
+            competenceCeiling: CapabilityLevel;
+            runtimeCeiling: CapabilityLevel;
+        };
+        constrainingFactor?: "certification_tier" | "competence_level" | "runtime_tier" | "observability_ceiling" | "context_policy_ceiling" | "multiple" | undefined;
+        recommendations?: string[] | undefined;
+    };
+}, {
+    allowed: boolean;
+    effectiveLevel: CapabilityLevel;
+    requestedLevel: CapabilityLevel;
+    levelGap: number;
+    permission: {
+        level: CapabilityLevel;
+        constrained: boolean;
+        ceilings: {
+            observabilityCeiling: CapabilityLevel;
+            contextPolicyCeiling: CapabilityLevel;
+            certificationCeiling: CapabilityLevel;
+            competenceCeiling: CapabilityLevel;
+            runtimeCeiling: CapabilityLevel;
+        };
+        constrainingFactor?: "certification_tier" | "competence_level" | "runtime_tier" | "observability_ceiling" | "context_policy_ceiling" | "multiple" | undefined;
+        recommendations?: string[] | undefined;
+    };
+}>;
+/**
+ * Creates a new context with a modified ceiling.
+ *
+ * @param ctx - Original context
+ * @param factor - Factor to modify
+ * @param newValue - New value for the factor
+ * @returns New context with modified value
+ */
+export declare function modifyContextCeiling(ctx: EffectivePermissionContext, factor: Exclude<ConstrainingFactor, 'multiple'>, newValue: number): EffectivePermissionContext;
+/**
+ * Calculates what context changes would be needed to achieve a target level.
+ *
+ * @param ctx - Current context
+ * @param targetLevel - Desired capability level
+ * @returns Map of factors to required values
+ */
+export declare function calculateRequiredChanges(ctx: EffectivePermissionContext, targetLevel: CapabilityLevel): Map<Exclude<ConstrainingFactor, 'multiple'>, number>;
+/**
+ * Creates a default permission context.
+ *
+ * @param overrides - Optional overrides
+ * @returns Default context with any overrides applied
+ */
+export declare function createDefaultContext(overrides?: Partial<EffectivePermissionContext>): EffectivePermissionContext;
+/**
+ * Creates a maximally permissive context.
+ *
+ * @returns Context with all ceilings at maximum
+ */
+export declare function createMaxPermissionContext(): EffectivePermissionContext;
+/**
+ * Type guard for EffectivePermissionContext.
+ */
+export declare function isEffectivePermissionContext(value: unknown): value is EffectivePermissionContext;
+/**
+ * Type guard for EffectivePermission.
+ */
+export declare function isEffectivePermission(value: unknown): value is EffectivePermission;
+//# sourceMappingURL=effective-permission.d.ts.map

package/dist/aci/effective-permission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effective-permission.d.ts","sourceRoot":"","sources":["../../src/aci/effective-permission.ts"],"names":[],"mappings":"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"}