Skip to content

PIDL v0.4.0 Release Notes

Release Date: 2026-06-28

This release introduces protocol composition, runtime execution simulation, protocol comparison, interactive debugging, and security analysis capabilities.

Highlights

  • Protocol composition with imports and inheritance for modular protocol design
  • Runtime execution engine with state tracking and execution traces
  • Protocol comparison (diff) for detecting changes between protocols
  • Interactive step-through debugger with breakpoints and state inspection
  • Security analysis with 10 built-in attack surface detection rules

What's New

Protocol Composition

Build modular protocols with imports and inheritance:

# Resolve imports and extends to output merged protocol
pidl resolve protocol-with-imports.json

Features:

  • Import entities and phases from other protocols with optional aliasing
  • Extend base protocols with exclusion filters
  • Standard library of common protocols (examples/stdlib/)
  • Circular import/extends detection
  • Automatic resolution in generate command

Example composition:

{
  "protocol": {
    "id": "my-oauth",
    "name": "My OAuth Extension"
  },
  "extends": {
    "path": "stdlib/oauth_entities.json",
    "exclude_phases": ["optional_refresh"]
  },
  "imports": [
    {
      "path": "stdlib/mcp_entities.json",
      "entities": ["mcp_client", "mcp_server"],
      "alias": "mcp"
    }
  ]
}

Protocol Simulation

Run protocol simulations with state tracking:

# Run full simulation
pidl simulate protocol.json

# Verbose with step-by-step output
pidl simulate -v protocol.json

# Output trace as SVG
pidl simulate --trace-format=svg --trace-output=trace.svg protocol.json

# Output trace as JSON
pidl simulate -json protocol.json

Features:

  • Protocol execution engine with flow-by-flow processing
  • Entity state tracking with initial state initialization
  • Execution trace recording with timestamps
  • Conditional flow evaluation with custom evaluators
  • State mutation validation

Protocol Comparison

Compare two protocols to detect changes:

# Compare protocols
pidl diff base.json updated.json

# Output as markdown
pidl diff -f markdown base.json updated.json

# Summary only
pidl diff -q base.json updated.json

Comparison detects:

  • Added, removed, and modified entities
  • Added, removed, and modified flows
  • Phase changes
  • Metadata differences

Interactive Debugger

Step through protocol execution with breakpoints:

pidl debug protocol.json

Commands:

Command Description
step, s Execute next flow
continue, c Run until breakpoint or completion
break <idx> [cond] Set breakpoint at flow index
delete <idx> Remove breakpoint
breakpoints List all breakpoints
inspect Show current state
inspect entity <id> Show entity details and state
inspect flow <idx> Show flow details
list List flows with position marker
set <entity> <state> Set entity state
reset Restart execution
quit, q Exit debugger

Features:

  • Conditional breakpoints with state expressions
  • Entity state inspection and modification
  • Execution trace access
  • Flow listing with execution markers

Security Analysis

Analyze protocols for security risks:

# Run security analysis
pidl analyze protocol.json

# Output as markdown
pidl analyze -f markdown -o security-report.md protocol.json

# Fail if high-severity risks found (for CI)
pidl analyze --fail-on=high protocol.json

# Filter by severity
pidl analyze --min-severity=high protocol.json

Built-in security rules:

Rule Severity Description
SEC001 High Trust boundary violation (untrusted to trusted without security)
SEC002 High Missing encryption on confidential flow
SEC003 Medium Unbound bearer token (no mTLS/DPoP binding)
SEC004 High Missing authentication on external flow
SEC005 Medium JWT without defined audience
SEC006 Medium Token transmitted in redirect
SEC007 Medium Missing mTLS on sensitive flow
SEC008 Low Entity without defined trust level
SEC009 Medium Sensitive data in redirect parameters
SEC010 Medium Weak authentication method

Output includes:

  • Risk details with location and remediation
  • Summary by severity and category
  • Security score (0-100)

CLI Enhancements

New commands:

Command Description
simulate Run protocol simulation with state tracking
diff Compare two protocols
debug Interactive step-through debugger
analyze Security analysis
resolve Resolve protocol imports and inheritance

New simulate options:

Flag Description
-steps Maximum steps to execute
-v Verbose output
-json Output trace as JSON
--trace-format Trace format: text, json, svg, mermaid
--trace-output Write trace to file

Go Library

New packages and types:

import (
    "github.com/grokify/pidl"
    "github.com/grokify/pidl/analyze"
)

// Protocol composition
resolved, err := pidl.ResolveProtocol(protocol, basePath)

// Execution
executor := pidl.NewExecutor(protocol)
trace, err := executor.Execute()

// Comparison
diff := pidl.Compare(base, updated, pidl.DiffOptions{})

// Debugging
session := pidl.NewDebugSession(protocol)
session.SetBreakpoint(3, "client.state == \"waiting\"")
step, _ := session.Step()

// Security analysis
analysis := analyze.Analyze(protocol, analyze.DefaultAnalysisOptions())
if analysis.HasRisksAtOrAbove(analyze.SeverityHigh) {
    // handle risks
}

Migration

Existing PIDL files remain fully compatible. New fields (imports, extends) are optional and enable composition features.

Documentation

License

MIT License