@capabilityhostprotocol/types 0.1.0

package/src/governance.ts

@@ -0,0 +1,252 @@
+/**
+ * Governance Types
+ *
+ * Governance layer types for capability execution control.
+ * These determine how governance violations are handled.
+ *
+ * @module governance
+ */
+
+import type { AssuranceTier } from "./assurance.js";
+import type { RiskClass } from "./risk.js";
+import type { DeclaredInvariant } from "./invariants.js";
+import type { SubjectContext } from "./context.js";
+import type { Evidence, EvidenceType } from "./evidence.js";
+import { createEvidence } from "./evidence.js";
+
+/**
+ * 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)
+ */
+export type GovernanceMode = "enforce" | "audit" | "disabled" | "shadow";
+
+/**
+ * Governance modes as a const array.
+ */
+export const GOVERNANCE_MODES = [
+  "enforce",
+  "audit",
+  "disabled",
+  "shadow",
+] as const;
+
+/**
+ * Check if a governance mode blocks execution on violations.
+ */
+export function blocksExecution(mode: GovernanceMode): boolean {
+  return mode === "enforce";
+}
+
+/**
+ * Check if a governance mode emits evidence.
+ */
+export function emitsEvidence(mode: GovernanceMode): boolean {
+  return mode !== "disabled";
+}
+
+/**
+ * Execution context for governed capabilities.
+ *
+ * Provides access to subject information, governance state, evidence emission,
+ * and execution metadata during capability execution.
+ */
+export 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.
+ */
+export 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 {
+  return {
+    invocation_id: crypto.randomUUID(),
+    capability_id: params.capability_id,
+    subject: params.subject,
+    correlation_id: params.correlation_id ?? crypto.randomUUID(),
+    trace_id: params.trace_id ?? null,
+    governance_mode: params.governance_mode ?? "enforce",
+    risk_class: params.risk_class ?? "medium",
+    minimum_tier: params.minimum_tier ?? "S1",
+    invariants: params.invariants ?? [],
+    evidence: [],
+    metadata: params.metadata ?? {},
+    started_at: new Date().toISOString(),
+  };
+}
+
+/**
+ * Emit evidence within a governed context.
+ * Mutates the context by appending to evidence array.
+ */
+export function emitEvidence(
+  ctx: GovernedContext,
+  evidence_type: EvidenceType,
+  payload?: Record<string, unknown>,
+  assurance_tier?: AssuranceTier
+): Evidence {
+  const evidence = createEvidence({
+    evidence_type,
+    capability_id: ctx.capability_id,
+    subject_id: ctx.subject.subject_id,
+    correlation_id: ctx.correlation_id,
+    assurance_tier: assurance_tier ?? ctx.minimum_tier,
+    payload: payload ?? {},
+    trace_id: ctx.trace_id,
+  });
+  ctx.evidence.push(evidence);
+  return evidence;
+}
+
+/**
+ * Create a child context for invoking another capability.
+ * Maintains correlation and trace context.
+ */
+export function createChildContext(
+  parent: GovernedContext,
+  capability_id: string
+): GovernedContext {
+  return {
+    invocation_id: crypto.randomUUID(),
+    capability_id,
+    subject: parent.subject,
+    correlation_id: parent.correlation_id,
+    trace_id: parent.trace_id,
+    governance_mode: parent.governance_mode,
+    risk_class: parent.risk_class,
+    minimum_tier: parent.minimum_tier,
+    invariants: [],
+    evidence: [],
+    metadata: {
+      ...parent.metadata,
+      parent_invocation_id: parent.invocation_id,
+    },
+    started_at: new Date().toISOString(),
+  };
+}
+
+/**
+ * Calculate elapsed time in milliseconds.
+ */
+export function elapsedMs(ctx: GovernedContext): number {
+  const started = new Date(ctx.started_at).getTime();
+  return Date.now() - started;
+}
+
+/**
+ * Configuration for governance behavior.
+ */
+export 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.
+ */
+export function createGovernanceConfig(
+  overrides?: Partial<GovernanceConfig>
+): GovernanceConfig {
+  return {
+    default_mode: "enforce",
+    require_subject: true,
+    emit_evidence: true,
+    audit_denials: true,
+    default_tier: "S1",
+    ...overrides,
+  };
+}
+
+/**
+ * Development environment configuration.
+ */
+export const DEVELOPMENT_CONFIG: GovernanceConfig = {
+  default_mode: "audit",
+  require_subject: false,
+  emit_evidence: true,
+  audit_denials: true,
+  default_tier: "S1",
+};
+
+/**
+ * Production environment configuration.
+ */
+export const PRODUCTION_CONFIG: GovernanceConfig = {
+  default_mode: "enforce",
+  require_subject: true,
+  emit_evidence: true,
+  audit_denials: true,
+  default_tier: "S2",
+};
+
+/**
+ * Testing environment configuration.
+ */
+export const TESTING_CONFIG: GovernanceConfig = {
+  default_mode: "disabled",
+  require_subject: false,
+  emit_evidence: false,
+  audit_denials: false,
+  default_tier: "S1",
+};

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Public TypeScript types for CHP v0.1.
+ *
+ * The root export is intentionally limited to the open-source protocol surface
+ * described by `spec/chp-v0.1.md` and the JSON Schemas in `schemas/`.
+ *
+ * Internal legacy mesh/governance helpers are available from
+ * `@auxo/ts-types/legacy`.
+ *
+ * @packageDocumentation
+ */
+
+export * from "./v0_1.js";
+
+export const CHP_VERSION = "0.1";
+export const VERSION = "0.1.0";

