Specification + Parser path

• Front end = Specification. Backend = Parser and Executors.

What this means

• Specification (Spec) is a human and machine readable contract that defines Intents, Capabilities, Policies, Offers, Receipts, and message envelopes.
• Parser ingests a spec and generates runtime artifacts such as validators, codecs, routers, and negotiation logic.

Components

• Spec authoring format: JSON Schema or JSON-LD contexts with content addressing.
• Spec registry: CAS that stores versioned schemas and extension packs.
• Spec parser: builds parsers, type definitions, validators, and stubs.
• Runtime bindings: codegen for Python, Go.
• Policy hooks: pre, run, post evaluation stages.
• Verification suite: signature and hash checkers for all objects.

Developer workflow

• Author or import a spec for a domain capability.
• Run the parser to generate types, validators, and wire bindings.
• Implement capability logic behind the generated interface.
• Publish AdvertiseCapability with schema hashes.
• Verify Receipts with parser-generated checkers.

Strengths

• Strong correctness from codegen and validation.
• Rapid adoption by existing teams that prefer API like ergonomics.
• Predictable interop because schemas are explicit and versioned.

Tradeoffs

• Slower evolution when many specs must be updated together.
• Heavier governance for schema changes.
• Expressiveness limited by the schema language chosen.

Example

• Spec fragment for a capability:

{
  "$id": "pl.schema/Capability.v1",   // schema identifier
  "type": "object",                   // this is an object schema
  "properties": {
    "id": { "type": "string" },       // capability identifier
    "provider": { "type": "string" }, // capability provider
    "io": {
      "type": "object",
      "properties": {
        "input": { "type": "array" }, // inputs required
        "output": { "type": "array" } // outputs produced
      },
      "required": ["input", "output"]
    }
  },
  "required": ["id", "provider", "io"]
}

• Parser output: language bindings, a validator, and a negotiation stub that checks IO types, price, SLOs, and policy references.

Where this shines

• Regulated domains with heavy compliance.
• Large vendors that want stability and long term support.
• Interop programs between known counterparties.

DSL + Workflow path

• Front end = Domain Specific Language. Backend = Workflow Engine.

What this means

• DSL is a concise language to express Intents, Plans, Policies, and selection logic.
• Workflow engine compiles DSL to a Task DAG, performs discovery and negotiation, and executes with Receipts.

Components

• Pervasive DSL: minimal syntax for goals, constraints, utility, policy bindings, and feature flags.
• Planner: expands goals into a DAG with bindable capability slots.
• Scheduler: selects providers using trust, policy, cost, and SLO scores.
• State store: event log and memory.
• Verifiers: receipt and attestation checkers.
• Policy Engine: evaluates portable policy objects during planning and at runtime.

DSL sketch

goal: SummarizeDocument
inputs:
  doc: cid:doc-123
constraints:
  length: "<400w"
  deadline: "PT30S"
policy:
  require: [cid:pol-PII-no-exfil]
select:
  optimize: [readability:0.6, coverage:0.4, price:0.2]
plan:
  - map: FetchSections(doc)
  - map: Summarize(section)
  - reduce: MergeSummaries()
  - join: AttachReferences()

Strengths

• High expressiveness for composition and planning.
• Fast iteration since plans evolve without schema releases.
• Good for high flux, evolving and open ended workflows.

Tradeoffs

• Higher runtime complexity in planner and scheduler.
• More moving parts for observability and debugging.
• Requires guardrails to keep DSL safe and predictable.

Where this shines

• Cross domain workflows with frequent change.
• Agent marketplaces and open ecosystems.
• Experimental planning and federated operators.

---

Interop between the two paths

• You can mix both paths in one network.
• Spec to DSL: a generator emits DSL stubs from specs. The DSL then composes these stubs into plans.
• DSL to Spec: stabilized DSL patterns can be frozen into new spec schemas for high assurance use.
• Common substrate: envelopes, identity, attestations, receipts, and policies are identical in both paths.
• Dual discovery: capability descriptors reference both schema ids and optional DSL signatures.

Choosing a path: decision matrix

Context	Prefer Spec + Parser	Prefer DSL + Workflow
Compliance heavy	Yes	Maybe
Rapid iteration	Maybe	Yes
Many independent vendors	Yes	Yes
Evolving / Experimental	Maybe	Yes
Tooling maturity needed	Yes	Maybe
Complex composition	Maybe	Yes

Governance and versioning

Spec path

• Version contracts: v1, v1.1 with strict compatibility rules.
• Change control: proposals, review, and test vectors.
• Deprecation: sunset schedules with auto negotiation.

DSL path

• Language stability tiers: core stable, experimental extensions.
• Capability libraries: published DSL macros with hashes.
• Feature flags: negotiate exact sets per Offer.

---

Security model alignment

• Both paths use the same envelope security: signatures, nonces, replay limits, and content hashes.
• Spec path prefers static allowlists and formal verification of schemas.
• DSL path prefers sandboxed planners, policy guards, and taint tracking during plan expansion.

---

Performance and scaling

Spec path

• Lower overhead per call, strong caching by schema id.
• Best for hot paths like inference or CRUD style ops.

DSL path

• Optimizes across the whole DAG.
• Good for map, reduce, join, and cross provider execution.

Concrete example end to end

Spec capability:

{
  "id":"cid:cap-summarize-v1",
  "schema":"pl.schema/Capability.v1",
  "provider":"did:agent:B",
  "io":{"input":[{"type":"text/plain"}],"output":[{"type":"text/markdown"}]},
  "policy_requirements":["cid:pol-PII-no-exfil"]
}

DSL plan that composes it:

goal: BriefingPack
inputs: { docs: [cid:d1, cid:d2, cid:d3] }
plan:
  - map: SummarizeDocument(docs[*]) using cid:cap-summarize-v1
  - reduce: MergeSummaries()
  - join: AttachCitations()
policy:
  require: [cid:pol-PII-no-exfil]
select:
  optimize: [latency:0.5, price:0.3, quality:0.2]

The workflow engine discovers providers for cid:cap-summarize-v1, negotiates Offers, executes map tasks, verifies Receipts, reduces, joins, and emits a final Receipt tied to the same trace.