@capabilityhostprotocol/types 0.1.0

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@capabilityhostprotocol/types",
+  "version": "0.1.0",
+  "description": "TypeScript protocol types for the Capability Host Protocol (CHP v0.1).",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./legacy": {
+      "types": "./dist/legacy.d.ts",
+      "import": "./dist/legacy.mjs",
+      "require": "./dist/legacy.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/legacy.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts src/legacy.ts --format cjs,esm --dts --watch",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit --strict --module NodeNext --moduleResolution NodeNext --target ES2022 examples/v0_1.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "chp",
+    "capability-host-protocol",
+    "governance",
+    "evidence",
+    "capabilities",
+    "typescript"
+  ],
+  "author": "Auxo",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/capabilityhostprotocol/chp-core.git",
+    "directory": "packages/ts-types"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}

package/src/assurance.ts

@@ -0,0 +1,65 @@
+/**
+ * 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
+ */
+export type AssuranceTier = "S1" | "S2" | "S3";
+
+/**
+ * Assurance tier values as a const array.
+ */
+export const ASSURANCE_TIERS = ["S1", "S2", "S3"] as const;
+
+/**
+ * Human-readable names for assurance tiers.
+ */
+export const ASSURANCE_TIER_DISPLAY_NAMES: Record<AssuranceTier, string> = {
+  S1: "Observational",
+  S2: "Structural",
+  S3: "Attested",
+};
+
+/**
+ * Assurance tier numeric order for comparison.
+ */
+export const ASSURANCE_TIER_ORDER: Record<AssuranceTier, number> = {
+  S1: 1,
+  S2: 2,
+  S3: 3,
+};
+
+/**
+ * Compare two assurance tiers.
+ * @returns negative if a < b, 0 if equal, positive if a > b
+ */
+export function compareAssuranceTier(a: AssuranceTier, b: AssuranceTier): number {
+  return ASSURANCE_TIER_ORDER[a] - ASSURANCE_TIER_ORDER[b];
+}
+
+/**
+ * Check if an assurance tier meets a minimum requirement.
+ */
+export function meetsAssuranceTier(
+  actual: AssuranceTier,
+  required: AssuranceTier
+): boolean {
+  return ASSURANCE_TIER_ORDER[actual] >= ASSURANCE_TIER_ORDER[required];
+}
+
+/**
+ * Get the display name for an assurance tier.
+ */
+export function getAssuranceTierDisplayName(tier: AssuranceTier): string {
+  return ASSURANCE_TIER_DISPLAY_NAMES[tier];
+}

package/src/capability.ts

@@ -0,0 +1,163 @@
+/**
+ * Capability Declaration Types
+ *
+ * Capabilities are the units of authority in CHP.
+ * This module defines the canonical capability declaration structure.
+ *
+ * @module capability
+ */
+
+import type { RiskClass } from "./risk.js";
+import type { AssuranceTier } from "./assurance.js";
+import type { DeclaredInvariant } from "./invariants.js";
+import type { EvidenceType } from "./evidence.js";
+
+/**
+ * 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.
+ */
+export 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.
+ */
+export function getCapabilityId(decl: CapabilityDeclaration): string {
+  return `${decl.name}:${decl.version}`;
+}
+
+/**
+ * Create a new capability declaration.
+ */
+export 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 {
+  return {
+    name: params.name,
+    version: params.version ?? "1.0.0",
+    risk_class: params.risk_class ?? "medium",
+    description: params.description ?? "",
+    invariants: params.invariants ?? [],
+    evidence_types: params.evidence_types ?? [],
+    require_entitlement: params.require_entitlement ?? false,
+    minimum_tier: params.minimum_tier ?? "S1",
+    owner: params.owner ?? null,
+    tags: params.tags ?? [],
+  };
+}
+
+/**
+ * Validate that an object conforms to the CapabilityDeclaration interface.
+ */
+export function isCapabilityDeclaration(
+  obj: unknown
+): obj is CapabilityDeclaration {
+  if (typeof obj !== "object" || obj === null) return false;
+
+  const c = obj as Record<string, unknown>;
+  return (
+    typeof c.name === "string" &&
+    typeof c.version === "string" &&
+    typeof c.risk_class === "string" &&
+    typeof c.require_entitlement === "boolean"
+  );
+}
+
+/**
+ * Supported invocation modes for a capability.
+ */
+export type InvocationMode =
+  | "sync" // Synchronous request/response
+  | "async" // Asynchronous with callback/promise
+  | "stream" // Streaming response
+  | "fire_and_forget"; // No response expected
+
+/**
+ * Invocation modes as a const array.
+ */
+export const INVOCATION_MODES = [
+  "sync",
+  "async",
+  "stream",
+  "fire_and_forget",
+] as const;
+
+/**
+ * Host identity for capability hosting.
+ * Identifies where capabilities are hosted.
+ */
+export 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.
+ */
+export function createHostIdentity(params: {
+  host_id: string;
+  host_type?: string;
+  version?: string;
+  environment?: string;
+  metadata?: Record<string, unknown>;
+}): HostIdentity {
+  return {
+    host_id: params.host_id,
+    host_type: params.host_type ?? "server",
+    version: params.version ?? "1.0.0",
+    environment: params.environment ?? "development",
+    metadata: params.metadata ?? {},
+  };
+}

