Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
343 lines (262 loc) · 15.6 KB

ARCHITECTURE.md

File metadata and controls

343 lines (262 loc) · 15.6 KB

Architecture Spec

Layer → File → Test → Integration mapping for the Agent Passport System

Generated: 2026-03-01 from source code analysis

---

Layer Map

Each layer has: implementation file(s), type definitions, test file(s), and MCP tools.

Layer 1 — Agent Passport Protocol (Identity + Delegation)

What: Ed25519 cryptographic identity. Delegation chains with scope narrowing. Cascade revocation. Action receipts. Reputation scoring.

Component File Lines
Identity src/core/passport.ts createPassport, signPassport, updatePassport, isExpired
Delegation src/core/delegation.ts ~520 lines. createDelegation, subDelegate, revokeDelegation, cascadeRevoke, validateChain, onRevocation
Crypto src/crypto/keys.ts generateKeyPair, sign, verify (node:crypto Ed25519)
Canonical src/core/canonical.ts Deterministic JSON serialization for cross-language signature compat
Verification src/verification/verify.ts verifyPassport, createChallenge, verifyChallenge
Reputation src/verification/reputation.ts applyReputationEvent, calculateOverallScore
Types src/types/passport.ts AgentPassport, Delegation, ActionReceipt, CascadeRevocationResult
Tests File Count
Identity tests/passport.test.ts Core identity tests
Delegation tests/delegation.test.ts Chain creation, scope narrowing
Cascade tests/cascade.test.ts Cascade revocation, batch revocation
Adversarial tests/adversarial.ts 38 attack scenarios (replay, impersonation, escalation)
Canonical tests/canonical.test.ts Serialization edge cases
MCP Tools Count
generate_keys, join_social_contract, verify_passport 3 (Identity)
create_delegation, verify_delegation, revoke_delegation, sub_delegate 4 (Delegation)

Layer 2 — Human Values Floor

What: 7 universal principles (F-001 through F-007). YAML-defined. Agents attest to floor, compliance is checked. Extensions narrow but never widen.

Component File
Implementation src/core/values.ts
Floor data values/floor.yaml (7 principles, extension framework)
Types Part of src/types/passport.ts (ValuesFloor, FloorPrinciple, FloorAttestation)
Tests File
Values tests/values.test.ts
MCP Tools
load_values_floor, attest_to_floor 2 (shared with Layer 5 policy tools)

Principles:

  • F-001: Traceability (mandatory, technical enforcement)
  • F-002: Honest Identity (mandatory, technical)
  • F-003: Scoped Authority (mandatory, technical)
  • F-004: Revocability (mandatory, technical)
  • F-005: Auditability (mandatory, technical)
  • F-006: Non-Deception (strong consideration, reputation-based)
  • F-007: Proportionality (strong consideration, reputation-based)

Layer 3 — Beneficiary Attribution

What: Merkle proofs for contribution tracking. Every action receipt traces to a human beneficiary. Collaboration attribution for multi-agent work.

Component File
Implementation src/core/attribution.ts
Types Part of src/types/passport.ts (BeneficiaryInfo, AttributionReport, MerkleProof)
Tests File
Attribution tests/attribution.test.ts
MCP Tools
None yet Attribution tools not yet exposed via MCP

Layer 4 — Agent Agora (Communication)

What: Protocol-native signed message feeds. Topics, threading, author registry. Every message is Ed25519 signed and verifiable.

Component File Lines
Implementation src/core/agora.ts ~196 lines
Types src/types/agora.ts AgoraMessage, AgoraFeed, AgoraAgent, AgoraRegistry
Tests File
Agora tests/agora.test.ts
MCP Tools Count
post_agora_message, get_agora_topics, get_agora_thread, get_agora_by_topic, register_agora_agent 5

Layer 5 — Intent Architecture + Policy Engine

What: Two sub-systems. (a) Intent: roles, deliberation, consensus, tradeoff evaluation, precedents. (b) Policy: 3-signature chain (intent → evaluation → receipt), FloorValidatorV1.

Component File Lines
Intent src/core/intent.ts Roles, deliberation, consensus rounds, precedents
Policy src/core/policy.ts ~427 lines. createActionIntent, evaluateIntent, FloorValidatorV1
Types (intent) src/types/intent.ts AgentRole, IntentDocument, Deliberation, ConsensusRound
Types (policy) src/types/policy.ts ActionIntent, PolicyDecision, PolicyReceipt, ValidationContext
Tests File
Policy tests/policy.test.ts
MCP Tools Count
create_intent, evaluate_intent 2 (shared with Layer 2 values tools)

