CogniMesh Approvals — Algorithm Extraction

Algorithmic content extracted from projects/ckamal/src/domains/approvals/ (P0.3) for Colibri absorption. Implementation target: src/domains/approvals/.

ApprovalService API

class ApprovalService extends EventEmitter {

  // Request an approval before executing an action
  async createApproval(type, payload, requesterId, options)
  // → Returns: { approvalId, status: "PENDING", expiresAt }
  // type:        ApprovalType enum
  // payload:     { action, description, riskLevel, context }
  // requesterId: agent ID requesting the action
  // options:     { timeout_ms, escalate_to, priority }

  async approve(approvalId, approverId, comment)
  // → Returns: { approvalId, status: "APPROVED", decidedAt, decidedBy }

  async reject(approvalId, approverId, comment)
  // → Returns: { approvalId, status: "REJECTED", decidedAt, decidedBy, reason: comment }

  async escalate(approvalId, escalatedBy, reason)
  // → Returns: { approvalId, status: "ESCALATED", escalatedTo }

  async listPending(filters)
  // filters: { requesterId?, type?, riskLevel?, createdAfter? }
  // → Returns: approval[] ordered by priority desc, createdAt asc

  async getById(approvalId)
  // → Returns: full approval record including history
}

RiskLevel Enum

const RiskLevel = {
  LOW:      "LOW",      // routine operations, reversible, low impact
  MEDIUM:   "MEDIUM",   // moderate impact, may require review
  HIGH:     "HIGH",     // significant impact, requires human approval
  CRITICAL: "CRITICAL"  // irreversible or high-blast-radius operations
};

Risk level influences which ApprovalType is selected and whether approval can be auto-granted.

ApprovalType Enum

const ApprovalType = {
  AGENT_ACTION:     "AGENT_ACTION",     // generic agent operation requiring sign-off
  CODE_CHANGE:      "CODE_CHANGE",      // modifying source code in a repo
  FILE_DELETE:      "FILE_DELETE",      // deleting a file (irreversible)
  FILE_MODIFY:      "FILE_MODIFY",      // modifying an existing file
  DEPLOYMENT:       "DEPLOYMENT",       // deploying to an environment
  EXTERNAL_CALL:    "EXTERNAL_CALL",    // calling an external API or service
  DATA_EXPORT:      "DATA_EXPORT",      // exporting data outside the system
  ESCALATION:       "ESCALATION",       // escalating to a higher authority
};

Approval Lifecycle

PENDING
  │
  ├─ approve(approvalId) ──────────► APPROVED
  │
  ├─ reject(approvalId)  ──────────► REJECTED
  │
  ├─ escalate(approvalId) ─────────► ESCALATED
  │                                      │
  │                                      └─ (re-enters as new PENDING for escalate_to)
  │
  ├─ timeout (options.timeout_ms)  ─► EXPIRED
  │
  └─ cancel(approvalId)  ──────────► CANCELLED

Terminal states: APPROVED, REJECTED, EXPIRED, CANCELLED
Escalated: creates new approval record for the escalated authority

Approval Status Schema

const ApprovalStatus = {
  PENDING:            "PENDING",            // awaiting decision
  APPROVED:           "APPROVED",           // granted — action may proceed
  REJECTED:           "REJECTED",           // denied — action must not proceed
  CHANGES_REQUESTED:  "CHANGES_REQUESTED",  // conditionally rejected — revise and resubmit
  ESCALATED:          "ESCALATED",          // forwarded to higher authority
  CANCELLED:          "CANCELLED",          // withdrawn by requester
  EXPIRED:            "EXPIRED"             // timeout exceeded without decision
};

Middleware Integration

approval-middleware.js wraps agent actions with an approval gate:

function withApproval(action, getRiskLevel) {
  return async function wrappedAction(context, ...args) {
    const riskLevel = getRiskLevel(context, args);
    const type = mapActionToApprovalType(action);

    const approval = await approvalService.createApproval(
      type,
      { action: action.name, context, riskLevel },
      context.agentId,
      { timeout_ms: 300000 }  // 5 minute default
    );

    // Poll or await approval decision
    const decision = await waitForDecision(approval.approvalId);

    if (decision.status === 'APPROVED') {
      return action(context, ...args);
    } else {
      throw new ApprovalDeniedError(decision.status, decision.reason);
    }
  };
}

Integration with β Task Pipeline: Agent actions decorated with withApproval pause at the APPLY phase, emit a pending approval event, and resume only when the approval resolves. High risk-level actions (HIGH, CRITICAL) are never auto-approved; they require human decision via the UI or PM workflow.

Events emitted by ApprovalService:

approval.created — new approval request submitted
approval.decided — any terminal decision (approved/rejected/expired)
approval.escalated — escalation occurred

Colibri Absorption Target

Implementation: src/domains/approvals/
Files to create: approval-service.js, approval-middleware.js
Database table: approvals (id, type, status, requester_id, payload, risk_level, created_at, decided_at, decided_by, comment)
Integration point: β task pipeline APPLY phase gate
See implementation guide: [[guides/implementation/ckamal-extraction-guide CogniMesh Extraction Guide]] P0.3