Open general

risk field is advertised to callers (PERMISSIONS.md) but never added to the bridge author contract (BRIDGE_SDK.md) — doc-vs-doc gap

John Lauer · 6d ago

Type: doc/contract gap surfaced during the sample-bridge modernization audit (2026-08-04).

The gap

Three surfaces disagree about whether a bridge can declare a per-verb risk field:

  • skills/PERMISSIONS.md already tells AI callers it exists and gates on it: "bridgeExec": {"note":"bridge exec verbs gate per the bridge's declared risk field"}.
  • skills/PERMISSION_MODEL.md has it as a DESIGN PROPOSAL only: risk: "read"|"input"|"exec"|..., and its own text says "When this ships, the risk field goes into the verb/describe contract in skills/BRIDGE_SDK.md" — which has NOT happened.
  • skills/BRIDGE_SDK.md — grep is clean. risk appears nowhere. A bridge author following the SDK has no way to learn the field exists or what values it takes.
  • src-tauri/src/commands.rs risk_class_for_verb() is a hardcoded AD-core-only match with NO bridge lookup.

So the permission model advertises a bridge-declared risk gate to callers, but (a) bridges are never told to declare it, and (b) AD-core doesn't read it from a bridge even if they did. Neither hello sample declares it, and neither is out of compliance — because the contract doesn't exist yet.

Decision needed (not a silent patch)

Either:

  1. Ship it: add risk to the bridge.json/describe contract in BRIDGE_SDK.md, wire risk_class_for_verb (or the bridge-exec gate) to read the bridge's declared value, and have the samples model it. Then the PERMISSIONS.md note becomes true.
  2. Retract it: if per-bridge risk gating isn't the direction, remove the bridgeExec note from PERMISSIONS.md so callers aren't told about a gate that doesn't exist.

Filing rather than patching because it's a permission-model design call (how a third-party bridge's exec verbs get gated), not a typo. Found while making the hello samples SDK-accurate.

0 Replies

Log in to reply.