@vorionsys/contracts 0.1.0

package/dist/canonical/governance.d.ts

@@ -0,0 +1,905 @@
+/**
+ * @fileoverview Canonical Governance type definitions for the Vorion Platform.
+ *
+ * This file provides the authoritative definitions for governance-related types
+ * including authorization results, authentication context, hierarchy levels,
+ * and authority scopes. These types unify various implementations across the
+ * codebase into a single source of truth.
+ *
+ * @module @vorion/contracts/canonical/governance
+ */
+import { z } from 'zod';
+import { DenialReason } from '../v2/decision.js';
+export { DenialReason };
+/**
+ * Extended denial reasons for governance-specific scenarios.
+ *
+ * These extend the base DenialReason enum with governance-specific codes.
+ * Use DenialReason for trust/policy denials, and these for RBAC/scope denials.
+ */
+export declare enum GovernanceDenialReason {
+    /** User lacks required roles for the action */
+    MISSING_ROLES = "missing_roles",
+    /** User lacks required permissions for the action */
+    MISSING_PERMISSIONS = "missing_permissions",
+    /** Action is outside the authorized scope */
+    SCOPE_VIOLATION = "scope_violation",
+    /** Human oversight/approval is required but not present */
+    REQUIRES_HUMAN_APPROVAL = "requires_human_approval"
+}
+/**
+ * Zod schema for GovernanceDenialReason enum validation.
+ */
+export declare const governanceDenialReasonSchema: z.ZodNativeEnum<typeof GovernanceDenialReason>;
+/**
+ * Zod schema for base DenialReason enum validation (from v2/decision.ts).
+ */
+export declare const denialReasonSchema: z.ZodNativeEnum<typeof DenialReason>;
+/**
+ * Zod schema for combined denial reasons (DenialReason or GovernanceDenialReason).
+ */
+export declare const anyDenialReasonSchema: z.ZodUnion<[z.ZodNativeEnum<typeof DenialReason>, z.ZodNativeEnum<typeof GovernanceDenialReason>]>;
+/**
+ * Result of an authorization check.
+ *
+ * Unifies simple RBAC-style checks (roles/permissions) and more complex
+ * trust-based authorization decisions. Provides rich context about why
+ * a request was allowed or denied.
+ */
+export interface AuthorizationResult {
+    /** Whether the action is authorized */
+    readonly allowed: boolean;
+    /** Human-readable explanation of the decision */
+    readonly reason?: string;
+    /** Specific denial reason code (when allowed=false) - trust/policy denial */
+    readonly denialReason?: DenialReason;
+    /** Specific denial reason code (when allowed=false) - governance/RBAC denial */
+    readonly governanceDenialReason?: GovernanceDenialReason;
+    /** Roles that matched the authorization requirement (RBAC) */
+    readonly matchedRoles?: readonly string[];
+    /** Permissions that matched the authorization requirement (RBAC) */
+    readonly matchedPermissions?: readonly string[];
+    /** Constraints that apply to the authorized action */
+    readonly constraints?: AuthorizationConstraints;
+    /** Recommended remediation steps if denied */
+    readonly remediations?: readonly string[];
+    /** When this authorization decision expires */
+    readonly expiresAt?: Date;
+}
+/**
+ * Constraints applied to an authorized action.
+ *
+ * Even when an action is allowed, these constraints define the
+ * boundaries within which it must be executed.
+ */
+export interface AuthorizationConstraints {
+    /** Maximum number of operations allowed */
+    readonly maxOperations?: number;
+    /** Time window in milliseconds for the authorization */
+    readonly validityMs?: number;
+    /** Resource identifiers this authorization applies to */
+    readonly resources?: readonly string[];
+    /** Data sensitivity levels allowed */
+    readonly allowedSensitivity?: readonly string[];
+    /** Whether human oversight is required during execution */
+    readonly requiresOversight?: boolean;
+    /** Additional custom constraints */
+    readonly custom?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Zod schema for AuthorizationConstraints.
+ */
+export declare const authorizationConstraintsSchema: z.ZodObject<{
+    maxOperations: z.ZodOptional<z.ZodNumber>;
+    validityMs: z.ZodOptional<z.ZodNumber>;
+    resources: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    allowedSensitivity: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    requiresOversight: z.ZodOptional<z.ZodBoolean>;
+    custom: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    custom?: Record<string, unknown> | undefined;
+    maxOperations?: number | undefined;
+    validityMs?: number | undefined;
+    resources?: string[] | undefined;
+    allowedSensitivity?: string[] | undefined;
+    requiresOversight?: boolean | undefined;
+}, {
+    custom?: Record<string, unknown> | undefined;
+    maxOperations?: number | undefined;
+    validityMs?: number | undefined;
+    resources?: string[] | undefined;
+    allowedSensitivity?: string[] | undefined;
+    requiresOversight?: boolean | undefined;
+}>;
+/**
+ * Zod schema for AuthorizationResult.
+ */
+export declare const authorizationResultSchema: z.ZodObject<{
+    allowed: z.ZodBoolean;
+    reason: z.ZodOptional<z.ZodString>;
+    denialReason: z.ZodOptional<z.ZodNativeEnum<typeof DenialReason>>;
+    governanceDenialReason: z.ZodOptional<z.ZodNativeEnum<typeof GovernanceDenialReason>>;
+    matchedRoles: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
+    matchedPermissions: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
+    constraints: z.ZodOptional<z.ZodObject<{
+        maxOperations: z.ZodOptional<z.ZodNumber>;
+        validityMs: z.ZodOptional<z.ZodNumber>;
+        resources: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        allowedSensitivity: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        requiresOversight: z.ZodOptional<z.ZodBoolean>;
+        custom: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        custom?: Record<string, unknown> | undefined;
+        maxOperations?: number | undefined;
+        validityMs?: number | undefined;
+        resources?: string[] | undefined;
+        allowedSensitivity?: string[] | undefined;
+        requiresOversight?: boolean | undefined;
+    }, {
+        custom?: Record<string, unknown> | undefined;
+        maxOperations?: number | undefined;
+        validityMs?: number | undefined;
+        resources?: string[] | undefined;
+        allowedSensitivity?: string[] | undefined;
+        requiresOversight?: boolean | undefined;
+    }>>;
+    remediations: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString, "many">>>;
+    expiresAt: z.ZodOptional<z.ZodDate>;
+}, "strip", z.ZodTypeAny, {
+    allowed: boolean;
+    constraints?: {
+        custom?: Record<string, unknown> | undefined;
+        maxOperations?: number | undefined;
+        validityMs?: number | undefined;
+        resources?: string[] | undefined;
+        allowedSensitivity?: string[] | undefined;
+        requiresOversight?: boolean | undefined;
+    } | undefined;
+    expiresAt?: Date | undefined;
+    denialReason?: DenialReason | undefined;
+    reason?: string | undefined;
+    governanceDenialReason?: GovernanceDenialReason | undefined;
+    matchedRoles?: readonly string[] | undefined;
+    matchedPermissions?: readonly string[] | undefined;
+    remediations?: readonly string[] | undefined;
+}, {
+    allowed: boolean;
+    constraints?: {
+        custom?: Record<string, unknown> | undefined;
+        maxOperations?: number | undefined;
+        validityMs?: number | undefined;
+        resources?: string[] | undefined;
+        allowedSensitivity?: string[] | undefined;
+        requiresOversight?: boolean | undefined;
+    } | undefined;
+    expiresAt?: Date | undefined;
+    denialReason?: DenialReason | undefined;
+    reason?: string | undefined;
+    governanceDenialReason?: GovernanceDenialReason | undefined;
+    matchedRoles?: readonly string[] | undefined;
+    matchedPermissions?: readonly string[] | undefined;
+    remediations?: readonly string[] | undefined;
+}>;
+/** TypeScript type inferred from the Zod schema */
+export type AuthorizationResultType = z.infer<typeof authorizationResultSchema>;
+/**
+ * Governance roles for permission-based access control.
+ *
+ * Defines roles specific to governance operations.
+ * These roles determine what governance actions a user can perform.
+ *
+ * Note: For user management roles, see UserRole in agent.ts
+ */
+export type GovernanceRole = 'admin' | 'operator' | 'trainer' | 'consumer' | 'reviewer' | 'both';
+/**
+ * Zod schema for GovernanceRole validation.
+ */
+export declare const governanceRoleSchema: z.ZodEnum<["admin", "operator", "trainer", "consumer", "reviewer", "both"]>;
+/**
+ * Authentication context for an authenticated user/entity.
+ *
+ * Contains identity information extracted from JWT tokens or session data.
+ * Used throughout the system to make authorization decisions.
+ */
+export interface AuthContext {
+    /** Unique identifier for the authenticated user */
+    readonly userId: string;
+    /** Tenant/organization the user belongs to */
+    readonly tenantId: string;
+    /** Roles assigned to the user */
+    readonly roles: readonly string[];
+    /** Fine-grained permissions assigned to the user */
+    readonly permissions: readonly string[];
+    /** User's primary governance role (for UI/simple RBAC) */
+    readonly governanceRole?: GovernanceRole;
+    /** Current session identifier */
+    readonly sessionId?: string;
+    /** Agent ID if this context represents an agent */
+    readonly agentId?: string;
+    /** Hierarchy level if this context represents a hierarchical entity */
+    readonly hierarchyLevel?: HierarchyLevel;
+    /** Additional attributes from the authentication source */
+    readonly attributes?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Zod schema for AuthContext.
+ */
+export declare const authContextSchema: z.ZodObject<{
+    userId: z.ZodString;
+    tenantId: z.ZodString;
+    roles: z.ZodReadonly<z.ZodArray<z.ZodString, "many">>;
+    permissions: z.ZodReadonly<z.ZodArray<z.ZodString, "many">>;
+    governanceRole: z.ZodOptional<z.ZodEnum<["admin", "operator", "trainer", "consumer", "reviewer", "both"]>>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodString>;
+    hierarchyLevel: z.ZodOptional<z.ZodLazy<z.ZodEnum<["hitl", "orch", "metagoat", "agent", "bot"]>>>;
+    attributes: z.ZodOptional<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, "strip", z.ZodTypeAny, {
+    userId: string;
+    permissions: readonly string[];
+    tenantId: string;
+    roles: readonly string[];
+    agentId?: string | undefined;
+    sessionId?: string | undefined;
+    governanceRole?: "admin" | "operator" | "both" | "trainer" | "consumer" | "reviewer" | undefined;
+    hierarchyLevel?: "agent" | "hitl" | "orch" | "metagoat" | "bot" | undefined;
+    attributes?: Readonly<Record<string, unknown>> | undefined;
+}, {
+    userId: string;
+    permissions: readonly string[];
+    tenantId: string;
+    roles: readonly string[];
+    agentId?: string | undefined;
+    sessionId?: string | undefined;
+    governanceRole?: "admin" | "operator" | "both" | "trainer" | "consumer" | "reviewer" | undefined;
+    hierarchyLevel?: "agent" | "hitl" | "orch" | "metagoat" | "bot" | undefined;
+    attributes?: Readonly<Record<string, unknown>> | undefined;
+}>;
+/** TypeScript type inferred from the Zod schema */
+export type AuthContextType = z.infer<typeof authContextSchema>;
+/**
+ * Canonical hierarchy levels for agent/entity organization.
+ *
+ * The platform supports two hierarchy models that can be unified:
+ *
+ * **Named Hierarchy** (5 tiers, semantic):
+ * - HITL: Human-In-The-Loop (ultimate authority)
+ * - ORCH: Orchestrators (workflow coordination)
+ * - METAGOAT: Meta-agents (optimization/training)
+ * - AGENT: Domain specialists (task execution)
+ * - BOT: User-facing interfaces
+ *
+ * **Numbered Hierarchy** (9 tiers, granular):
+ * - L8: Mission stewardship (equivalent to HITL)
+ * - L7-L5: Strategic/organizational levels
+ * - L4-L3: Project/coordination levels (ORCH)
+ * - L2: Planning level (METAGOAT)
+ * - L1: Execution level (AGENT)
+ * - L0: Interface level (BOT)
+ *
+ * The canonical definition uses the named approach with numeric tiers
+ * for granularity within each named level.
+ */
+export type HierarchyLevel = 'hitl' | 'orch' | 'metagoat' | 'agent' | 'bot';
+/**
+ * Zod schema for HierarchyLevel validation.
+ */
+export declare const hierarchyLevelSchema: z.ZodEnum<["hitl", "orch", "metagoat", "agent", "bot"]>;
+/**
+ * Numeric tier mapping for hierarchy levels.
+ * Lower numbers = higher authority.
+ */
+export declare const HIERARCHY_TIERS: Readonly<Record<HierarchyLevel, number>>;
+/**
+ * Array of hierarchy levels in authority order (highest first).
+ */
+export declare const HIERARCHY_ORDER: readonly HierarchyLevel[];
+/**
+ * Configuration for a hierarchy level.
+ */
+export interface HierarchyLevelConfig {
+    /** The hierarchy level */
+    readonly level: HierarchyLevel;
+    /** Numeric tier (0 = highest authority) */
+    readonly tier: number;
+    /** Human-readable name */
+    readonly name: string;
+    /** Description of the level's responsibilities */
+    readonly description: string;
+    /** Scope of authority for this level */
+    readonly authorityScope: AuthorityScopeType;
+    /** Authority score (0-100, higher = more authority) */
+    readonly authority: number;
+    /** Levels this entity can delegate to */
+    readonly canDelegate: readonly HierarchyLevel[];
+    /** Level this entity reports to (null for HITL) */
+    readonly reportsTo: HierarchyLevel | null;
+    /** Maximum autonomy level (1-7) */
+    readonly maxAutonomyLevel: number;
+    /** Whether this level can train other entities */
+    readonly canTrainOthers: boolean;
+    /** Whether this level can approve other entities */
+    readonly canApproveOthers: boolean;
+    /** Whether human oversight is required for this level */
+    readonly requiresHumanOversight: boolean;
+    /** Minimum trust score required (0-1000) */
+    readonly minTrustScore: number;
+}
+/**
+ * Canonical hierarchy level configurations.
+ */
+export declare const HIERARCHY_LEVELS: Readonly<Record<HierarchyLevel, HierarchyLevelConfig>>;
+/**
+ * Zod schema for HierarchyLevelConfig.
+ */
+export declare const hierarchyLevelConfigSchema: z.ZodObject<{
+    level: z.ZodEnum<["hitl", "orch", "metagoat", "agent", "bot"]>;
+    tier: z.ZodNumber;
+    name: z.ZodString;
+    description: z.ZodString;
+    authorityScope: z.ZodLazy<z.ZodEnum<["governance", "coordination", "management", "execution", "interaction"]>>;
+    authority: z.ZodNumber;
+    canDelegate: z.ZodReadonly<z.ZodArray<z.ZodEnum<["hitl", "orch", "metagoat", "agent", "bot"]>, "many">>;
+    reportsTo: z.ZodNullable<z.ZodEnum<["hitl", "orch", "metagoat", "agent", "bot"]>>;
+    maxAutonomyLevel: z.ZodNumber;
+    canTrainOthers: z.ZodBoolean;
+    canApproveOthers: z.ZodBoolean;
+    requiresHumanOversight: z.ZodBoolean;
+    minTrustScore: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    minTrustScore: number;
+    level: "agent" | "hitl" | "orch" | "metagoat" | "bot";
+    tier: number;
+    authorityScope: "governance" | "coordination" | "management" | "execution" | "interaction";
+    authority: number;
+    canDelegate: readonly ("agent" | "hitl" | "orch" | "metagoat" | "bot")[];
+    reportsTo: "agent" | "hitl" | "orch" | "metagoat" | "bot" | null;
+    maxAutonomyLevel: number;
+    canTrainOthers: boolean;
+    canApproveOthers: boolean;
+    requiresHumanOversight: boolean;
+}, {
+    name: string;
+    description: string;
+    minTrustScore: number;
+    level: "agent" | "hitl" | "orch" | "metagoat" | "bot";
+    tier: number;
+    authorityScope: "governance" | "coordination" | "management" | "execution" | "interaction";
+    authority: number;
+    canDelegate: readonly ("agent" | "hitl" | "orch" | "metagoat" | "bot")[];
+    reportsTo: "agent" | "hitl" | "orch" | "metagoat" | "bot" | null;
+    maxAutonomyLevel: number;
+    canTrainOthers: boolean;
+    canApproveOthers: boolean;
+    requiresHumanOversight: boolean;
+}>;
+/**
+ * Authority scope types defining what kind of authority an entity has.
+ */
+export type AuthorityScopeType = 'governance' | 'coordination' | 'management' | 'execution' | 'interaction';
+/**
+ * Zod schema for AuthorityScopeType validation.
+ */
+export declare const authorityScopeTypeSchema: z.ZodEnum<["governance", "coordination", "management", "execution", "interaction"]>;
+/**
+ * Control actions that can be taken by governance rules.
+ */
+export type ControlAction = 'allow' | 'deny' | 'constrain' | 'clarify' | 'escalate' | 'log' | 'audit';
+/**
+ * Zod schema for ControlAction validation.
+ */
+export declare const controlActionSchema: z.ZodEnum<["allow", "deny", "constrain", "clarify", "escalate", "log", "audit"]>;
+/**
+ * Detailed authority scope definition.
+ *
+ * Defines the specific boundaries of an authority, including what namespaces,
+ * actions, resources, and capabilities fall under its purview.
+ */
+export interface AuthorityScope {
+    /** High-level type of authority */
+    readonly type: AuthorityScopeType;
+    /** Namespaces this authority applies to */
+    readonly namespaces: readonly string[];
+    /** Actions this authority can authorize */
+    readonly actions: readonly ControlAction[];
+    /** Resource patterns this authority applies to */
+    readonly resources: readonly string[];
+    /** Capabilities this authority can grant */
+    readonly capabilities: readonly string[];
+    /** Time-based restrictions */
+    readonly timeRestrictions?: AuthorityScopeTimeRestriction;
+    /** Geographic or context-based restrictions */
+    readonly contextRestrictions?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Time-based restrictions for an authority scope.
+ */
+export interface AuthorityScopeTimeRestriction {
+    /** Days of week when authority is valid (0=Sunday) */
+    readonly daysOfWeek?: readonly number[];
+    /** Start time (HH:MM format) */
+    readonly startTime?: string;
+    /** End time (HH:MM format) */
+    readonly endTime?: string;
+    /** Timezone for time restrictions */
+    readonly timezone?: string;
+}
+/**
+ * Zod schema for AuthorityScopeTimeRestriction.
+ */
+export declare const authorityScopeTimeRestrictionSchema: z.ZodObject<{
+    daysOfWeek: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodNumber, "many">>>;
+    startTime: z.ZodOptional<z.ZodString>;
+    endTime: z.ZodOptional<z.ZodString>;
+    timezone: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    startTime?: string | undefined;
+    endTime?: string | undefined;
+    daysOfWeek?: readonly number[] | undefined;
+    timezone?: string | undefined;
+}, {
+    startTime?: string | undefined;
+    endTime?: string | undefined;
+    daysOfWeek?: readonly number[] | undefined;
+    timezone?: string | undefined;
+}>;
+/**
+ * Zod schema for AuthorityScope.
+ */
+export declare const authorityScopeSchema: z.ZodObject<{
+    type: z.ZodEnum<["governance", "coordination", "management", "execution", "interaction"]>;
+    namespaces: z.ZodReadonly<z.ZodArray<z.ZodString, "many">>;
+    actions: z.ZodReadonly<z.ZodArray<z.ZodEnum<["allow", "deny", "constrain", "clarify", "escalate", "log", "audit"]>, "many">>;
+    resources: z.ZodReadonly<z.ZodArray<z.ZodString, "many">>;
+    capabilities: z.ZodReadonly<z.ZodArray<z.ZodString, "many">>;
+    timeRestrictions: z.ZodOptional<z.ZodObject<{
+        daysOfWeek: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodNumber, "many">>>;
+        startTime: z.ZodOptional<z.ZodString>;
+        endTime: z.ZodOptional<z.ZodString>;
+        timezone: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        startTime?: string | undefined;
+        endTime?: string | undefined;
+        daysOfWeek?: readonly number[] | undefined;
+        timezone?: string | undefined;
+    }, {
+        startTime?: string | undefined;
+        endTime?: string | undefined;
+        daysOfWeek?: readonly number[] | undefined;
+        timezone?: string | undefined;
+    }>>;
+    contextRestrictions: z.ZodOptional<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, "strip", z.ZodTypeAny, {
+    type: "governance" | "coordination" | "management" | "execution" | "interaction";
+    capabilities: readonly string[];
+    resources: readonly string[];
+    namespaces: readonly string[];
+    actions: readonly ("audit" | "deny" | "allow" | "constrain" | "clarify" | "escalate" | "log")[];
+    timeRestrictions?: {
+        startTime?: string | undefined;
+        endTime?: string | undefined;
+        daysOfWeek?: readonly number[] | undefined;
+        timezone?: string | undefined;
+    } | undefined;
+    contextRestrictions?: Readonly<Record<string, unknown>> | undefined;
+}, {
+    type: "governance" | "coordination" | "management" | "execution" | "interaction";
+    capabilities: readonly string[];
+    resources: readonly string[];
+    namespaces: readonly string[];
+    actions: readonly ("audit" | "deny" | "allow" | "constrain" | "clarify" | "escalate" | "log")[];
+    timeRestrictions?: {
+        startTime?: string | undefined;
+        endTime?: string | undefined;
+        daysOfWeek?: readonly number[] | undefined;
+        timezone?: string | undefined;
+    } | undefined;
+    contextRestrictions?: Readonly<Record<string, unknown>> | undefined;
+}>;
+/** TypeScript type inferred from the Zod schema */
+export type AuthorityScopeZodType = z.infer<typeof authorityScopeSchema>;
+/**
+ * Types of authority that can be held.
+ */
+export type AuthorityType = 'system' | 'role' | 'delegated' | 'temporary' | 'emergency';
+/**
+ * Zod schema for AuthorityType validation.
+ */
+export declare const authorityTypeSchema: z.ZodEnum<["system", "role", "delegated", "temporary", "emergency"]>;
+/**
+ * Complete authority definition.
+ *
+ * Represents a grant of authority to perform specific actions within
+ * defined scopes, with associated permissions and constraints.
+ */
+export interface Authority {
+    /** Unique identifier for this authority */
+    readonly authorityId: string;
+    /** Human-readable name */
+    readonly name: string;
+    /** Type of authority */
+    readonly type: AuthorityType;
+    /** Scope of this authority */
+    readonly scope: AuthorityScope;
+    /** Specific permissions granted */
+    readonly permissions: readonly Permission[];
+    /** Authority this was delegated from (if delegated) */
+    readonly delegatedFrom?: string;
+    /** Minimum trust level required to use this authority */
+    readonly requiredTrustLevel: number;
+    /** When this authority expires */
+    readonly expiresAt?: Date;
+    /** Whether this authority is currently active */
+    readonly active: boolean;
+    /** Audit metadata */
+    readonly audit: AuthorityAudit;
+}
+/**
+ * Permission granted by an authority.
+ */
+export interface Permission {
+    /** Unique identifier for this permission */
+    readonly permissionId: string;
+    /** Action this permission allows */
+    readonly action: string;
+    /** Resource this permission applies to */
+    readonly resource: string;
+    /** Conditions that must be met for the permission to apply */
+    readonly conditions?: Readonly<Record<string, unknown>>;
+    /** Whether the permission is granted (true) or denied (false) */
+    readonly granted: boolean;
+}
+/**
+ * Audit information for an authority.
+ */
+export interface AuthorityAudit {
+    /** When the authority was created */
+    readonly createdAt: Date;
+    /** Who created the authority */
+    readonly createdBy: string;
+    /** When the authority was last updated */
+    readonly updatedAt: Date;
+    /** Who last updated the authority */
+    readonly updatedBy: string;
+    /** When the authority was approved (if required) */
+    readonly approvedAt?: Date;
+    /** Who approved the authority */
+    readonly approvedBy?: string;
+}
+/**
+ * Zod schema for Permission.
+ */
+export declare const permissionSchema: z.ZodObject<{
+    permissionId: z.ZodString;
+    action: z.ZodString;
+    resource: z.ZodString;
+    conditions: z.ZodOptional<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    granted: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    action: string;
+    permissionId: string;
+    resource: string;
+    granted: boolean;
+    conditions?: Readonly<Record<string, unknown>> | undefined;
+}, {
+    action: string;
+    permissionId: string;
+    resource: string;
+    granted: boolean;
+    conditions?: Readonly<Record<string, unknown>> | undefined;
+}>;
+/**
+ * Zod schema for AuthorityAudit.
+ */
+export declare const authorityAuditSchema: z.ZodObject<{
+    createdAt: z.ZodDate;
+    createdBy: z.ZodString;
+    updatedAt: z.ZodDate;
+    updatedBy: z.ZodString;
+    approvedAt: z.ZodOptional<z.ZodDate>;
+    approvedBy: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    createdAt: Date;
+    updatedAt: Date;
+    createdBy: string;
+    updatedBy: string;
+    approvedBy?: string | undefined;
+    approvedAt?: Date | undefined;
+}, {
+    createdAt: Date;
+    updatedAt: Date;
+    createdBy: string;
+    updatedBy: string;
+    approvedBy?: string | undefined;
+    approvedAt?: Date | undefined;
+}>;
+/**
+ * Zod schema for Authority.
+ */
+export declare const authoritySchema: z.ZodObject<{
+    authorityId: z.ZodString;
+    name: z.ZodString;
+    type: z.ZodEnum<["system", "role", "delegated", "temporary", "emergency"]>;
+    scope: z.ZodObject<{
+        type: z.ZodEnum<["governance", "coordination", "management", "execution", "interaction"]>;
+        namespaces: z.ZodReadonly<z.ZodArray<z.ZodString, "many">>;
+        actions: z.ZodReadonly<z.ZodArray<z.ZodEnum<["allow", "deny", "constrain", "clarify", "escalate", "log", "audit"]>, "many">>;
+        resources: z.ZodReadonly<z.ZodArray<z.ZodString, "many">>;
+        capabilities: z.ZodReadonly<z.ZodArray<z.ZodString, "many">>;
+        timeRestrictions: z.ZodOptional<z.ZodObject<{
+            daysOfWeek: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodNumber, "many">>>;
+            startTime: z.ZodOptional<z.ZodString>;
+            endTime: z.ZodOptional<z.ZodString>;
+            timezone: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            startTime?: string | undefined;
+            endTime?: string | undefined;
+            daysOfWeek?: readonly number[] | undefined;
+            timezone?: string | undefined;
+        }, {
+            startTime?: string | undefined;
+            endTime?: string | undefined;
+            daysOfWeek?: readonly number[] | undefined;
+            timezone?: string | undefined;
+        }>>;
+        contextRestrictions: z.ZodOptional<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "governance" | "coordination" | "management" | "execution" | "interaction";
+        capabilities: readonly string[];
+        resources: readonly string[];
+        namespaces: readonly string[];
+        actions: readonly ("audit" | "deny" | "allow" | "constrain" | "clarify" | "escalate" | "log")[];
+        timeRestrictions?: {
+            startTime?: string | undefined;
+            endTime?: string | undefined;
+            daysOfWeek?: readonly number[] | undefined;
+            timezone?: string | undefined;
+        } | undefined;
+        contextRestrictions?: Readonly<Record<string, unknown>> | undefined;
+    }, {
+        type: "governance" | "coordination" | "management" | "execution" | "interaction";
+        capabilities: readonly string[];
+        resources: readonly string[];
+        namespaces: readonly string[];
+        actions: readonly ("audit" | "deny" | "allow" | "constrain" | "clarify" | "escalate" | "log")[];
+        timeRestrictions?: {
+            startTime?: string | undefined;
+            endTime?: string | undefined;
+            daysOfWeek?: readonly number[] | undefined;
+            timezone?: string | undefined;
+        } | undefined;
+        contextRestrictions?: Readonly<Record<string, unknown>> | undefined;
+    }>;
+    permissions: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        permissionId: z.ZodString;
+        action: z.ZodString;
+        resource: z.ZodString;
+        conditions: z.ZodOptional<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        granted: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        action: string;
+        permissionId: string;
+        resource: string;
+        granted: boolean;
+        conditions?: Readonly<Record<string, unknown>> | undefined;
+    }, {
+        action: string;
+        permissionId: string;
+        resource: string;
+        granted: boolean;
+        conditions?: Readonly<Record<string, unknown>> | undefined;
+    }>, "many">>;
+    delegatedFrom: z.ZodOptional<z.ZodString>;
+    requiredTrustLevel: z.ZodNumber;
+    expiresAt: z.ZodOptional<z.ZodDate>;
+    active: z.ZodBoolean;
+    audit: z.ZodObject<{
+        createdAt: z.ZodDate;
+        createdBy: z.ZodString;
+        updatedAt: z.ZodDate;
+        updatedBy: z.ZodString;
+        approvedAt: z.ZodOptional<z.ZodDate>;
+        approvedBy: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        createdAt: Date;
+        updatedAt: Date;
+        createdBy: string;
+        updatedBy: string;
+        approvedBy?: string | undefined;
+        approvedAt?: Date | undefined;
+    }, {
+        createdAt: Date;
+        updatedAt: Date;
+        createdBy: string;
+        updatedBy: string;
+        approvedBy?: string | undefined;
+        approvedAt?: Date | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    active: boolean;
+    audit: {
+        createdAt: Date;
+        updatedAt: Date;
+        createdBy: string;
+        updatedBy: string;
+        approvedBy?: string | undefined;
+        approvedAt?: Date | undefined;
+    };
+    type: "delegated" | "system" | "role" | "temporary" | "emergency";
+    name: string;
+    scope: {
+        type: "governance" | "coordination" | "management" | "execution" | "interaction";
+        capabilities: readonly string[];
+        resources: readonly string[];
+        namespaces: readonly string[];
+        actions: readonly ("audit" | "deny" | "allow" | "constrain" | "clarify" | "escalate" | "log")[];
+        timeRestrictions?: {
+            startTime?: string | undefined;
+            endTime?: string | undefined;
+            daysOfWeek?: readonly number[] | undefined;
+            timezone?: string | undefined;
+        } | undefined;
+        contextRestrictions?: Readonly<Record<string, unknown>> | undefined;
+    };
+    permissions: readonly {
+        action: string;
+        permissionId: string;
+        resource: string;
+        granted: boolean;
+        conditions?: Readonly<Record<string, unknown>> | undefined;
+    }[];
+    authorityId: string;
+    requiredTrustLevel: number;
+    expiresAt?: Date | undefined;
+    delegatedFrom?: string | undefined;
+}, {
+    active: boolean;
+    audit: {
+        createdAt: Date;
+        updatedAt: Date;
+        createdBy: string;
+        updatedBy: string;
+        approvedBy?: string | undefined;
+        approvedAt?: Date | undefined;
+    };
+    type: "delegated" | "system" | "role" | "temporary" | "emergency";
+    name: string;
+    scope: {
+        type: "governance" | "coordination" | "management" | "execution" | "interaction";
+        capabilities: readonly string[];
+        resources: readonly string[];
+        namespaces: readonly string[];
+        actions: readonly ("audit" | "deny" | "allow" | "constrain" | "clarify" | "escalate" | "log")[];
+        timeRestrictions?: {
+            startTime?: string | undefined;
+            endTime?: string | undefined;
+            daysOfWeek?: readonly number[] | undefined;
+            timezone?: string | undefined;
+        } | undefined;
+        contextRestrictions?: Readonly<Record<string, unknown>> | undefined;
+    };
+    permissions: readonly {
+        action: string;
+        permissionId: string;
+        resource: string;
+        granted: boolean;
+        conditions?: Readonly<Record<string, unknown>> | undefined;
+    }[];
+    authorityId: string;
+    requiredTrustLevel: number;
+    expiresAt?: Date | undefined;
+    delegatedFrom?: string | undefined;
+}>;
+/** TypeScript type inferred from the Zod schema */
+export type AuthorityZodType = z.infer<typeof authoritySchema>;
+/**
+ * Gets the numeric tier for a hierarchy level.
+ *
+ * @param level - The hierarchy level
+ * @returns The numeric tier (0 = highest authority)
+ */
+export declare function getHierarchyTier(level: HierarchyLevel): number;
+/**
+ * Gets the configuration for a hierarchy level.
+ *
+ * @param level - The hierarchy level
+ * @returns The level configuration
+ */
+export declare function getHierarchyLevelConfig(level: HierarchyLevel): HierarchyLevelConfig;
+/**
+ * Checks if one hierarchy level has higher authority than another.
+ *
+ * @param a - First hierarchy level
+ * @param b - Second hierarchy level
+ * @returns True if a has higher authority than b
+ */
+export declare function isHigherAuthority(a: HierarchyLevel, b: HierarchyLevel): boolean;
+/**
+ * Checks if a hierarchy level can delegate to another level.
+ *
+ * @param from - The delegating level
+ * @param to - The target level
+ * @returns True if delegation is allowed
+ */
+export declare function canDelegate(from: HierarchyLevel, to: HierarchyLevel): boolean;
+/**
+ * Gets the reporting chain for a hierarchy level.
+ *
+ * @param level - The starting hierarchy level
+ * @returns Array of levels in the reporting chain (from top to starting level)
+ */
+export declare function getReportingChain(level: HierarchyLevel): HierarchyLevel[];
+/**
+ * Checks if a trust score meets the minimum requirement for a hierarchy level.
+ *
+ * @param level - The hierarchy level
+ * @param trustScore - The trust score to check (0-1000)
+ * @returns True if the trust score meets the minimum
+ */
+export declare function meetsMinimumTrust(level: HierarchyLevel, trustScore: number): boolean;
+/**
+ * Creates an allowed authorization result.
+ *
+ * @param options - Optional parameters for the result
+ * @returns An allowed AuthorizationResult
+ */
+export declare function createAllowedResult(options?: {
+    reason?: string;
+    matchedRoles?: string[];
+    matchedPermissions?: string[];
+    constraints?: AuthorizationConstraints;
+    expiresAt?: Date;
+}): AuthorizationResult;
+/**
+ * Creates a denied authorization result for trust/policy denials.
+ *
+ * @param denialReason - The reason for denial (from DenialReason enum)
+ * @param options - Optional parameters for the result
+ * @returns A denied AuthorizationResult
+ */
+export declare function createDeniedResult(denialReason: DenialReason, options?: {
+    reason?: string;
+    remediations?: string[];
+}): AuthorizationResult;
+/**
+ * Creates a denied authorization result for governance/RBAC denials.
+ *
+ * @param governanceDenialReason - The reason for denial (from GovernanceDenialReason enum)
+ * @param options - Optional parameters for the result
+ * @returns A denied AuthorizationResult
+ */
+export declare function createGovernanceDeniedResult(governanceDenialReason: GovernanceDenialReason, options?: {
+    reason?: string;
+    remediations?: string[];
+}): AuthorizationResult;
+/**
+ * Type guard to check if a value is a valid HierarchyLevel.
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid HierarchyLevel
+ */
+export declare function isHierarchyLevel(value: unknown): value is HierarchyLevel;
+/**
+ * Type guard to check if a value is a valid AuthorityScopeType.
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid AuthorityScopeType
+ */
+export declare function isAuthorityScopeType(value: unknown): value is AuthorityScopeType;
+/**
+ * Maps numbered hierarchy levels (L0-L8) to canonical named levels.
+ *
+ * @deprecated Use HierarchyLevel directly. This is for migration only.
+ */
+export declare const NUMBERED_LEVEL_TO_NAMED: Readonly<Record<string, HierarchyLevel>>;
+/**
+ * Converts a numbered level to a named hierarchy level.
+ *
+ * @deprecated Use HierarchyLevel directly. This is for migration only.
+ * @param numberedLevel - Numbered level string (L0-L8)
+ * @returns The corresponding named HierarchyLevel
+ */
+export declare function numberedToNamedLevel(numberedLevel: string): HierarchyLevel;
+//# sourceMappingURL=governance.d.ts.map