@codmir/contracts 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1233 @@
+/**
+ * @fileoverview
+ * Codmir Contract Schema v1
+ *
+ * Contracts are versioned, JSON-serializable, and deterministic.
+ * They define what autonomous agents are allowed to do, their triggers,
+ * permissions, steps, and execution policies.
+ */
+type IsoDateString = string;
+type ContractId = string;
+type ContractVersion = string;
+type StepId = string;
+type RunId = string;
+type EventName = string;
+type JsonValue = string | number | boolean | null | {
+    [k: string]: JsonValue;
+} | JsonValue[];
+/**
+ * Permission types that a contract can request.
+ * Engine/Policy adapter enforces these before any action.
+ */
+type Permission = {
+    kind: "event:emit";
+    pattern: string;
+} | {
+    kind: "event:read";
+    pattern: string;
+} | {
+    kind: "storage:read";
+    scope: string;
+} | {
+    kind: "storage:write";
+    scope: string;
+} | {
+    kind: "repo:read";
+    scope: string;
+} | {
+    kind: "repo:write";
+    scope: string;
+} | {
+    kind: "http:request";
+    domains: string[];
+} | {
+    kind: "secrets:read";
+    keys: string[];
+} | {
+    kind: "llm:invoke";
+    models?: string[];
+};
+/**
+ * Contract trigger definition.
+ * Specifies which events can start a new run of this contract.
+ */
+type ContractTrigger = {
+    type: "event";
+    /**
+     * Event pattern support:
+     * - exact match: "ticket.created"
+     * - wildcard: "ticket.*"
+     */
+    event: string;
+    /**
+     * Optional filter conditions on event payload.
+     * Engine evaluates these deterministically.
+     */
+    where?: Record<string, JsonValue>;
+};
+type RetryPolicy = {
+    maxAttempts: number;
+    backoffMs: number;
+    backoffMultiplier?: number;
+};
+type StepTimeout = {
+    /** Hard timeout in milliseconds */
+    ms: number;
+};
+/**
+ * Deterministic condition expression for branching and step guards.
+ * Evaluated against run context (JSON-like object).
+ */
+type ConditionExpr = {
+    op: "eq";
+    path: string;
+    value: JsonValue;
+} | {
+    op: "neq";
+    path: string;
+    value: JsonValue;
+} | {
+    op: "gt";
+    path: string;
+    value: number;
+} | {
+    op: "gte";
+    path: string;
+    value: number;
+} | {
+    op: "lt";
+    path: string;
+    value: number;
+} | {
+    op: "lte";
+    path: string;
+    value: number;
+} | {
+    op: "and";
+    exprs: ConditionExpr[];
+} | {
+    op: "or";
+    exprs: ConditionExpr[];
+} | {
+    op: "not";
+    expr: ConditionExpr;
+} | {
+    op: "exists";
+    path: string;
+} | {
+    op: "contains";
+    path: string;
+    value: string;
+} | {
+    op: "startsWith";
+    path: string;
+    value: string;
+} | {
+    op: "endsWith";
+    path: string;
+    value: string;
+};
+type StepKind = "task" | "llm" | "emit" | "wait" | "branch" | "transform" | "approval" | "skill" | "audit";
+type StepBase = {
+    id: StepId;
+    name: string;
+    kind: StepKind;
+    timeout?: StepTimeout;
+    retry?: RetryPolicy;
+    /**
+     * If present, the step is skipped unless condition resolves true.
+     * Condition must be deterministic (based on run context).
+     */
+    if?: ConditionExpr;
+    /**
+     * Next step pointer. Some step kinds may override this (branch/wait).
+     */
+    next?: StepId | null;
+    /**
+     * Optional description for documentation/debugging.
+     */
+    description?: string;
+};
+/**
+ * Task step - executes a named task in runtime (Railway).
+ */
+type TaskStep = StepBase & {
+    kind: "task";
+    /**
+     * A runtime-registered task name, e.g. "analyze-ticket", "apply-patch".
+     */
+    task: string;
+    /**
+     * Inputs are pulled from run context (event payload + accumulated outputs).
+     * Engine resolves {{path}} templates deterministically.
+     */
+    input: Record<string, JsonValue>;
+    /**
+     * Where to store the step output in run context.
+     * Example: "steps.analyzeTicket"
+     */
+    saveAs?: string;
+};
+/**
+ * LLM step - calls intelligence adapter.
+ */
+type LlmStep = StepBase & {
+    kind: "llm";
+    model?: string;
+    /**
+     * Messages or prompt template. Keep JSON-serializable.
+     */
+    prompt: Record<string, JsonValue>;
+    /**
+     * Where to store the LLM response in run context.
+     */
+    saveAs?: string;
+    /**
+     * Optional system prompt.
+     */
+    systemPrompt?: string;
+    /**
+     * Temperature for generation (0-1).
+     */
+    temperature?: number;
+    /**
+     * Max tokens for response.
+     */
+    maxTokens?: number;
+};
+/**
+ * Emit step - emits an event to the event bus.
+ */
+type EmitStep = StepBase & {
+    kind: "emit";
+    event: EventName;
+    payload: Record<string, JsonValue>;
+};
+/**
+ * Wait step - waits for an external event to arrive.
+ */
+type WaitStep = StepBase & {
+    kind: "wait";
+    /**
+     * Wait for a specific event name/pattern to arrive.
+     * When matched, engine stores it and proceeds.
+     */
+    event: string;
+    /**
+     * Where to store the received event payload in run context.
+     */
+    saveEventAs?: string;
+    /**
+     * Alternative next step if timeout is reached.
+     */
+    nextOnTimeout?: StepId | null;
+};
+/**
+ * Branch step - conditional branching based on run context.
+ */
+type BranchStep = StepBase & {
+    kind: "branch";
+    branches: Array<{
+        when: ConditionExpr;
+        next: StepId;
+    }>;
+    defaultNext: StepId;
+};
+/**
+ * Transform step - pure data transformation within run context.
+ */
+type TransformStep = StepBase & {
+    kind: "transform";
+    /**
+     * Transformations to apply to run context.
+     * Each key is a destination path, value is a template or expression.
+     */
+    transforms: Record<string, JsonValue>;
+};
+/**
+ * Approval step - human-in-the-loop gate (Overseer pattern).
+ * Pauses execution until approved/denied by authorized actor.
+ */
+type ApprovalStep = StepBase & {
+    kind: "approval";
+    /**
+     * Human-readable description of what is being approved.
+     */
+    prompt: string;
+    /**
+     * Users/roles who can approve this step.
+     */
+    approvers?: string[];
+    /**
+     * Next step if approved.
+     */
+    nextOnApproved: StepId;
+    /**
+     * Next step if denied (optional - run fails if not specified).
+     */
+    nextOnDenied?: StepId | null;
+    /**
+     * Timeout behavior - defaults to deny.
+     */
+    timeoutAction?: "deny" | "approve" | "fail";
+    /**
+     * Context data to show the approver.
+     */
+    context?: Record<string, JsonValue>;
+};
+/**
+ * Skill step - executes a fine-tuned skill (Claude Code integration).
+ */
+type SkillStep = StepBase & {
+    kind: "skill";
+    /**
+     * ID of the skill to execute.
+     * @example "tickets.plan", "code.review", "tests.generate"
+     */
+    skillId: string;
+    /**
+     * Input to pass to the skill (templates resolved from run context).
+     */
+    input: Record<string, JsonValue>;
+    /**
+     * Where to save skill output in run context.
+     */
+    saveAs?: string;
+    /**
+     * Next step after skill completes.
+     */
+    next?: StepId | null;
+};
+/**
+ * Audit step - audits code changes with AI analysis (Governor pattern).
+ * Fetches changes between commits, analyzes with full context, generates findings.
+ */
+type AuditStep = StepBase & {
+    kind: "audit";
+    /**
+     * Target repository (path or URL).
+     */
+    repository: string;
+    /**
+     * From commit reference (SHA, tag, or branch).
+     * Templates allowed: {{event.payload.baseCommit}}
+     */
+    fromCommit: string;
+    /**
+     * To commit reference (SHA, tag, or branch).
+     * Templates allowed: {{event.payload.headCommit}}
+     */
+    toCommit: string;
+    /**
+     * Include conversation context in analysis.
+     */
+    includeConversation?: boolean;
+    /**
+     * Include AI reasoning context in analysis.
+     */
+    includeReasoning?: boolean;
+    /**
+     * Minimum severity to report.
+     */
+    minSeverity?: "critical" | "high" | "medium" | "low" | "info";
+    /**
+     * Auto-approve if no issues above threshold.
+     */
+    autoApproveThreshold?: "critical" | "high" | "medium" | "low";
+    /**
+     * Where to save audit result in run context.
+     */
+    saveAs?: string;
+    /**
+     * Next step after audit completes.
+     */
+    next?: StepId | null;
+    /**
+     * Next step if audit fails or rejects.
+     */
+    nextOnReject?: StepId | null;
+};
+type ContractStep = TaskStep | LlmStep | EmitStep | WaitStep | BranchStep | TransformStep | ApprovalStep | SkillStep | AuditStep;
+/**
+ * Expected duration category for smart sync/async routing.
+ */
+type ExpectedDuration = "instant" | "quick" | "medium" | "long";
+/**
+ * Execution mode preference.
+ */
+type ExecutionMode = "sync" | "async" | "auto";
+/**
+ * Execution hints for realtime/voice callers.
+ * Helps the engine decide whether to wait for completion or return immediately.
+ */
+type ExecutionHints = {
+    /**
+     * Expected duration category for smart routing:
+     * - instant: < 2s (DB write, simple API call)
+     * - quick: 2-30s (external API, light processing)
+     * - medium: 30s-5min (code analysis, file operations)
+     * - long: > 5min (deployments, heavy computation)
+     */
+    expectedDuration: ExpectedDuration;
+    /**
+     * Override: max milliseconds voice/realtime callers should wait.
+     * Default is derived from expectedDuration.
+     */
+    syncThreshold?: number;
+    /**
+     * Preferred execution mode:
+     * - sync: Caller waits for result (blocking)
+     * - async: Fire-and-forget, notify via events
+     * - auto: Engine decides based on expectedDuration (default)
+     */
+    mode?: ExecutionMode;
+    /**
+     * Can the caller interrupt/cancel mid-execution?
+     */
+    interruptible?: boolean;
+    /**
+     * Human-friendly message for async acknowledgment.
+     * Example: "I'm deploying that now, I'll let you know when it's ready."
+     */
+    asyncAckMessage?: string;
+};
+/**
+ * Default sync thresholds per duration category (in milliseconds).
+ */
+declare const DURATION_SYNC_THRESHOLDS: Record<ExpectedDuration, number>;
+type ContractLimits = {
+    /**
+     * Total run time cap enforced by engine.
+     */
+    maxRunMs: number;
+    /**
+     * Maximum number of steps executed to avoid infinite loops.
+     */
+    maxSteps: number;
+    /**
+     * Maximum LLM invocations per run.
+     */
+    maxLlmCalls?: number;
+    /**
+     * Maximum total tokens consumed per run.
+     */
+    maxTokens?: number;
+};
+type ContractOutputs = {
+    /**
+     * Events emitted at run completion (success).
+     */
+    onCompleted?: Array<{
+        event: EventName;
+        payload: Record<string, JsonValue>;
+    }>;
+    /**
+     * Events emitted at run failure.
+     */
+    onFailed?: Array<{
+        event: EventName;
+        payload: Record<string, JsonValue>;
+    }>;
+    /**
+     * Events emitted when run is cancelled.
+     */
+    onCancelled?: Array<{
+        event: EventName;
+        payload: Record<string, JsonValue>;
+    }>;
+};
+/**
+ * Codmir Contract v1
+ *
+ * A contract is a declarative agreement describing:
+ * - What the agent is allowed to do
+ * - What inputs it may consume
+ * - What outputs it may emit
+ * - What events advance or terminate execution
+ * - What resources it can touch
+ *
+ * Contracts are portable, auditable, and replayable.
+ */
+type CodmirContract = {
+    /**
+     * Schema version for forward compatibility.
+     */
+    schemaVersion: "codmir.contract.v1";
+    /**
+     * Unique contract identifier.
+     */
+    id: ContractId;
+    /**
+     * Semantic version of this contract.
+     */
+    version: ContractVersion;
+    /**
+     * Human-readable title.
+     */
+    title: string;
+    /**
+     * Optional description.
+     */
+    description?: string;
+    /**
+     * Events that can trigger a new run of this contract.
+     */
+    triggers: ContractTrigger[];
+    /**
+     * Permissions required by this contract.
+     */
+    permissions: Permission[];
+    /**
+     * Execution limits.
+     */
+    limits: ContractLimits;
+    /**
+     * Entry point step ID.
+     */
+    entryStepId: StepId;
+    /**
+     * Step definitions forming the execution graph.
+     */
+    steps: ContractStep[];
+    /**
+     * Optional output events.
+     */
+    outputs?: ContractOutputs;
+    /**
+     * Execution hints for voice/realtime callers.
+     * Helps decide sync vs async execution based on expected duration.
+     */
+    execution?: ExecutionHints;
+    /**
+     * Optional tags for categorization.
+     */
+    tags?: string[];
+    /**
+     * Optional creation timestamp.
+     */
+    createdAt?: IsoDateString;
+    /**
+     * Optional author/owner.
+     */
+    author?: string;
+    /**
+     * Optional metadata.
+     */
+    metadata?: Record<string, JsonValue>;
+};
+/**
+ * Summary of a contract for registry listing.
+ */
+type ContractSummary = {
+    id: ContractId;
+    version: ContractVersion;
+    title: string;
+    description?: string;
+    triggers: string[];
+    tags?: string[];
+    createdAt?: IsoDateString;
+};
+/**
+ * Contract registry query options.
+ */
+type ContractQuery = {
+    id?: ContractId;
+    triggerEvent?: string;
+    tags?: string[];
+    limit?: number;
+    offset?: number;
+};
+
+/**
+ * @fileoverview
+ * Grace Foundation Schema Extensions
+ *
+ * "Social contract between AI and humanity"
+ *
+ * These types extend the core Codmir contract schema with:
+ * - Ethical impact assessment
+ * - Reversibility guarantees
+ * - Economic constraints
+ * - Societal impact scoring
+ * - Human dignity protections
+ *
+ * Every contract that uses Grace extensions must be:
+ * - Transparent: All actions logged and traceable
+ * - Consensual: Explicit permission scope
+ * - Reversible: Every action undoable
+ * - Accountable: Task attribution and versioning
+ * - Bounded: Economic and resource limits
+ */
+
+/**
+ * Ethical impact categories for contract assessment.
+ */
+type EthicalImpactCategory = "user_data" | "financial" | "public_systems" | "employment" | "privacy" | "security" | "environmental" | "accessibility" | "content_generation";
+/**
+ * Severity levels for ethical impact.
+ */
+type ImpactSeverity = "none" | "low" | "medium" | "high" | "critical";
+/**
+ * Individual ethical impact assessment.
+ */
+type EthicalImpact = {
+    category: EthicalImpactCategory;
+    severity: ImpactSeverity;
+    description?: string;
+    mitigations?: string[];
+};
+/**
+ * Full ethical impact assessment for a contract.
+ */
+type EthicalAssessment = {
+    /**
+     * Individual impact assessments by category.
+     */
+    impacts: EthicalImpact[];
+    /**
+     * Overall risk score (0-100).
+     * Computed from individual impacts.
+     */
+    overallRiskScore: number;
+    /**
+     * Human-readable summary of ethical considerations.
+     */
+    summary?: string;
+    /**
+     * Whether this contract requires human review before execution.
+     */
+    requiresHumanReview: boolean;
+    /**
+     * Specific roles that must approve high-impact contracts.
+     */
+    requiredApprovers?: string[];
+};
+/**
+ * Reversibility configuration for a contract.
+ */
+type ReversibilityConfig = {
+    /**
+     * Whether all actions in this contract are reversible.
+     */
+    fullyReversible: boolean;
+    /**
+     * Create a snapshot before execution begins.
+     */
+    snapshotBeforeExecution: boolean;
+    /**
+     * Retain snapshots for this duration (ms).
+     * Default: 7 days
+     */
+    snapshotRetentionMs?: number;
+    /**
+     * Steps that are explicitly irreversible.
+     * Engine will require extra confirmation for these.
+     */
+    irreversibleSteps?: string[];
+    /**
+     * Rollback strategy if execution fails midway.
+     */
+    rollbackStrategy: "full" | "partial" | "none";
+    /**
+     * Custom rollback contract to execute on failure.
+     */
+    rollbackContractId?: string;
+};
+/**
+ * Cost units for economic tracking.
+ */
+type CostUnit = "credits" | "usd" | "tokens";
+/**
+ * Budget configuration for a contract.
+ */
+type BudgetConfig = {
+    /**
+     * Maximum budget for this contract execution.
+     */
+    maxBudget: number;
+    /**
+     * Unit of the budget.
+     */
+    unit: CostUnit;
+    /**
+     * Alert threshold (percentage of budget).
+     * Default: 80
+     */
+    alertThreshold?: number;
+    /**
+     * Action when budget is exceeded.
+     */
+    onExceeded: "pause" | "fail" | "notify";
+    /**
+     * Whether to refund unused budget.
+     */
+    refundUnused: boolean;
+};
+/**
+ * Resource allocation for compute fairness.
+ */
+type ResourceAllocation = {
+    /**
+     * CPU allocation (vCPU cores).
+     */
+    cpu?: number;
+    /**
+     * Memory allocation (GB).
+     */
+    memory?: number;
+    /**
+     * GPU allocation (boolean or specific type).
+     */
+    gpu?: boolean | string;
+    /**
+     * Maximum execution time (ms).
+     */
+    maxExecutionTime: number;
+    /**
+     * Priority level for scheduling.
+     */
+    priority: "low" | "normal" | "high" | "critical";
+    /**
+     * Estimated carbon footprint (gCO2e).
+     */
+    estimatedCarbonFootprint?: number;
+};
+/**
+ * Workforce impact assessment.
+ */
+type WorkforceImpact = {
+    /**
+     * Does this contract automate human tasks?
+     */
+    automatesHumanTasks: boolean;
+    /**
+     * Estimated human hours displaced per execution.
+     */
+    estimatedDisplacementHours?: number;
+    /**
+     * Does this contract augment human capabilities?
+     */
+    augmentsHumans: boolean;
+    /**
+     * Skills that humans should develop alongside this automation.
+     */
+    recommendedHumanSkills?: string[];
+};
+/**
+ * Societal impact assessment.
+ */
+type SocietalImpact = {
+    /**
+     * Workforce displacement/augmentation analysis.
+     */
+    workforce?: WorkforceImpact;
+    /**
+     * Does this benefit underserved communities?
+     */
+    benefitsUnderserved?: boolean;
+    /**
+     * Potential for misuse.
+     */
+    misuseRisk: ImpactSeverity;
+    /**
+     * Safeguards against misuse.
+     */
+    misuseSafeguards?: string[];
+};
+/**
+ * Grace Foundation extensions for CodmirContract.
+ *
+ * Add these fields to your contract to enable Grace governance.
+ */
+type GraceExtensions = {
+    /**
+     * Grace schema version.
+     */
+    graceVersion: "grace.v1";
+    /**
+     * Ethical impact assessment.
+     */
+    ethics: EthicalAssessment;
+    /**
+     * Reversibility configuration.
+     */
+    reversibility: ReversibilityConfig;
+    /**
+     * Economic constraints.
+     */
+    budget?: BudgetConfig;
+    /**
+     * Resource allocation.
+     */
+    resources?: ResourceAllocation;
+    /**
+     * Societal impact assessment.
+     */
+    societalImpact?: SocietalImpact;
+    /**
+     * Human oversight configuration.
+     */
+    humanOversight: {
+        /**
+         * Minimum human checkpoints required.
+         */
+        minCheckpoints: number;
+        /**
+         * Allow autonomous execution without human oversight?
+         */
+        allowAutonomous: boolean;
+        /**
+         * Escalation path for issues.
+         */
+        escalationPath?: string[];
+    };
+    /**
+     * Transparency requirements.
+     */
+    transparency: {
+        /**
+         * Log all decisions with reasoning.
+         */
+        logDecisions: boolean;
+        /**
+         * Make execution logs available to affected parties.
+         */
+        logsAccessible: boolean;
+        /**
+         * Audit trail retention (days).
+         */
+        auditRetentionDays: number;
+    };
+};
+/**
+ * Grace policy rule types.
+ */
+type GracePolicyRule = {
+    type: "require_approval";
+    when: GracePolicyCondition;
+} | {
+    type: "deny";
+    when: GracePolicyCondition;
+    reason: string;
+} | {
+    type: "modify_scope";
+    when: GracePolicyCondition;
+    modifications: Record<string, JsonValue>;
+} | {
+    type: "add_checkpoint";
+    when: GracePolicyCondition;
+    checkpoint: string;
+} | {
+    type: "require_human_review";
+    when: GracePolicyCondition;
+};
+/**
+ * Conditions for policy rules.
+ */
+type GracePolicyCondition = {
+    op: "risk_above";
+    threshold: number;
+} | {
+    op: "touches_category";
+    category: EthicalImpactCategory;
+} | {
+    op: "budget_above";
+    amount: number;
+    unit: CostUnit;
+} | {
+    op: "not_reversible";
+} | {
+    op: "production_deployment";
+} | {
+    op: "affects_multiple_users";
+    threshold: number;
+} | {
+    op: "and";
+    conditions: GracePolicyCondition[];
+} | {
+    op: "or";
+    conditions: GracePolicyCondition[];
+};
+/**
+ * Audit event for Grace governance tracking.
+ */
+type GraceAuditEvent = {
+    id: string;
+    timestamp: string;
+    runId: string;
+    contractId: string;
+    type: "contract.submitted" | "ethics.assessed" | "approval.requested" | "approval.granted" | "approval.denied" | "checkpoint.reached" | "budget.alert" | "budget.exceeded" | "rollback.initiated" | "rollback.completed" | "human.override" | "policy.violated" | "policy.enforced";
+    actor: {
+        type: "human" | "ai" | "system";
+        id: string;
+        name?: string;
+    };
+    details: Record<string, JsonValue>;
+    /**
+     * Hash of previous audit event for chain integrity.
+     */
+    previousHash?: string;
+};
+/**
+ * Default Grace extensions for a new contract.
+ */
+declare const DEFAULT_GRACE_EXTENSIONS: GraceExtensions;
+/**
+ * Calculate overall risk score from impacts.
+ */
+declare function calculateRiskScore(impacts: EthicalImpact[]): number;
+/**
+ * Determine if human review is required based on impacts.
+ */
+declare function requiresHumanReview(impacts: EthicalImpact[]): boolean;
+/**
+ * Grace Foundation principles as machine-readable rules.
+ */
+declare const GRACE_PRINCIPLES: {
+    readonly transparency: "Every action logged, every decision traceable";
+    readonly consent: "Explicit permission scope, no implicit access";
+    readonly reversibility: "Every AI action must be undoable";
+    readonly accountability: "Task attribution, versioned modifications";
+    readonly economicBoundaries: "Token usage limit, execution cost cap";
+    readonly humanDignity: "AI augments, never replaces human judgment on critical decisions";
+    readonly fairness: "Distributed power must not centralize control";
+    readonly sustainability: "Prefer renewable-powered compute when available";
+};
+
+/**
+ * @fileoverview
+ * Contract validation utilities.
+ * Validates contracts are structurally correct before execution.
+ */
+
+/**
+ * Validation error with details.
+ */
+declare class ContractValidationError extends Error {
+    readonly field?: string | undefined;
+    readonly details?: unknown | undefined;
+    constructor(message: string, field?: string | undefined, details?: unknown | undefined);
+}
+/**
+ * Validation result type.
+ */
+type ValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    errors: ContractValidationError[];
+};
+/**
+ * Validate a contract with strict structural rules.
+ * Keep this deterministic and side-effect free.
+ *
+ * @param contract - Contract to validate
+ * @throws ContractValidationError if invalid
+ */
+declare function validateContract(contract: CodmirContract): void;
+/**
+ * Validate a contract and return a result object.
+ * Does not throw.
+ */
+declare function validateContractSafe(contract: CodmirContract): ValidationResult;
+/**
+ * Check if a contract has a specific permission.
+ */
+declare function hasPermission(contract: CodmirContract, kind: string, scope?: string): boolean;
+
+/**
+ * @fileoverview
+ * Condition expression evaluation for contracts.
+ * All evaluations are deterministic and side-effect free.
+ */
+
+/**
+ * Evaluate a deterministic condition expression against a JSON context.
+ *
+ * @param ctx - Run context object (JSON-like)
+ * @param expr - Condition expression to evaluate
+ * @returns true if the condition is satisfied
+ *
+ * @example
+ * ```ts
+ * const ctx = { status: "open", priority: 3 };
+ * evalCondition(ctx, { op: "eq", path: "status", value: "open" });
+ * // => true
+ * ```
+ */
+declare function evalCondition(ctx: Record<string, JsonValue>, expr: ConditionExpr): boolean;
+/**
+ * Validate that a condition expression is structurally valid.
+ * @throws Error if the expression is invalid
+ */
+declare function validateCondition(expr: ConditionExpr): void;
+/**
+ * Create a simple equality condition.
+ */
+declare function eq(path: string, value: JsonValue): ConditionExpr;
+/**
+ * Create a not-equals condition.
+ */
+declare function neq(path: string, value: JsonValue): ConditionExpr;
+/**
+ * Create an exists condition.
+ */
+declare function exists(path: string): ConditionExpr;
+/**
+ * Create an AND condition.
+ */
+declare function and(...exprs: ConditionExpr[]): ConditionExpr;
+/**
+ * Create an OR condition.
+ */
+declare function or(...exprs: ConditionExpr[]): ConditionExpr;
+/**
+ * Create a NOT condition.
+ */
+declare function not(expr: ConditionExpr): ConditionExpr;
+/**
+ * Create a greater-than condition.
+ */
+declare function gt(path: string, value: number): ConditionExpr;
+/**
+ * Create a greater-than-or-equal condition.
+ */
+declare function gte(path: string, value: number): ConditionExpr;
+/**
+ * Create a less-than condition.
+ */
+declare function lt(path: string, value: number): ConditionExpr;
+/**
+ * Create a less-than-or-equal condition.
+ */
+declare function lte(path: string, value: number): ConditionExpr;
+/**
+ * Create a contains condition (string or array).
+ */
+declare function contains(path: string, value: string): ConditionExpr;
+/**
+ * Create a startsWith condition.
+ */
+declare function startsWith(path: string, value: string): ConditionExpr;
+/**
+ * Create an endsWith condition.
+ */
+declare function endsWith(path: string, value: string): ConditionExpr;
+
+/**
+ * @fileoverview
+ * Template resolution utilities for contracts.
+ * Supports {{path}} syntax for extracting values from run context.
+ */
+
+/**
+ * Safely get a nested value by dot path from a JSON-like object.
+ * @param obj - Source object
+ * @param path - Dot-separated path (e.g., "trigger.ticketId")
+ * @returns The value at the path, or undefined if not found
+ *
+ * @example
+ * ```ts
+ * getByPath({ trigger: { ticketId: "123" } }, "trigger.ticketId")
+ * // => "123"
+ * ```
+ */
+declare function getByPath(obj: Record<string, JsonValue>, path: string): JsonValue | undefined;
+/**
+ * Set a nested value by dot path, creating objects along the way.
+ * @param obj - Target object (mutated in place)
+ * @param path - Dot-separated path
+ * @param value - Value to set
+ *
+ * @example
+ * ```ts
+ * const ctx = {};
+ * setByPath(ctx, "steps.analyze.output", { summary: "..." });
+ * // ctx => { steps: { analyze: { output: { summary: "..." } } } }
+ * ```
+ */
+declare function setByPath(obj: Record<string, JsonValue>, path: string, value: JsonValue): void;
+/**
+ * Delete a nested value by dot path.
+ * @param obj - Target object (mutated in place)
+ * @param path - Dot-separated path
+ */
+declare function deleteByPath(obj: Record<string, JsonValue>, path: string): void;
+/**
+ * Check if a string is a template reference.
+ */
+declare function isTemplate(value: string): boolean;
+/**
+ * Extract path from a template string.
+ * @returns The path if it's a template, null otherwise
+ */
+declare function extractTemplatePath(value: string): string | null;
+/**
+ * Resolve templates of the form "{{some.path}}" inside JSON values deterministically.
+ *
+ * Supports:
+ * - Strings equal to "{{path}}" → replaced with value at path
+ * - Objects/arrays → recursively resolved
+ * - Other primitives → passed through unchanged
+ *
+ * @param ctx - Run context object (JSON-like)
+ * @param input - Input value containing potential templates
+ * @returns Resolved value with templates replaced
+ *
+ * @example
+ * ```ts
+ * const ctx = { trigger: { ticketId: "T-123" } };
+ * resolveTemplates(ctx, { id: "{{trigger.ticketId}}" });
+ * // => { id: "T-123" }
+ * ```
+ */
+declare function resolveTemplates(ctx: Record<string, JsonValue>, input: JsonValue): JsonValue;
+/**
+ * Resolve a step input object using run context.
+ * Convenience wrapper around resolveTemplates.
+ */
+declare function resolveStepInput(ctx: Record<string, JsonValue>, input: Record<string, JsonValue>): Record<string, JsonValue>;
+/**
+ * Deep clone a JSON value.
+ */
+declare function cloneJson<T extends JsonValue>(value: T): T;
+/**
+ * Merge two JSON objects shallowly.
+ */
+declare function mergeJson(target: Record<string, JsonValue>, source: Record<string, JsonValue>): Record<string, JsonValue>;
+/**
+ * Deep merge two JSON objects.
+ */
+declare function deepMergeJson(target: Record<string, JsonValue>, source: Record<string, JsonValue>): Record<string, JsonValue>;
+
+/**
+ * @fileoverview
+ * Example contract: Ticket Triage Workflow
+ *
+ * This contract demonstrates an autonomous agent that:
+ * 1. Analyzes incoming tickets
+ * 2. Classifies priority and category
+ * 3. Assigns to appropriate team
+ * 4. Emits status updates
+ */
+
+/**
+ * Ticket Triage Contract
+ *
+ * Triggered by: ticket.created
+ * Permissions: Read tickets, emit events, invoke LLM
+ */
+declare const ticketTriageContract: CodmirContract;
+
+/**
+ * @fileoverview
+ * Example contract: Code Review Workflow
+ *
+ * This contract demonstrates an autonomous agent that:
+ * 1. Analyzes pull request changes
+ * 2. Checks for code quality issues
+ * 3. Suggests improvements
+ * 4. Posts review comments
+ * 5. Waits for author response (human-in-the-loop)
+ */
+
+/**
+ * Code Review Contract
+ *
+ * Triggered by: github.pull_request.opened, github.pull_request.synchronize
+ * Permissions: Read repo, emit events, invoke LLM, post comments
+ */
+declare const codeReviewContract: CodmirContract;
+
+/**
+ * @fileoverview
+ * PR Analysis Contract
+ *
+ * This contract is triggered by GitHub App webhooks (not GitHub Actions)
+ * when a pull request is opened, synchronized, or reopened.
+ *
+ * It replaces the ai-pr-review.yml GitHub Actions workflow with
+ * event-driven execution through the Codmir engine.
+ */
+
+/**
+ * PR Analysis Contract
+ *
+ * Triggered by: github.pull_request.opened, github.pull_request.synchronize, github.pull_request.reopened
+ * Permissions: Read repo, emit events, invoke LLM, post comments via HTTP
+ */
+declare const prAnalysisContract: CodmirContract;
+/**
+ * Enhanced PR Analysis Contract with LLM review
+ *
+ * This version includes AI-powered code review in addition to static analysis.
+ * Use this for more comprehensive reviews.
+ */
+declare const prAnalysisWithLlmContract: CodmirContract;
+
+/**
+ * @fileoverview
+ * Voice Create Ticket Contract
+ *
+ * Creates a ticket/issue from a voice command.
+ * This is a fast, synchronous action (instant duration).
+ */
+
+declare const voiceCreateTicketContract: CodmirContract;
+
+/**
+ * @fileoverview
+ * Voice Search Codebase Contract
+ *
+ * Searches the codebase for patterns, functions, or files from voice command.
+ * This is a quick action (2-30s depending on codebase size).
+ */
+
+declare const voiceSearchCodebaseContract: CodmirContract;
+
+/**
+ * @fileoverview
+ * Voice Deploy Preview Contract
+ *
+ * Deploys a preview environment from a voice command.
+ * This is a long-running action that requires approval (async).
+ */
+
+declare const voiceDeployPreviewContract: CodmirContract;
+
+/**
+ * @fileoverview
+ * Voice Save Note Contract
+ *
+ * Saves a note or snippet from a voice command.
+ * This is a fast, synchronous action (instant duration).
+ */
+
+declare const voiceSaveNoteContract: CodmirContract;
+
+/**
+ * @fileoverview
+ * Voice Contract Registry
+ *
+ * Central registry for all voice action contracts.
+ * Provides lookup by contract ID or action name.
+ */
+
+/**
+ * All registered voice contracts.
+ */
+declare const VOICE_CONTRACTS: Record<string, CodmirContract>;
+/**
+ * Get a voice contract by its ID.
+ * @param contractId - Contract ID (e.g., "voice.create-ticket")
+ * @returns The contract or undefined if not found
+ */
+declare function getVoiceContract(contractId: string): CodmirContract | undefined;
+/**
+ * Get a voice contract by the action name from the event catalog.
+ * @param actionName - Action name (e.g., "create_ticket")
+ * @returns The contract or undefined if not found
+ */
+declare function getVoiceContractForAction(actionName: string): CodmirContract | undefined;
+
+export { type ApprovalStep, type AuditStep, type BranchStep, type BudgetConfig, type CodmirContract, type ConditionExpr, type ContractId, type ContractLimits, type ContractOutputs, type ContractQuery, type ContractStep, type ContractSummary, type ContractTrigger, ContractValidationError, type ContractVersion, type CostUnit, DEFAULT_GRACE_EXTENSIONS, DURATION_SYNC_THRESHOLDS, type EmitStep, type EthicalAssessment, type EthicalImpact, type EthicalImpactCategory, type EventName, type ExecutionHints, type ExecutionMode, type ExpectedDuration, GRACE_PRINCIPLES, type GraceAuditEvent, type GraceExtensions, type GracePolicyCondition, type GracePolicyRule, type ImpactSeverity, type IsoDateString, type JsonValue, type LlmStep, type Permission, type ResourceAllocation, type RetryPolicy, type ReversibilityConfig, type RunId, type SkillStep, type SocietalImpact, type StepBase, type StepId, type StepKind, type StepTimeout, type TaskStep, type TransformStep, VOICE_CONTRACTS, type ValidationResult, type WaitStep, type WorkforceImpact, and, calculateRiskScore, cloneJson, codeReviewContract, contains, deepMergeJson, deleteByPath, endsWith, eq, evalCondition, exists, extractTemplatePath, getByPath, getVoiceContract, getVoiceContractForAction, gt, gte, hasPermission, isTemplate, lt, lte, mergeJson, neq, not, or, prAnalysisContract, prAnalysisWithLlmContract, requiresHumanReview, resolveStepInput, resolveTemplates, setByPath, startsWith, ticketTriageContract, validateCondition, validateContract, validateContractSafe, voiceCreateTicketContract, voiceDeployPreviewContract, voiceSaveNoteContract, voiceSearchCodebaseContract };