3-Signature Chain:

  1. Agent declares intent (createActionIntent → signed ActionIntent)
  2. Policy engine evaluates (evaluateIntent → PolicyDecision with verdict)
  3. Execution creates receipt (createPolicyReceipt → signed proof of evaluation)

Layer 6 — Coordination Primitives

What: Full task lifecycle. Task brief → role assignment → evidence submission → review → handoff → deliverable → completion. Designed for multi-agent workflows.

Component File Lines
Implementation src/core/coordination.ts ~562 lines
Types src/types/coordination.ts TaskBrief, EvidencePacket, ReviewDecision, Deliverable, TaskCompletion
Tests File
Coordination tests/coordination.test.ts
MCP Tools Count
create_task_brief, assign_agent, accept_assignment, submit_evidence, review_evidence, handoff_evidence, get_evidence, submit_deliverable, complete_task, get_my_role, get_task_detail 11

Task Lifecycle:

create_task_brief → assign_agent → accept_assignment
  → submit_evidence → review_evidence (approve/rework/reject)
    → handoff_evidence → submit_deliverable
      → complete_task (with retrospective)

Layer 7 — Integration Wiring

What: Bridge functions that connect isolated layers. No modifications to existing layers — pure composition.

Component File Lines
Implementation src/core/integration.ts ~381 lines
Bridge What It Connects
commerceWithIntent() Commerce → Intent/Policy. Creates intent, evaluates via policy, then runs preflight.
commerceReceiptToActionReceipt() Commerce → Attribution. Converts CommerceActionReceipt to standard ActionReceipt for Merkle proofs.
validateCommerceDelegation() Commerce → Delegation. Validates CommerceDelegation against protocol Delegation (scope, spend, signature).
coordinationToAgora() Coordination → Agora. Auto-posts task lifecycle events as signed Agora messages.
postTaskCreated() Convenience: post "task created" to Agora feed.
postReviewCompleted() Convenience: post "review completed" to Agora feed.
postTaskCompleted() Convenience: post "task completed" with metrics to Agora feed.
Tests File Count
Integration tests/integration-wiring.test.ts 14 tests
MCP Tools
None directly Integration is used internally by MCP commerce tools (commerceWithIntent called by commerce_preflight)

Layer 8 — Agentic Commerce (ACP)

What: 4-gate checkout pipeline. Human approval for purchases. Spend tracking and limits. Based on Agentic Commerce Protocol concepts.

Component File Lines
Implementation src/core/commerce.ts ~535 lines
Types src/types/commerce.ts ACPCheckoutSession, ACPLineItem, ACPMoney, CommerceDelegation
Tests File Count
Commerce tests/commerce.test.ts 17 tests
MCP Tools Count
commerce_preflight, get_commerce_spend, request_human_approval 3

4-Gate Pipeline:

  1. Passport gate — agent has valid, non-expired identity
  2. Delegation gate — agent has commerce delegation with sufficient scope
  3. Merchant gate — merchant is on approved list
  4. Spend gate — amount within delegation spend limit

Agent Attestation Architecture (Consilium Build — Day 42)

What: Four-tier evidence model for passport issuance. Passport grades 0-3. Tier 0 silent observation. Challenge-response runtime attestation. Workspace manifest. Recovery with cryptographic proof. Post-issuance behavioral sequence tracking. Endorsement latency. Gateway bridge.

Component File Lines
Types src/types/attestation.ts PassportGrade, ObservedContext (closed Tier 0), IssuanceEvidenceRecord, IssuanceAssessment, RuntimeAttestation, ProviderAttestation, WorkspaceManifest, WorkspaceCheckpoint, RecoveryRequest, RecoveryResult, IssuanceChallenge, AttestationFlag
Core functions src/core/attestation.ts createIssuanceChallenge, verifyRuntimeAttestation, computePassportGrade, computeAttestationFlags, computeAttestationBundleHash, createIssuanceContext, bindAttestation, createWorkspaceManifest, createEmptyEvidenceRecord
Passport extension src/types/passport.ts attestation?: PassportAttestationSummary on SignedPassport (backward compatible)
Tests File Count
Attestation tests/attestation.test.ts 55 tests: types, challenge, runtime verification, grade computation, flags, binding, workspace manifest, evidence records, E2E 5-phase flow, consilium mandatory corrections
MCP Tools Count
issue_passport (enhanced), get_passport_grade, list_issuance_records, get_behavioral_sequence 4 (3 new + 1 enhanced)
Gateway (private) Route
Trust profile GET /passport/:agentId/trust-profile
Issuance dossier POST /issuance-dossier
Convergence GET /convergence/destinations
Sybil 4-gate Built into provisionWallet()

