Add doc-approval.extract capability contract, WASM agent, and app manifest

[enricopiovesan]

Summary

Add the doc-approval.extract capability and doc-approval app manifest to the Traverse runtime. This is the capability backing the doc-approval multi-platform reference app in App-References.

It demonstrates: conditional state machine transitions, human-in-the-loop routing, multi-actor sessions (submitter + approver), and the UMA "AI proposes, authority decides" pattern.

Capability contract

Capability ID: doc-approval.extract

Input:

{
  "document": "string",
  "document_type": "invoice | contract | policy | report | null"
}

Output (runtime-owned — all clients render only):

{
  "document_type": "invoice | contract | policy | report | unknown",
  "extracted_fields": {
    "title": "string",
    "date": "string | null",
    "parties": ["string"],
    "amounts": [{ "value": 0.0, "currency": "string", "description": "string" }],
    "key_clauses": ["string"],
    "summary": "string"
  },
  "recommendation": "approve | review | reject",
  "confidence_score": 0.0,
  "confidence_factors": ["string"]
}

Extraction rules (deterministic, no model dependency)

• document_type: infer from keyword signals (invoice: "invoice", "bill", "amount due"; contract: "agreement", "parties", "whereas"; policy: "policy", "section", "clause"; report: "report", "findings", "analysis")
• title: first line or heading pattern
• date: first date pattern matching ISO, US, or EU format
• parties: lines with "between", "party", named entity patterns (UPPERCASE names, "Inc.", "Ltd.", "Corp.")
• amounts: currency symbol + number patterns
• key_clauses: lines with legal/procedural signal words ("shall", "must", "agree", "terminate", "liable")
• summary: first 280 chars of body text (after heading)
• confidence_score: 0.0–1.0 based on: how many fields were extracted (each adds weight), how unambiguous the document_type is, whether required fields (title, date) were found
• recommendation: approve if confidence ≥ 0.85; review if 0.5 ≤ confidence < 0.85; reject if confidence < 0.5
• confidence_factors: list of plain-English reasons: "date not found", "document type ambiguous", "no parties identified"

All deterministic — no AI/model call. Same document → same output every time.

App manifest state machine

{
  "kind": "app_manifest",
  "app_id": "doc-approval",
  "version": "0.1.0",
  "state_machine": {
    "initial_state": "idle",
    "list_context_fields": [
      "output.document_type",
      "output.confidence_score",
      "output.recommendation",
      "output.extracted_fields.summary"
    ],
    "states": [
      {
        "id": "idle",
        "transitions": [{ "on": "submit", "to": "extracting" }]
      },
      {
        "id": "extracting",
        "invoke": { "capability_id": "doc-approval.extract", "input_from": "command.payload" },
        "transitions": [
          { "on": "capability_succeeded", "condition": { "field": "output.confidence_score", "op": "gte", "value": 0.85 }, "to": "auto_approved" },
          { "on": "capability_succeeded", "condition": { "field": "output.confidence_score", "op": "lt", "value": 0.85 }, "to": "pending_review" },
          { "on": "capability_failed", "to": "extraction_error" }
        ]
      },
      {
        "id": "auto_approved",
        "transitions": [{ "on": "reset", "to": "idle" }]
      },
      {
        "id": "pending_review",
        "transitions": [
          { "on": "approve", "to": "approved" },
          { "on": "reject", "to": "rejected" }
        ]
      },
      {
        "id": "approved",
        "transitions": [{ "on": "reset", "to": "idle" }]
      },
      {
        "id": "rejected",
        "transitions": [{ "on": "reset", "to": "idle" }]
      },
      {
        "id": "extraction_error",
        "transitions": [
          { "on": "retry", "to": "extracting" },
          { "on": "reset", "to": "idle" }
        ]
      }
    ]
  }
}

Definition of Done

• Capability contract at contracts/examples/doc-approval/capabilities/extract/contract.json
• WASM agent at examples/doc-approval/extract-agent/ (Rust source + compiled .wasm)
• Agent is deterministic: no network, no model dependency
• App manifest at apps/doc-approval/app.manifest.json with full branching state machine
• traverse-cli app validate --manifest apps/doc-approval/app.manifest.json exits 0
• Conditional transitions evaluated correctly: confidence ≥ 0.85 → auto_approved, < 0.85 → pending_review
• Integration test: 3 documents of varying confidence exercise all three paths (auto_approved, pending_review, extraction_error)
• Same document always produces same output (determinism test)

Requires

• Traverse #536 — conditional transitions spec
• Traverse #525 — app state machine runtime

Unblocks

• App-References: all doc-approval platform clients