@capabilityhostprotocol/types 0.1.0

package/dist/legacy.d.mts

@@ -0,0 +1,542 @@
+/**
+ * Risk Classification Types
+ *
+ * Risk classes determine the level of governance scrutiny applied to a capability.
+ * Higher risk classes require stronger assurance and more evidence.
+ *
+ * @module risk
+ */
+/**
+ * Risk classification for capabilities.
+ *
+ * Ordered from lowest to highest risk:
+ * - INFORMATIONAL: Read-only, no side effects
+ * - LOW: Minor side effects, easily reversible
+ * - MEDIUM: Moderate side effects, may require coordination
+ * - HIGH: Significant side effects, requires authorization
+ * - CRITICAL: System-wide impact, requires multi-party approval
+ */
+type RiskClass = "informational" | "low" | "medium" | "high" | "critical";
+/**
+ * Risk class values as a const array for iteration.
+ */
+declare const RISK_CLASSES: readonly ["informational", "low", "medium", "high", "critical"];
+/**
+ * Risk class numeric order for comparison.
+ */
+declare const RISK_CLASS_ORDER: Record<RiskClass, number>;
+/**
+ * Compare two risk classes.
+ * @returns negative if a < b, 0 if equal, positive if a > b
+ */
+declare function compareRiskClass(a: RiskClass, b: RiskClass): number;
+/**
+ * Check if a risk class is at least as high as another.
+ */
+declare function isRiskAtLeast(actual: RiskClass, required: RiskClass): boolean;
+
+/**
+ * Assurance Tier Types
+ *
+ * Three-tier assurance model for execution trust.
+ * Each tier provides increasing levels of confidence in execution evidence.
+ *
+ * @module assurance
+ */
+/**
+ * Assurance tiers for execution trust.
+ *
+ * - S1: Observational - Execution was observed by the host
+ * - S2: Structural - Deterministic replay is possible
+ * - S3: Attested - Cryptographic proof with verified environment
+ */
+type AssuranceTier = "S1" | "S2" | "S3";
+/**
+ * Assurance tier values as a const array.
+ */
+declare const ASSURANCE_TIERS: readonly ["S1", "S2", "S3"];
+/**
+ * Human-readable names for assurance tiers.
+ */
+declare const ASSURANCE_TIER_DISPLAY_NAMES: Record<AssuranceTier, string>;
+/**
+ * Assurance tier numeric order for comparison.
+ */
+declare const ASSURANCE_TIER_ORDER: Record<AssuranceTier, number>;
+/**
+ * Compare two assurance tiers.
+ * @returns negative if a < b, 0 if equal, positive if a > b
+ */
+declare function compareAssuranceTier(a: AssuranceTier, b: AssuranceTier): number;
+/**
+ * Check if an assurance tier meets a minimum requirement.
+ */
+declare function meetsAssuranceTier(actual: AssuranceTier, required: AssuranceTier): boolean;
+/**
+ * Get the display name for an assurance tier.
+ */
+declare function getAssuranceTierDisplayName(tier: AssuranceTier): string;
+
+/**
+ * Evidence Types
+ *
+ * Evidence is the immutable record of capability execution.
+ * Every capability execution produces one or more Evidence records.
+ * These form the basis of the capability graph and audit trail.
+ *
+ * @module evidence
+ */
+
+/**
+ * Evidence types for capability execution tracking.
+ *
+ * Every capability execution produces evidence. The type indicates
+ * what kind of execution event occurred.
+ */
+type EvidenceType = "execution_started" | "execution_completed" | "execution_failed" | "execution_denied" | "execution_aborted" | "invocation_received" | "invocation_validated" | "invocation_rejected" | "entitlement_checked" | "entitlement_granted" | "entitlement_denied" | "invariant_checked" | "invariant_passed" | "invariant_failed" | "retry_attempted" | "retry_exhausted" | "timeout_exceeded" | "circuit_opened" | "circuit_closed" | "rate_limited" | "assurance_derived" | "assurance_degraded" | "lineage_traced" | "causal_link_created";
+/**
+ * All evidence types as a const array for iteration.
+ */
+declare const EVIDENCE_TYPES: readonly ["execution_started", "execution_completed", "execution_failed", "execution_denied", "execution_aborted", "invocation_received", "invocation_validated", "invocation_rejected", "entitlement_checked", "entitlement_granted", "entitlement_denied", "invariant_checked", "invariant_passed", "invariant_failed", "retry_attempted", "retry_exhausted", "timeout_exceeded", "circuit_opened", "circuit_closed", "rate_limited", "assurance_derived", "assurance_degraded", "lineage_traced", "causal_link_created"];
+/**
+ * Immutable evidence record for capability execution.
+ *
+ * This is the canonical CHP evidence structure that must be
+ * faithfully serialized/deserialized across language boundaries.
+ */
+interface Evidence {
+    /** Unique identifier for this evidence */
+    evidence_id: string;
+    /** Type of evidence (from EvidenceType) */
+    evidence_type: EvidenceType;
+    /** The capability that produced this evidence */
+    capability_id: string;
+    /** ISO-8601 timestamp when the evidence was created */
+    timestamp: string;
+    /** The subject (user/agent) that triggered execution */
+    subject_id?: string | null;
+    /** Links related evidence across executions */
+    correlation_id?: string | null;
+    /** Trust level of this evidence */
+    assurance_tier: AssuranceTier;
+    /** Additional context-specific data */
+    payload: Record<string, unknown>;
+    /** W3C Trace Context trace ID for distributed tracing */
+    trace_id?: string | null;
+}
+/**
+ * Create a new evidence record.
+ *
+ * @param params - Evidence creation parameters
+ * @returns A new Evidence object
+ */
+declare function createEvidence(params: {
+    evidence_type: EvidenceType;
+    capability_id: string;
+    subject_id?: string | null;
+    correlation_id?: string | null;
+    assurance_tier?: AssuranceTier;
+    payload?: Record<string, unknown>;
+    trace_id?: string | null;
+}): Evidence;
+/**
+ * Validate that an object conforms to the Evidence interface.
+ */
+declare function isEvidence(obj: unknown): obj is Evidence;
+
+/**
+ * Invariant Types
+ *
+ * Invariants are constraints that must hold for a capability to execute.
+ * They are checked at the invocation boundary or during execution.
+ *
+ * @module invariants
+ */
+/**
+ * Classification of invariant constraints.
+ *
+ * Determines when and how invariants are checked and enforced.
+ *
+ * - STRUCTURAL: Code/schema correctness (compile-time checkable)
+ * - ENVIRONMENTAL: Runtime environment constraints
+ * - DATA: Input/output data validation
+ * - TEMPORAL: Time-based constraints (deadlines, ordering)
+ * - CAUSAL: Dependency and causality constraints
+ */
+type InvariantClass = "structural" | "environmental" | "data" | "temporal" | "causal";
+/**
+ * Invariant classes as a const array.
+ */
+declare const INVARIANT_CLASSES: readonly ["structural", "environmental", "data", "temporal", "causal"];
+/**
+ * Who is responsible for enforcing an invariant.
+ *
+ * - HOST: The capability host enforces at invocation boundary
+ * - RUNTIME: Enforced during capability execution
+ * - SUBSTRATE: Enforced by underlying infrastructure (e.g., Zenoh)
+ * - DECLARATIVE: Declared but not actively enforced
+ */
+type EnforcementResponsibility = "host" | "runtime" | "substrate" | "declarative";
+/**
+ * What happens when an invariant fails.
+ *
+ * - DENY: Prevent execution entirely
+ * - ABORT: Stop execution and rollback if possible
+ * - WARN: Log warning but allow execution
+ * - DEGRADE: Continue with reduced assurance
+ */
+type FailureBehavior = "deny" | "abort" | "warn" | "degrade";
+/**
+ * A declared invariant constraint for a capability.
+ *
+ * This is the canonical CHP invariant structure that must be
+ * faithfully serialized/deserialized across language boundaries.
+ */
+interface DeclaredInvariant {
+    /** Unique identifier for this invariant */
+    invariant_id: string;
+    /** Type of invariant (structural, temporal, etc.) */
+    invariant_class: InvariantClass;
+    /** Who enforces this invariant */
+    enforcement: EnforcementResponsibility;
+    /** What happens on failure */
+    failure_behavior: FailureBehavior;
+    /** Human-readable description */
+    description: string;
+    /** Invariant-specific configuration */
+    parameters: Record<string, unknown>;
+}
+/**
+ * Create a new declared invariant.
+ */
+declare function createDeclaredInvariant(params: {
+    invariant_id: string;
+    invariant_class: InvariantClass;
+    enforcement?: EnforcementResponsibility;
+    failure_behavior?: FailureBehavior;
+    description?: string;
+    parameters?: Record<string, unknown>;
+}): DeclaredInvariant;
+/**
+ * Validate that an object conforms to the DeclaredInvariant interface.
+ */
+declare function isDeclaredInvariant(obj: unknown): obj is DeclaredInvariant;
+
+/**
+ * Context Types
+ *
+ * Context types for subject (user/agent) and invocation tracking.
+ * These provide the "who" and "what" for capability execution.
+ *
+ * @module context
+ */
+/**
+ * Context about the subject (user/agent) invoking a capability.
+ *
+ * Subjects are the actors in the system - they invoke capabilities
+ * and are tracked for authorization and audit purposes.
+ */
+interface SubjectContext {
+    /** Unique identifier for the subject */
+    subject_id: string;
+    /** Type of subject (user, agent, service) */
+    subject_type: string;
+    /** List of entitlements the subject holds */
+    entitlements: string[];
+    /** Additional subject-specific data */
+    metadata: Record<string, unknown>;
+}
+/**
+ * Create a new subject context.
+ */
+declare function createSubjectContext(params: {
+    subject_id: string;
+    subject_type?: string;
+    entitlements?: string[];
+    metadata?: Record<string, unknown>;
+}): SubjectContext;
+/**
+ * Check if a subject has a specific entitlement.
+ */
+declare function hasEntitlement(subject: SubjectContext, entitlement: string): boolean;
+/**
+ * Context for a capability invocation.
+ *
+ * Provides access to subject information, correlation tracking,
+ * and execution metadata during capability execution.
+ */
+interface InvocationContext {
+    /** Unique ID for this invocation */
+    invocation_id: string;
+    /** The capability being invoked */
+    capability_id: string;
+    /** The subject invoking the capability */
+    subject: SubjectContext;
+    /** For linking related invocations */
+    correlation_id: string | null;
+    /** W3C Trace Context trace ID */
+    trace_id: string | null;
+    /** If this is a child invocation */
+    parent_invocation_id: string | null;
+    /** ISO-8601 timestamp when the invocation started */
+    timestamp: string;
+    /** Additional context data */
+    metadata: Record<string, unknown>;
+}
+/**
+ * Create a new invocation context.
+ */
+declare function createInvocationContext(params: {
+    capability_id: string;
+    subject: SubjectContext;
+    correlation_id?: string | null;
+    trace_id?: string | null;
+    parent_invocation_id?: string | null;
+    metadata?: Record<string, unknown>;
+}): InvocationContext;
+/**
+ * Outcome of a capability execution.
+ *
+ * - SUCCESS: Execution completed successfully
+ * - FAILURE: Execution failed with an error
+ * - DENIED: Execution was denied (entitlement/invariant)
+ * - TIMEOUT: Execution exceeded time limit
+ * - ABORTED: Execution was aborted (e.g., circuit breaker)
+ */
+type ExecutionOutcome = "success" | "failure" | "denied" | "timeout" | "aborted";
+/**
+ * Execution outcomes as a const array.
+ */
+declare const EXECUTION_OUTCOMES: readonly ["success", "failure", "denied", "timeout", "aborted"];
+
+/**
+ * Governance Types
+ *
+ * Governance layer types for capability execution control.
+ * These determine how governance violations are handled.
+ *
+ * @module governance
+ */
+
+/**
+ * Mode of governance enforcement.
+ *
+ * Determines how governance violations are handled.
+ *
+ * - ENFORCE: Violations block execution (production)
+ * - AUDIT: Violations are logged but allowed (testing)
+ * - DISABLED: No governance checks (development only)
+ * - SHADOW: Parallel check without blocking (migration)
+ */
+type GovernanceMode = "enforce" | "audit" | "disabled" | "shadow";
+/**
+ * Governance modes as a const array.
+ */
+declare const GOVERNANCE_MODES: readonly ["enforce", "audit", "disabled", "shadow"];
+/**
+ * Check if a governance mode blocks execution on violations.
+ */
+declare function blocksExecution(mode: GovernanceMode): boolean;
+/**
+ * Check if a governance mode emits evidence.
+ */
+declare function emitsEvidence(mode: GovernanceMode): boolean;
+/**
+ * Execution context for governed capabilities.
+ *
+ * Provides access to subject information, governance state, evidence emission,
+ * and execution metadata during capability execution.
+ */
+interface GovernedContext {
+    /** Unique ID for this invocation */
+    invocation_id: string;
+    /** The capability being invoked */
+    capability_id: string;
+    /** The subject (user/agent) invoking */
+    subject: SubjectContext;
+    /** For linking related invocations */
+    correlation_id: string;
+    /** W3C Trace Context trace ID */
+    trace_id: string | null;
+    /** Active enforcement mode */
+    governance_mode: GovernanceMode;
+    /** Risk classification of the capability */
+    risk_class: RiskClass;
+    /** Required assurance tier */
+    minimum_tier: AssuranceTier;
+    /** Active invariants */
+    invariants: DeclaredInvariant[];
+    /** Evidence emitted during execution */
+    evidence: Evidence[];
+    /** Additional context data */
+    metadata: Record<string, unknown>;
+    /** ISO-8601 timestamp when context was created */
+    started_at: string;
+}
+/**
+ * Create a new governed context.
+ */
+declare function createGovernedContext(params: {
+    capability_id: string;
+    subject: SubjectContext;
+    governance_mode?: GovernanceMode;
+    risk_class?: RiskClass;
+    minimum_tier?: AssuranceTier;
+    correlation_id?: string | null;
+    trace_id?: string | null;
+    invariants?: DeclaredInvariant[];
+    metadata?: Record<string, unknown>;
+}): GovernedContext;
+/**
+ * Emit evidence within a governed context.
+ * Mutates the context by appending to evidence array.
+ */
+declare function emitEvidence(ctx: GovernedContext, evidence_type: EvidenceType, payload?: Record<string, unknown>, assurance_tier?: AssuranceTier): Evidence;
+/**
+ * Create a child context for invoking another capability.
+ * Maintains correlation and trace context.
+ */
+declare function createChildContext(parent: GovernedContext, capability_id: string): GovernedContext;
+/**
+ * Calculate elapsed time in milliseconds.
+ */
+declare function elapsedMs(ctx: GovernedContext): number;
+/**
+ * Configuration for governance behavior.
+ */
+interface GovernanceConfig {
+    /** Default enforcement mode */
+    default_mode: GovernanceMode;
+    /** Whether a subject is always required */
+    require_subject: boolean;
+    /** Whether to emit evidence */
+    emit_evidence: boolean;
+    /** Whether to emit evidence for denials */
+    audit_denials: boolean;
+    /** Default assurance tier */
+    default_tier: AssuranceTier;
+}
+/**
+ * Create default governance configuration.
+ */
+declare function createGovernanceConfig(overrides?: Partial<GovernanceConfig>): GovernanceConfig;
+/**
+ * Development environment configuration.
+ */
+declare const DEVELOPMENT_CONFIG: GovernanceConfig;
+/**
+ * Production environment configuration.
+ */
+declare const PRODUCTION_CONFIG: GovernanceConfig;
+/**
+ * Testing environment configuration.
+ */
+declare const TESTING_CONFIG: GovernanceConfig;
+
+/**
+ * Capability Declaration Types
+ *
+ * Capabilities are the units of authority in CHP.
+ * This module defines the canonical capability declaration structure.
+ *
+ * @module capability
+ */
+
+/**
+ * Metadata for a declared capability.
+ *
+ * This is the canonical record of what a capability is, what it can do,
+ * and what governance applies to it.
+ */
+interface CapabilityDeclaration {
+    /** Unique capability identifier (e.g., "payment.process") */
+    name: string;
+    /** Semantic version string (e.g., "1.0.0") */
+    version: string;
+    /** Risk classification (INFORMATIONAL to CRITICAL) */
+    risk_class: RiskClass;
+    /** Human-readable description */
+    description: string;
+    /** Constraints that must hold for execution */
+    invariants: DeclaredInvariant[];
+    /** Evidence types this capability produces */
+    evidence_types: EvidenceType[];
+    /** Whether invocation requires authorization */
+    require_entitlement: boolean;
+    /** Minimum assurance tier for execution */
+    minimum_tier: AssuranceTier;
+    /** Team or individual responsible */
+    owner: string | null;
+    /** Categorization tags */
+    tags: string[];
+}
+/**
+ * Get the full capability identifier with version.
+ */
+declare function getCapabilityId(decl: CapabilityDeclaration): string;
+/**
+ * Create a new capability declaration.
+ */
+declare function createCapabilityDeclaration(params: {
+    name: string;
+    version?: string;
+    risk_class?: RiskClass;
+    description?: string;
+    invariants?: DeclaredInvariant[];
+    evidence_types?: EvidenceType[];
+    require_entitlement?: boolean;
+    minimum_tier?: AssuranceTier;
+    owner?: string | null;
+    tags?: string[];
+}): CapabilityDeclaration;
+/**
+ * Validate that an object conforms to the CapabilityDeclaration interface.
+ */
+declare function isCapabilityDeclaration(obj: unknown): obj is CapabilityDeclaration;
+/**
+ * Supported invocation modes for a capability.
+ */
+type InvocationMode = "sync" | "async" | "stream" | "fire_and_forget";
+/**
+ * Invocation modes as a const array.
+ */
+declare const INVOCATION_MODES: readonly ["sync", "async", "stream", "fire_and_forget"];
+/**
+ * Host identity for capability hosting.
+ * Identifies where capabilities are hosted.
+ */
+interface HostIdentity {
+    /** Unique host identifier */
+    host_id: string;
+    /** Host type (server, edge, agent, etc.) */
+    host_type: string;
+    /** Host version/build */
+    version: string;
+    /** Environment (production, staging, development) */
+    environment: string;
+    /** Additional host metadata */
+    metadata: Record<string, unknown>;
+}
+/**
+ * Create a new host identity.
+ */
+declare function createHostIdentity(params: {
+    host_id: string;
+    host_type?: string;
+    version?: string;
+    environment?: string;
+    metadata?: Record<string, unknown>;
+}): HostIdentity;
+
+/**
+ * Legacy/internal TypeScript types for pre-v0.1 CHP work.
+ *
+ * These exports are retained for internal packages that still use the older
+ * mesh/governance model. They are not the public CHP v0.1 protocol surface.
+ *
+ * @packageDocumentation
+ */
+
+declare const LEGACY_CHP_VERSION = "1.0";
+
+export { ASSURANCE_TIERS, ASSURANCE_TIER_DISPLAY_NAMES, ASSURANCE_TIER_ORDER, type AssuranceTier, type CapabilityDeclaration, DEVELOPMENT_CONFIG, type DeclaredInvariant, EVIDENCE_TYPES, EXECUTION_OUTCOMES, type EnforcementResponsibility, type Evidence, type EvidenceType, type ExecutionOutcome, type FailureBehavior, GOVERNANCE_MODES, type GovernanceConfig, type GovernanceMode, type GovernedContext, type HostIdentity, INVARIANT_CLASSES, INVOCATION_MODES, type InvariantClass, type InvocationContext, type InvocationMode, LEGACY_CHP_VERSION, PRODUCTION_CONFIG, RISK_CLASSES, RISK_CLASS_ORDER, type RiskClass, type SubjectContext, TESTING_CONFIG, blocksExecution, compareAssuranceTier, compareRiskClass, createCapabilityDeclaration, createChildContext, createDeclaredInvariant, createEvidence, createGovernanceConfig, createGovernedContext, createHostIdentity, createInvocationContext, createSubjectContext, elapsedMs, emitEvidence, emitsEvidence, getAssuranceTierDisplayName, getCapabilityId, hasEntitlement, isCapabilityDeclaration, isDeclaredInvariant, isEvidence, isRiskAtLeast, meetsAssuranceTier };