package/src/invariants.ts

@@ -0,0 +1,123 @@
+/**
+ * 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
+ */
+export type InvariantClass =
+  | "structural"
+  | "environmental"
+  | "data"
+  | "temporal"
+  | "causal";
+
+/**
+ * Invariant classes as a const array.
+ */
+export const INVARIANT_CLASSES = [
+  "structural",
+  "environmental",
+  "data",
+  "temporal",
+  "causal",
+] as const;
+
+/**
+ * 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
+ */
+export 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
+ */
+export 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.
+ */
+export 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.
+ */
+export function createDeclaredInvariant(params: {
+  invariant_id: string;
+  invariant_class: InvariantClass;
+  enforcement?: EnforcementResponsibility;
+  failure_behavior?: FailureBehavior;
+  description?: string;
+  parameters?: Record<string, unknown>;
+}): DeclaredInvariant {
+  return {
+    invariant_id: params.invariant_id,
+    invariant_class: params.invariant_class,
+    enforcement: params.enforcement ?? "runtime",
+    failure_behavior: params.failure_behavior ?? "deny",
+    description: params.description ?? "",
+    parameters: params.parameters ?? {},
+  };
+}
+
+/**
+ * Validate that an object conforms to the DeclaredInvariant interface.
+ */
+export function isDeclaredInvariant(obj: unknown): obj is DeclaredInvariant {
+  if (typeof obj !== "object" || obj === null) return false;
+
+  const i = obj as Record<string, unknown>;
+  return (
+    typeof i.invariant_id === "string" &&
+    typeof i.invariant_class === "string" &&
+    typeof i.enforcement === "string" &&
+    typeof i.failure_behavior === "string"
+  );
+}

package/src/legacy.ts

