ARC-OS Quick Reference

Quick commands and examples for using ARC-OS

---

Authentication

# Login
curl -X POST https://api.arcos.app/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password"}'

# Set token
export TOKEN="your-jwt-token"
export TENANT="your-tenant-id"

---

Proof-Gated Orchestration (Recommended for Regulated Workflows)

Three-Phase Approach: Compile → Plan → Execute

Phase 1: Compile (NL → Typed Intent)

curl -X POST https://api.arcos.app/api/autonomy/compile \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "Run ADP/ACP compliance test for plan cycle 2024",
    "context": {"planCycleId": "cycle-uuid"},
    "autonomyMode": "guided"
  }'

Phase 2: Plan (Intent → Execution Plan)

curl -X POST https://api.arcos.app/api/autonomy/plan \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "intentId": "intent-uuid",
    "autonomyMode": "guided"
  }'

Phase 3: Execute (Plan → Deterministic Runtime)

curl -X POST https://api.arcos.app/api/autonomy/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "plan-uuid",
    "autonomyMode": "guided",
    "approvals": []
  }'

Legacy Orchestration (Quick Execute)

# Single-phase for quick scenarios
curl -X POST https://api.arcos.app/api/autonomous/orchestrate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "Process late deposit correction: $50k deposited 5 days late",
    "context": {"planId": "plan-uuid", "planCycleId": "cycle-uuid"},
    "useProofGated": false
  }'

---

Complete Plan Year Cycle

curl -X POST https://api.arcos.app/api/v1/day-in-the-life/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "plan-uuid",
    "clientId": "client-uuid",
    "planName": "Acme 401(k)",
    "planType": "401k",
    "periodStart": "2024-01-01",
    "periodEnd": "2024-12-31",
    "participantCount": 143
  }'

---

Evidence Bundles

# Create bundle
curl -X POST https://api.arcos.app/api/evidence \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bundleType": "PlanYear",
    "planCycleId": "cycle-uuid",
    "references": [{"type": "DataSnapshot", "id": "snapshot-uuid"}],
    "ruleVersions": [{"ruleId": "ADP", "version": "1.0", "effectiveDate": "2024-01-01"}]
  }'

# Seal bundle
curl -X POST https://api.arcos.app/api/evidence/BUNDLE_ID/seal \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"immutabilityLevel": "sealed"}'

# Get bundle
curl -X GET https://api.arcos.app/api/evidence/BUNDLE_ID \
  -H "Authorization: Bearer $TOKEN"

# Export bundle
curl -X GET "https://api.arcos.app/api/evidence/BUNDLE_ID/export?format=pdf" \
  -H "Authorization: Bearer $TOKEN"

---

Workflows

# Transition workflow
curl -X POST https://api.arcos.app/api/workflows/WORKFLOW_ID/transition \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"instanceId": "instance-uuid", "toState": "ComplianceTesting"}'

# Get workflow state
curl -X GET "https://api.arcos.app/api/workflows/WORKFLOW_ID/state?instanceId=instance-uuid" \
  -H "Authorization: Bearer $TOKEN"

# Replay workflow
curl -X POST https://api.arcos.app/api/workflows/replay \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"correlationId": "correlation-uuid", "sandbox": true}'

---

GraphQL Examples

# Get plan cycle with evidence
query {
  planCycle(id: "cycle-uuid") {
    id
    periodStart
    periodEnd
    evidenceBundles {
      id
      bundleType
      status
      seal {
        sealed_at
        merkle_root_hash
      }
    }
  }
}

# Get workflow state
query {
  workflow(workflowId: "WF.plan_cycle.lifecycle.v1", instanceId: "instance-uuid") {
    id
    currentState
    transitions {
      from
      to
      event
    }
  }
}

curl -X POST https://api.arcos.app/api/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "query { planCycle(id: \"cycle-uuid\") { id evidenceBundles { id } } }"}'

---

Real-Time Updates (SSE)

// Subscribe to updates
const sse = new EventSource(
  `https://api.arcos.app/api/sse?token=${TOKEN}&correlationId=${CORRELATION_ID}`
);

sse.onmessage = (event) => {
  const update = JSON.parse(event.data);
  console.log('Update:', update);
};

---

Common Scenarios

