PIDL v0.7.0 Release Notes¶

Release Date: 2026-10-19

This release lets one PIDL file describe a whole protocol: its roles and an ordered list of scenarios, with shared steps written once as fragments. Every output follows the file's order, so diagrams, tables, outlines and the slide decks and guides built from them agree. It also brings the fixes prepared since v0.6.0: D2 sequence diagrams, deterministic SVG output, and Windows builds.

Highlights¶

Scenarios: named journeys through the same roles, such as AAuth's five access modes, in one file
Fragments and include steps: shared steps drawn as labeled boxes in PlantUML, Mermaid, D2 and SVG, or expanded in place
Consistent ordering: the entities and scenarios arrays set the order of every output
Overview outputs: roles-by-scenario matrix, token table, and an ordered outline in Markdown and JSON
Token verification: record who checks each token and claim and who signs each request; new analyzer rules follow tokens through a scenario
AAuth example: draft-hardt-oauth-aauth-protocol-11 with its five access modes

What's New¶

Scenarios¶

{
  "scenarios": [
    {
      "id": "ps-authorization",
      "name": "PS authorization (three-party)",
      "flows": [
        {"include": "person-token"},
        {"from": "agent", "to": "resource", "action": "authorize"},
        {"include": "consent"}
      ]
    },
    {"id": "consent", "name": "User consent", "fragment": true, "flows": [ ... ]}
  ]
}

A file has either flows, which works exactly as before, or scenarios. See the Scenarios guide and the specification.

Command Line¶

Command	What it does
`pidl scenarios <file>`	Lists scenarios in output order
`generate --scenario <id>`	Renders one scenario
`generate --all-scenarios -o <dir>`	Writes `01-<id>.svg`, `02-<id>.svg`, … in file order
`generate --expand`	Shows included fragments step by step
`generate -f scenario-matrix`	Roles by scenario
`generate -f token-table`	Tokens, checkers, claims and the scenarios that use them
`generate -f outline` / `outline-json`	Ordered outline for guides and decks
`simulate`, `debug`, `analyze --scenario <id>`	Work on one scenario

Token Verification and Analysis¶

Token definitions gain verified_by and claims; flow security gains signed_by, issues and verifies. New rules:

Rule	Reports
SEC017	A role that no flow uses
SEC018	A token checked before any earlier step issues it
SEC019	A request signed by someone other than its sender or the token holder
SEC020	A token checked by an entity not in its `verified_by`
SEC021	A fragment that no scenario includes

In the AAuth example, SEC019 flags federated access, where the PS signs the request to the AS while presenting a resource token delivered to the agent.

Composition and Diff¶

extends and imports merge scenarios, with exclude_scenarios and an import scenarios selector. pidl diff compares scenarios by ID and reports roles and scenarios that moved.

Changes¶

Network boundary diagrams list entities in entities order instead of alphabetically. Sort the entities array to keep the previous layout.
Flow.sequence is deprecated. It is a display-only step number and never affected order.

Fixes¶

D2 sequence diagrams render messages as edges, with quoted labels and correct response direction
Network and trust SVG output, network boundary assignment and pidl diff output no longer depend on map iteration order
Labeled process flows link one output to one input instead of every input
Windows checkouts use LF line endings, so embedded SVG templates and golden tests match other platforms
CLI components and trust no longer crash without a metadata block; the debugger no longer loops at end of input

Upgrading¶

Existing files need no changes. To adopt scenarios, move the top-level flows into a scenario:

{"scenarios": [{"id": "main", "name": "Main flow", "flows": [ ... ]}]}

Installation¶

go install github.com/grokify/pidl/cmd/pidl@v0.7.0