@@ -0,0 +1,84 @@
+/**
+ * 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
+ */
+
+export {
+  type RiskClass,
+  RISK_CLASSES,
+  RISK_CLASS_ORDER,
+  compareRiskClass,
+  isRiskAtLeast,
+} from "./risk.js";
+
+export {
+  type AssuranceTier,
+  ASSURANCE_TIERS,
+  ASSURANCE_TIER_DISPLAY_NAMES,
+  ASSURANCE_TIER_ORDER,
+  compareAssuranceTier,
+  meetsAssuranceTier,
+  getAssuranceTierDisplayName,
+} from "./assurance.js";
+
+export {
+  type EvidenceType,
+  type Evidence,
+  EVIDENCE_TYPES,
+  createEvidence,
+  isEvidence,
+} from "./evidence.js";
+
+export {
+  type InvariantClass,
+  type EnforcementResponsibility,
+  type FailureBehavior,
+  type DeclaredInvariant,
+  INVARIANT_CLASSES,
+  createDeclaredInvariant,
+  isDeclaredInvariant,
+} from "./invariants.js";
+
+export {
+  type SubjectContext,
+  type InvocationContext,
+  type ExecutionOutcome,
+  EXECUTION_OUTCOMES,
+  createSubjectContext,
+  createInvocationContext,
+  hasEntitlement,
+} from "./context.js";
+
+export {
+  type GovernanceMode,
+  type GovernedContext,
+  type GovernanceConfig,
+  GOVERNANCE_MODES,
+  DEVELOPMENT_CONFIG,
+  PRODUCTION_CONFIG,
+  TESTING_CONFIG,
+  blocksExecution,
+  emitsEvidence,
+  createGovernedContext,
+  createGovernanceConfig,
+  createChildContext,
+  emitEvidence,
+  elapsedMs,
+} from "./governance.js";
+
+export {
+  type CapabilityDeclaration,
+  type InvocationMode,
+  type HostIdentity,
+  INVOCATION_MODES,
+  getCapabilityId,
+  createCapabilityDeclaration,
+  isCapabilityDeclaration,
+  createHostIdentity,
+} from "./capability.js";
+
+export const LEGACY_CHP_VERSION = "1.0";

package/src/risk.ts

@@ -0,0 +1,62 @@
+/**
+ * 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
+ */
+export type RiskClass =
+  | "informational"
+  | "low"
+  | "medium"
+  | "high"
+  | "critical";
+
+/**
+ * Risk class values as a const array for iteration.
+ */
+export const RISK_CLASSES = [
+  "informational",
+  "low",
+  "medium",
+  "high",
+  "critical",
+] as const;
+
+/**
+ * Risk class numeric order for comparison.
+ */
+export const RISK_CLASS_ORDER: Record<RiskClass, number> = {
+  informational: 0,
+  low: 1,
+  medium: 2,
+  high: 3,
+  critical: 4,
+};
+
+/**
+ * Compare two risk classes.
+ * @returns negative if a < b, 0 if equal, positive if a > b
+ */
+export function compareRiskClass(a: RiskClass, b: RiskClass): number {
+  return RISK_CLASS_ORDER[a] - RISK_CLASS_ORDER[b];
+}
+
+/**
+ * Check if a risk class is at least as high as another.
+ */
+export function isRiskAtLeast(actual: RiskClass, required: RiskClass): boolean {
+  return RISK_CLASS_ORDER[actual] >= RISK_CLASS_ORDER[required];
+}

package/src/v0_1.ts