Late Deposit Correction (Proof-Gated)

Compile:

curl -X POST https://api.arcos.app/api/autonomy/compile \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "scenario": "Late deposit: $50k, 5 days late. Calculate lost earnings, get approval, execute correction.",
    "context": {"planId": "plan-uuid", "planCycleId": "cycle-uuid", "amount": 50000, "daysLate": 5},
    "autonomyMode": "guided"
  }'

Plan:

curl -X POST https://api.arcos.app/api/autonomy/plan \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"intentId": "intent-uuid", "autonomyMode": "guided"}'

Execute (after approval):

curl -X POST https://api.arcos.app/api/autonomy/execute \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "planId": "plan-uuid",
    "autonomyMode": "guided",
    "approvals": [{"approvalId": "approval-uuid", "status": "approved", "approverId": "sponsor-uuid"}]
  }'

Compliance Testing

curl -X POST https://api.arcos.app/api/autonomous/orchestrate \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "scenario": "Run ADP/ACP and top-heavy tests for plan cycle 2024",
    "context": {"planCycleId": "cycle-uuid"}
  }'

Audit Response

curl -X POST https://api.arcos.app/api/autonomous/orchestrate \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "scenario": "Respond to DOL audit: assemble evidence bundles for plan year 2024, export with redaction",
    "context": {"planCycleId": "cycle-uuid", "auditNoticeId": "notice-uuid"}
  }'

Plan Merger

curl -X POST https://api.arcos.app/api/autonomous/orchestrate \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "scenario": "Merge Plan A (200 participants) with Plan B (150 participants). Map data, reconcile, validate compliance.",
    "context": {"planAId": "plan-a-uuid", "planBId": "plan-b-uuid"}
  }'

---

Key Endpoints

| Endpoint | Method | Purpose |

|----------|--------|---------|

| /api/autonomy/compile | POST | Compile NL → Typed Intent (Phase 1) |

| /api/autonomy/plan | POST | Generate Plan with Policy Gates (Phase 2) |

| /api/autonomy/execute | POST | Execute Plan with Deterministic Runtime (Phase 3) |

| /api/autonomous/orchestrate | POST | Legacy single-phase orchestration (quick execute) |

| /api/v1/day-in-the-life/execute | POST | Complete plan year cycle |

| /api/evidence | POST | Create evidence bundle |

| /api/evidence/[id]/seal | POST | Seal evidence bundle |

| /api/evidence/[id]/export | GET | Export evidence bundle |

| /api/workflows/[id]/transition | POST | Transition workflow state |

| /api/workflows/[id]/state | GET | Get workflow state |

| /api/workflows/replay | POST | Replay workflow events |

| /api/graphql | POST | GraphQL queries |

| /api/sse | GET | Real-time updates (SSE) |

---

Workflow States

Plan Cycle Lifecycle

PlanCycleCreated → DataCollection → DataValidation → 
PayrollReconciliation → ComplianceTesting → 
CorrectionsRequired? → FilingPreparation → 
FilingSubmission → CycleSealed

Correction Case Lifecycle

CaseOpened → ErrorClassified → PathSelected → 
CalculationComplete → ApprovalRequested → 
Approved → CorrectionExecuted → CaseClosed

Compliance Testing

TestInitialized → TestExecuting → TestComplete → 
ResultsReviewed → Sealed

---

Evidence Bundle Types

• PlanYear - Complete plan year evidence
• Testing - Compliance test evidence
• Filing - Filing submission evidence
• Correction - Correction execution evidence
• Distribution - Distribution processing evidence
• DataCollection - Data collection evidence
• Reconciliation - Reconciliation evidence

---

Tips

1. Use Autonomous Orchestration for new or complex scenarios
2. Always seal evidence bundles when workflows complete
3. Capture correlation IDs for tracking and replay
4. Use GraphQL for complex queries
5. Subscribe to SSE for real-time updates
6. Replay workflows for audit reconstruction

---

Environment Variables

export ARCOS_API_URL="https://api.arcos.app"
export ARCOS_TOKEN="your-jwt-token"
export ARCOS_TENANT="your-tenant-id"

---

For detailed documentation, see [PRACTICAL_USAGE_GUIDE.md](./PRACTICAL_USAGE_GUIDE.md)