cap: Documentation
Browse Sign In

capdag Documentation

URN matching, capability dispatch, and the Bifaci runtime protocol

Scope

This documentation covers the capdag system: URN semantics, capability dispatch, the Bifaci runtime protocol, and deployed APIs. When a statement here conflicts with source code, code wins.

Implementations exist in Rust (reference), Go, Python, JavaScript, and Swift/Objective-C. All follow identical semantics for canonicalization, matching, dispatch, and specificity.

Terminology

Term Definition
Tagged URN A URN with structure prefix:key1=value1;key2=value2;...
Media URN A Tagged URN with prefix media: describing a data type
Cap URN A Tagged URN with prefix cap: describing a capability
Provider A registered capability that can handle requests
Request A capability URN describing what is needed
Dispatch Routing a request to a valid provider via the dispatch predicate
Specificity A numeric score measuring how constrained a URN is

Document Map

URN Foundations

Document Purpose
URN Syntax Tagged URN grammar, normalization, canonicalization, wildcard truth table
Predicates Derived predicates: accepts, conforms_to, is_comparable, is_equivalent
Specificity Scoring rules, tie behavior by subsystem

Cap URN System

Document Purpose
Cap URN Structure Product structure $C = U \times U \times U$, direction tags, identity cap
Dispatch The dispatch predicate — the central routing rule
Ranking Selection policy among valid dispatch candidates
Media URNs Media type system, coercion tags, form tags

Capability Definitions

Document Purpose
Capability Schema JSON format for Cap definitions, arguments, outputs, media specs
Validation Rules Structural validation rules (CU1-CU2, RULE1-RULE12, MS1-MS3, XV1-XV5)

Runtime and Execution

Document Purpose
Bifaci Protocol Wire format, frame types, CBOR encoding, checksums
Runtime Hosting Cartridge runtime, host runtime, relay topology
Integration Recipes End-to-end request patterns, DAG execution, orchestrator pipeline

Reference

Document Purpose
Libraries Language implementations and usage examples
API Reference Deployed HTTP endpoints for the capability registry
Formal Foundations Mathematical formalization (optional reference)

Reading Order

For those new to capdag, the recommended reading order is:

  1. URN Syntax — understand the base domain
  2. Predicates — learn the four derived predicates
  3. Specificity — understand scoring
  4. Cap URN Structure — see how Cap URNs compose three dimensions
  5. Dispatch — the central routing rule
  6. Ranking — how to choose among valid providers
  7. Media URNs — media type details
  8. Capability Schema and Validation Rules — structural constraints

The runtime and execution documents can be read independently.

The Central Rule

The dispatch predicate determines whether a provider can handle a request:

$$ \text{Dispatch}(p, r) \iff (i_r = \top \lor i_r \preceq i_p) \land (o_r = \top \lor o_p \preceq o_r) \land y_r \preceq y_p $$

This uses mixed variance across three dimensions: contravariant input, covariant output, invariant cap-tags. See Dispatch for the full specification.

Source Priority

  1. capdag/src/** — Rust reference implementation
  2. tagged-urn-rs/src/** — URN library
  3. capdag-dot-com/functions/** — deployed API
  4. This documentation