openloop-protocol

Hub-Edge Protocol

openloop-protocol is OpenLoop's public, dependency-light collaboration protocol package described in ADR-005. The current root API is the Hub-Edge protocol; OpenLoop's internal Agent Adapter Event Protocol remains private to OpenLoop Core.

This package owns only the wire-safe Team Hub ↔ Local Edge collaboration protocol:

• envelopes and discriminated payloads;
• dependency-free runtime decoders;
• declarative payload shape validation for every message family;
• protocol version negotiation;
• canonical JSON serialization and SHA-256 payload hashes;
• redaction helpers;
• golden fixtures and a compatibility matrix.

It intentionally does not import OpenLoop Core, TeamLoop, a Hub database, HTTP server, Agent SDK, UI code, or local runner implementation.

The prerelease tarball builds src to dist/*.js and dist/*.d.ts before packing so downstream Hub/Edge consumers can import the protocol package without transpiling TypeScript from node_modules.

decodeHubEdgeMessage accepts unknown, validates envelope and payload values at runtime, and returns a correlated envelope union. Consumers can narrow on messageType without recreating wire schemas or asserting payload types. The public payload and decoded-envelope types are inferred from the same message definitions used by the runtime validator.

edge.5 handoff governance projections

0.1.0-edge.5 keeps wire protocol 1.0 and preserves the edge.4 minimal eligibility and snapshot shapes. It deliberately requires a synchronized upgrade for approval because the edge.4 lease-shaped placeholder cannot safely represent PR11B authority. The complete contract prevents either consumer from inventing a sibling wire schema:

• review.eligibility.recorded separates canAccept from canCreateHostedReview; legacy eligible remains an alias of canAccept, while HandoffReadiness is the conjunction of both gates plus Hub currentness. A blocked projection carries Hub-safe blockers and next actions. The complete projection is content-addressed by eligibilityHash.
• handoff.review_snapshot.recorded binds one immutable handoff candidate to the exact SharedGoalSpec version and contract hash, source commit/tree/base, eligibility projection, EvidenceReceipt references, hosted-review preflight, optional AcceptanceReceipt, and redaction version. snapshotHash covers the candidate content rather than its storage ID or observation time.
• handoff.approval.recorded binds a reviewer decision to one exact snapshot and approval policy. The complete projection records reviewer role, self-approval policy evaluation, a wire-safe optional note, and approvalHash.

Handoff approval is Hub-to-Edge governance input, not execution authority. Its envelope is Run-scoped and fails closed if leaseId, generation, or fencingCredential is present. The Hub must authenticate the actor, enforce approval-specific RBAC and self-approval policy, prove the snapshot is current, and invalidate it when the handoff candidate changes. Self-approval restrictions apply to positive handoff authority, not to requesting changes or rejecting a candidate. Approval never mutates Goal acceptance.

acceptanceReceiptRef.payloadHash is the raw lowercase 64-character value returned by the exported payloadHash() helper for the referenced acceptance payload. Content hashes such as snapshotHash remain explicitly sha256:- prefixed; the two forms are not interchangeable.

Eligibility and snapshot projections are all-or-none when any edge.5 field appears. Approval always requires the complete edge.5 projection and rejects the edge.4 lease-shaped placeholder. The exact package rollout remains Hub- first so TeamLoop can prove fixture parity before OpenLoop Edge emits edge.5.

edge.4 trust projections

0.1.0-edge.4 keeps wire protocol 1.0, preserves the edge.3 minimal field shapes, and continues accepting privacy-conforming edge.3 payloads. It also enforces the wire privacy boundary that edge.3 documented but did not validate at value level. Optional fields let upgraded producers send the complete minimal PR11A projections without sending raw logs, diffs, transcripts, credentials, or local paths:

• evidence.receipt.recorded may add tri-state status, canonicalization, commit/tree source identity, checker identity/version, creation time, local-run provenance, verification level, and artifact manifest references.
• acceptance.receipt.recorded may add a stable receipt ID, SharedGoalSpec version, result commit, evidence receipt references, and redaction version.
• artifact.upload.requested may add the exported ArtifactManifest fields: media type, byte size, SHA-256, creation time, redaction status, availability status, and retention class. Producing Run/Attempt identity comes from the authenticated envelope; consentReason is request context, not part of ArtifactManifest.
• artifact.upload.consent may add a userinfo-free HTTPS upload URL, expiry, maximum bytes, media type, and retention class for a scoped, short-lived grant.

The runtime payload types keep those additions optional for edge.3 decode compatibility. Upgraded producers should construct the exported complete EvidenceReceipt, AcceptanceReceipt, and ArtifactManifest types before placing them into their corresponding payloads.

redactedSummary, consentReason, and the other legacy PR11A string fields are bounded to 0–1024 characters and fail closed on absolute-path, credential, transcript, and complete-diff markers. Generic legacy wire strings retain their edge.3 shape semantics. redactForHub applies the leak checks to both JSON keys and values in addition to sensitive-key redaction.

Once any additive fields are present, the decoder requires the complete projection. A complete manifest must have positive integer bytes and matching artifactHash == sha256:<sha256>. A complete upload grant must expire after its message sentAt and no more than 15 minutes later. The Hub remains responsible for live-clock expiry, allowed URL origin, exact scope/ACL, and byte/media/ retention matching against the registered manifest.

acceptance.receipt.recorded retains the lease-shaped envelope only to bind an immutable post-terminal fact to the exact terminal lineage. A Hub may accept it after lease release/expiry only after authenticating the Edge and matching the last Run/Attempt/lease/generation, fencing credential digest, and next sequence. Recording the receipt must never reopen or mutate Run status.