@@ -0,0 +1,166 @@
+/**
+ * CHP v0.1 protocol types.
+ *
+ * These interfaces mirror the JSON Schemas in the repository root `schemas/`
+ * directory. They are intentionally transport-neutral and do not depend on the
+ * older mesh/governance TypeScript model in this package.
+ */
+
+export const CHP_V0_1_VERSION = "0.1" as const;
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | JsonObject;
+export interface JsonObject {
+  [key: string]: JsonValue;
+}
+
+export type CapabilityRisk = "low" | "medium" | "high" | "critical";
+export type ChpV01InvocationMode = "sync" | "async" | "stream" | "fire_and_forget";
+export type ChpV01ExecutionOutcome = "success" | "failure" | "denied" | "skipped";
+export type AssuranceLevel = "S1" | "S2" | "S3";
+export type InvariantEnforcement = "declarative" | "host" | "runtime";
+export type InvariantFailureBehavior = "deny" | "warn" | "degrade";
+
+export const CHP_V0_1_OUTCOMES = [
+  "success",
+  "failure",
+  "denied",
+  "skipped",
+] as const satisfies readonly ChpV01ExecutionOutcome[];
+
+export const CHP_V0_1_CORE_EVIDENCE_TYPES = [
+  "execution_started",
+  "execution_completed",
+  "execution_failed",
+  "execution_denied",
+  "execution_skipped",
+] as const;
+
+export interface AssuranceMetadata {
+  level: AssuranceLevel;
+  evidence_policy?: string;
+  notes?: string[];
+}
+
+export interface InvariantDescriptor {
+  id: string;
+  kind: string;
+  description?: string;
+  enforcement?: InvariantEnforcement;
+  failure_behavior?: InvariantFailureBehavior;
+  parameters?: JsonObject;
+}
+
+export interface CapabilityDescriptor {
+  id: string;
+  version: string;
+  capability_uri?: string;
+  description: string;
+  modes: ChpV01InvocationMode[];
+  input_schema?: JsonObject;
+  output_schema?: JsonObject;
+  invariants?: InvariantDescriptor[];
+  emits: string[];
+  owner?: string | null;
+  tags?: string[];
+  risk?: CapabilityRisk;
+  assurance?: AssuranceMetadata;
+  metadata?: JsonObject;
+}
+
+export interface HostDescriptor {
+  id: string;
+  version: string;
+  protocol_version: typeof CHP_V0_1_VERSION;
+  kind: string;
+  capabilities: CapabilityDescriptor[];
+  evidence: {
+    store: string;
+    append_only: boolean;
+    [key: string]: JsonValue;
+  };
+  metadata?: JsonObject;
+}
+
+export interface CorrelationContext {
+  correlation_id: string;
+  causation_id?: string | null;
+  parent_correlation_id?: string | null;
+  trace_id?: string | null;
+  baggage?: Record<string, JsonPrimitive>;
+}
+
+export interface InvocationEnvelope {
+  invocation_id: string;
+  capability_id: string;
+  version?: string | null;
+  mode: ChpV01InvocationMode;
+  correlation: CorrelationContext;
+  subject: JsonObject;
+  payload: JsonObject;
+  requested_at: string;
+  metadata?: JsonObject;
+}
+
+export interface DenialReason {
+  code: string;
+  message: string;
+  invariant_id?: string | null;
+  retryable: boolean;
+  details?: JsonObject;
+}
+
+export interface InvocationResult {
+  invocation_id: string;
+  capability_id: string;
+  capability_version?: string | null;
+  correlation: CorrelationContext;
+  outcome: ChpV01ExecutionOutcome;
+  success: boolean;
+  data?: JsonValue;
+  error?: JsonObject | null;
+  denial?: DenialReason | null;
+  evidence_ids: string[];
+  started_at?: string | null;
+  completed_at: string;
+}
+
+export interface ExecutionEvidence {
+  event_id: string;
+  event_type: string;
+  invocation_id: string;
+  capability_id: string;
+  capability_version?: string | null;
+  host_id: string;
+  correlation: CorrelationContext;
+  timestamp: string;
+  sequence: number;
+  outcome?: ChpV01ExecutionOutcome | null;
+  payload: JsonObject;
+  redacted: boolean;
+  error?: JsonObject | null;
+  denial?: DenialReason | null;
+  assurance: AssuranceMetadata;
+}
+
+export interface ReplayQuery {
+  correlation_id: string;
+  limit?: number | null;
+  since_sequence?: number | null;
+  include_payloads?: boolean;
+}
+
+export interface ReplayResult {
+  correlation_id: string;
+  events: ExecutionEvidence[];
+  event_count: number;
+  replayed_at: string;
+}
+
+export function capabilityUri(descriptor: Pick<CapabilityDescriptor, "id" | "version">): string {
+  return `${descriptor.id}:${descriptor.version}`;
+}
+
+export function isChpV01Outcome(value: string): value is ChpV01ExecutionOutcome {
+  return (CHP_V0_1_OUTCOMES as readonly string[]).includes(value);
+}