package/src/context.ts

@@ -0,0 +1,137 @@
+/**
+ * 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.
+ */
+export 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.
+ */
+export function createSubjectContext(params: {
+  subject_id: string;
+  subject_type?: string;
+  entitlements?: string[];
+  metadata?: Record<string, unknown>;
+}): SubjectContext {
+  return {
+    subject_id: params.subject_id,
+    subject_type: params.subject_type ?? "user",
+    entitlements: params.entitlements ?? [],
+    metadata: params.metadata ?? {},
+  };
+}
+
+/**
+ * Check if a subject has a specific entitlement.
+ */
+export function hasEntitlement(
+  subject: SubjectContext,
+  entitlement: string
+): boolean {
+  return subject.entitlements.includes(entitlement);
+}
+
+/**
+ * Context for a capability invocation.
+ *
+ * Provides access to subject information, correlation tracking,
+ * and execution metadata during capability execution.
+ */
+export 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.
+ */
+export 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 {
+  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,
+    parent_invocation_id: params.parent_invocation_id ?? null,
+    timestamp: new Date().toISOString(),
+    metadata: params.metadata ?? {},
+  };
+}
+
+/**
+ * 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)
+ */
+export type ExecutionOutcome =
+  | "success"
+  | "failure"
+  | "denied"
+  | "timeout"
+  | "aborted";
+
+/**
+ * Execution outcomes as a const array.
+ */
+export const EXECUTION_OUTCOMES = [
+  "success",
+  "failure",
+  "denied",
+  "timeout",
+  "aborted",
+] as const;

package/src/evidence.ts

@@ -0,0 +1,167 @@
+/**
+ * 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
+ */
+
+import type { AssuranceTier } from "./assurance.js";
+
+/**
+ * Evidence types for capability execution tracking.
+ *
+ * Every capability execution produces evidence. The type indicates
+ * what kind of execution event occurred.
+ */
+export type EvidenceType =
+  // Core Execution
+  | "execution_started"
+  | "execution_completed"
+  | "execution_failed"
+  | "execution_denied"
+  | "execution_aborted"
+  // Invocation Boundary
+  | "invocation_received"
+  | "invocation_validated"
+  | "invocation_rejected"
+  // Authorization
+  | "entitlement_checked"
+  | "entitlement_granted"
+  | "entitlement_denied"
+  // Invariants
+  | "invariant_checked"
+  | "invariant_passed"
+  | "invariant_failed"
+  // Resilience Primitives
+  | "retry_attempted"
+  | "retry_exhausted"
+  | "timeout_exceeded"
+  | "circuit_opened"
+  | "circuit_closed"
+  | "rate_limited"
+  // Assurance
+  | "assurance_derived"
+  | "assurance_degraded"
+  // Lineage
+  | "lineage_traced"
+  | "causal_link_created";
+
+/**
+ * All evidence types as a const array for iteration.
+ */
+export const EVIDENCE_TYPES = [
+  // Core Execution
+  "execution_started",
+  "execution_completed",
+  "execution_failed",
+  "execution_denied",
+  "execution_aborted",
+  // Invocation Boundary
+  "invocation_received",
+  "invocation_validated",
+  "invocation_rejected",
+  // Authorization
+  "entitlement_checked",
+  "entitlement_granted",
+  "entitlement_denied",
+  // Invariants
+  "invariant_checked",
+  "invariant_passed",
+  "invariant_failed",
+  // Resilience Primitives
+  "retry_attempted",
+  "retry_exhausted",
+  "timeout_exceeded",
+  "circuit_opened",
+  "circuit_closed",
+  "rate_limited",
+  // Assurance
+  "assurance_derived",
+  "assurance_degraded",
+  // Lineage
+  "lineage_traced",
+  "causal_link_created",
+] as const;
+
+/**
+ * Immutable evidence record for capability execution.
+ *
+ * This is the canonical CHP evidence structure that must be
+ * faithfully serialized/deserialized across language boundaries.
+ */
+export 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
+ */
+export 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 {
+  return {
+    evidence_id: crypto.randomUUID(),
+    evidence_type: params.evidence_type,
+    capability_id: params.capability_id,
+    timestamp: new Date().toISOString(),
+    subject_id: params.subject_id ?? null,
+    correlation_id: params.correlation_id ?? null,
+    assurance_tier: params.assurance_tier ?? "S1",
+    payload: params.payload ?? {},
+    trace_id: params.trace_id ?? null,
+  };
+}
+
+/**
+ * Validate that an object conforms to the Evidence interface.
+ */
+export function isEvidence(obj: unknown): obj is Evidence {
+  if (typeof obj !== "object" || obj === null) return false;
+
+  const e = obj as Record<string, unknown>;
+  return (
+    typeof e.evidence_id === "string" &&
+    typeof e.evidence_type === "string" &&
+    typeof e.capability_id === "string" &&
+    typeof e.timestamp === "string" &&
+    typeof e.assurance_tier === "string" &&
+    typeof e.payload === "object"
+  );
+}