Integration Architecture

How layers connect at runtime:

                    ┌─────────────────────┐
                    │  Layer 8: Commerce   │
                    └─────────┬───────────┘
                              │ commerceWithIntent()
                    ┌─────────▼───────────┐
                    │  Layer 5: Policy     │  ← evaluateIntent() checks floor
                    └─────────┬───────────┘
                              │ references
                    ┌─────────▼───────────┐
                    │  Layer 2: Values     │  ← floor.yaml principles
                    └─────────────────────┘

                    ┌─────────────────────┐
                    │  Layer 6: Coord      │
                    └─────────┬───────────┘
                              │ coordinationToAgora()
                    ┌─────────▼───────────┐
                    │  Layer 4: Agora      │  ← lifecycle events become signed messages
                    └─────────────────────┘

                    ┌─────────────────────┐
                    │  Layer 8: Commerce   │
                    └─────────┬───────────┘
                              │ commerceReceiptToActionReceipt()
                    ┌─────────▼───────────┐
                    │  Layer 3: Attribution│  ← commerce receipts → Merkle proofs
                    └─────────────────────┘

                    ┌─────────────────────┐
                    │  Layer 8: Commerce   │
                    └─────────┬───────────┘
                              │ validateCommerceDelegation()
                    ┌─────────▼───────────┐
                    │  Layer 1: Delegation │  ← commerce scope within protocol scope
                    └─────────────────────┘

High-Level API (contract.ts)

For users who don't need individual layers:

Function What It Does
joinSocialContract() Create passport + attest to floor + set beneficiary in one call
verifySocialContract() Verify another agent's passport + floor attestation
delegate() Create delegation with scope + spend limits
recordWork() Sign an action receipt for completed work
proveContributions() Generate Merkle proofs of all contributions
auditCompliance() Check agent against Values Floor

Agent Context — Enforcement Middleware (context.ts)

Wraps an agent in an automatic compliance boundary. Every action goes through the 3-signature chain without the agent needing to call protocol functions manually.

Component File Lines
Implementation src/core/context.ts ~421 lines. AgentContext class, createAgentContext()
Types src/types/context.ts ~140 lines. AgentContextConfig, ExecuteRequest, ExecuteResult, AuditEntry
Tests File Count
Context tests/context.test.ts 26 tests, 9 suites

Enforcement Levels:

  • auto — Every execute() call runs the 3-signature chain automatically
  • manual — Agent must call protocol functions themselves (tracking only)
  • strict — Same as auto, reserved for additional constraints

Execute Flow:

ctx.execute({ type, target, scope })
  → finds matching delegation (or denies)
  → creates ActionIntent (signature 1)
  → evaluateIntent via FloorValidatorV1 (signature 2)
  → returns ExecuteResult { permitted, intent, decision }
ctx.complete(result, { status, summary })
  → creates ActionReceipt (signature 3)
  → creates PolicyReceipt
  → logs to audit trail

Key Features:

  • Delegation management: addDelegation(), removeDelegation(), findDelegation()
  • Spend tracking: cumulative spend across actions, auto-narrowing when near limit
  • Audit log: every action attempt recorded with timestamp, verdict, signatures
  • Callbacks: onPolicyDecision, onDenied for real-time monitoring
  • Custom evaluator: separate identity for policy evaluation

Type System Summary

All types are in src/types/. Key inheritance / composition patterns:

  • AgentPassport → signed with signPassport() → verified with verifyPassport()
  • Delegation → contains scope: string[], spendLimit → narrowed via subDelegate()
  • ActionReceipt → signed proof of work → used by computeAttribution()
  • AgoraMessage → contains AgoraMessageContent + signature → appended to AgoraFeed
  • ActionIntent → signature 1 of 3 → evaluated by PolicyDecision → proved by PolicyReceipt
  • TaskBrief → drives full coordination lifecycle → produces EvidencePacket → ReviewDecision → Deliverable
  • ACPCheckoutSession → contains ACPLineItem[] → gated by CommerceDelegation
  • AgentContext → wraps SocialContractAgent + ValuesFloor + Delegation[] → enforces 3-sig chain on every execute()