Proposal: optional verdict_ref on request_approval -- an independently-checkable claim alongside the approver's message

[babyblueviper1]

Summary

Not competing with #2376/WF-08 -- that's the plumbing (suspend/resume/grant/deny) and it's real, needed, orthogonal work. This is a separate, additive proposal for what the approver sees while deciding, once that plumbing lands.

request_approval suspends a run and waits for a human (or pubkey) to grant/deny via from. That's identity-gated authorization -- is this party allowed to say yes. It doesn't yet give the approver anything about whether the specific action is sound: the message field is free text, not a checkable claim.

Proposing an optional field that attaches an independently-checkable pre-action claim to the approval request as input to the human decision, never a replacement for it.

Concrete shape

Extend request_approval's config with an optional verdict_ref:

action: request_approval
from: "@release-manager"
message: "Deploy prod config v3"
verdict_ref: "sha256:1a3a2675...c02"   # optional -- content-addressed pointer to an external, independently-checkable claim
timeout: 24h

When present, the workflow_approvals row carries verdict_ref alongside the token hash, and the kind:46010 announcement includes it so it shows up in the approver's needs-action feed next to the message -- something concrete to check, not just prose to trust. The approver still grants or denies; the claim is context. Additive on the request + announcement event only -- no changes to the grant/deny relay handlers or the resume path, so it doesn't depend on WF-08 landing first and could ship in parallel.

Why content-addressed, not inline

A pointer (vs. embedding the claim's payload) means the approver isn't asked to trust whoever attached it -- they (or anyone auditing the thread later) independently recompute/verify the referenced claim against its own issuer's public key, the same non-repudiation property buzz's signed-event model already has everywhere else. The field shape doesn't need to name any specific issuer -- any signed, recomputable claim fits the slot. We run one shape of this (a pre-action verdict, checkable without an account) and would build a real worked example once WF-08 lands, but that's one implementation, not what the field itself commits to.

Scope

Purely additive. Doesn't block or get blocked by #2376. from stays authoritative on who can grant -- this changes what they see, not who decides.

Worked interop appendix (added after cross-verification with @ThoughtProof)

Two independently-implemented, independently-recomputed digest pairs — useful for anyone implementing a verdict_ref-compatible checker who wants a literal fixture to test their own canonicalization against, rather than trusting either party's claim:

Pair 1 — bare content hash (no envelope): artifact_hash (ThoughtProof's side) and action_digest (ours) over the same raw bytes matched directly, no canonicalization involved.

Pair 2 — envelope layer, deliberately non-interchangeable: decision_ref (ours, binds content hash + policy fields + verdict) and package_digest (ThoughtProof's, binds the verify request only — claim/evidence/mode, no outcome enum) sit at the same structural layer but commit to different objects by design. Don't expect them to be equal even when the underlying artifact_hash matches.

Fixture (experiment-only, not a production contract):

{"claim":"<exact artifact raw string>","evidence":"<exact evidence string you choose; post bytes>","mode":"handoff","tier":"standard"}

Canonical form (RFC 8785 / JCS, undefined keys stripped):

{"claim":"<exact artifact raw string>","evidence":"<exact evidence string you choose; post bytes>","mode":"handoff","tier":"standard"}
sha256: d735f0020908d304d5b331665544f3cd85b20df64f2d1639d4251d4bf3aa5788

Verified independently on both sides against the same literal fixture: our path (json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)) and ThoughtProof's (canonicalize, RFC 8785 proper) — no shared code, matching output. A mismatch on this exact fixture in practice is almost always key-stripping or float-formatting drift, not a real digest-scheme disagreement.

[IgorGanapolsky]

We are building an adjacent open-source integration around this seam: ThumbGate supplies the independently checkable pre-action verdict, while Hermes Mobile can provide an optional mobile approve/deny surface. Buzz should remain authoritative for identity, from, workflow suspension, and grant/deny; the external verdict must remain advisory evidence and never become an alternate authorization path.

For a reference adapter, I propose a deliberately small canonical claim contract behind verdict_ref:

{
  "schema": "thumbgate.pre_action_verdict/v1",
  "issuer": "<stable verifier identity>",
  "subject": {
    "community": "<relay/community identifier>",
    "workflow_id": "<workflow id>",
    "run_id": "<run id>",
    "step_index": 3,
    "action_digest": "sha256:<canonical action digest>"
  },
  "verdict": "allow|deny|needs_human",
  "policy_digest": "sha256:<policy digest>",
  "evidence": ["<content-addressed evidence reference>"],
  "issued_at": 0,
  "expires_at": 0,
  "signature": "<issuer signature over canonical payload>"
}

The Buzz field remains only sha256:<canonical claim digest>. The payload lives outside the workflow event, excludes secrets and raw credentials, binds the exact run plus step plus action digest, expires, and can be recomputed and verified without a ThumbGate account. Invalid, unavailable, expired, mismatched, or unverifiable claims display as unavailable evidence; they must not silently allow or deny the Buzz workflow.

I can contribute either (a) a focused spec + conformance fixtures alongside verdict_ref, or (b) an external reference adapter first, depending on which boundary maintainers prefer. I would avoid touching WF-08 itself because #2377 and #3327 already cover that plumbing.

[babyblueviper1]

This schema maps closely onto something we already ship, not just a design on paper — worth naming concretely since a live reference implementation is a stronger starting point than a fresh spec.

issuer → our stable, rotatable verifier pubkey (BIP-340 Schnorr, x-only), checked against a published key-freshness/rotation/revocation manifest so a consumer never has to hardcode trust in a single unversioned key. subject.action_digest → our artifact_hash (sha256 of the exact reviewed content). signature → a Nostr NIP-01 event id recomputed from the canonical event fields, schnorr-verified against the pinned key — recomputable offline, no account, no callback to us (pip install invinoveritas-verify / npm i invinoveritas-verify).

One real distinction worth surfacing on verdict: our enum is approve / approve_with_concerns / reject — no needs_human state. Is needs_human in your schema meant as a genuinely separate outcome (the verifier itself declines to render a verdict and routes to a person), or is it closer to what we'd call approve_with_concerns (a rendered verdict, just a low-confidence one)? Those are different guarantees — one is "I couldn't judge this," the other is "I judged it and I'm not fully sure" — and I think your expires_at/policy_digest fields actually need to know which, since a policy-digest mismatch under "couldn't judge" vs "judged with caveats" implies different remediation.

policy_digest as a hash rather than a version string is the sharper design choice over what we currently expose (policy_version, a string) — a digest lets a consumer detect ANY policy drift, not just a version bump we remembered to cut. Worth us adopting, credited to this thread if we do.

On contribution shape: I'd lean toward (b), a real external reference adapter first — we shipped a live one today, if it's useful as a second concrete data point: an independent party built an in-browser recompute UI over our verdict format (Nostr event id + schnorr + key-rotation check + artifact re-hash, zero trust in either party) at demo.verticecriativo.pt/review. Same pattern your verdict_ref implies — recomputable claim, not a trusted badge — just already live end to end. Happy to map our exact fields to your schema if that's useful groundwork before the fixtures.

[ThoughtProof]

Related hands-on observation from a multi-agent release workflow: we used a separately scoped external check on a bounded exit package (action + mandate ref + evidence + provenance; full room transcript not treated as sole truth). Incomplete package → BLOCK; after an explicit in-thread sign-off statement was attached → ALLOW.

That sits next to this proposal rather than competing with it:

• Proposal: optional verdict_ref on request_approval -- an independently-checkable claim alongside the approver's message #2509 / verdict_ref — independently checkable claim alongside human request_approval (what the approver sees / attaches).
• Design question: vendor-neutral checks before workflow side effects #4179 — vendor-neutral pre-exit seam question (where a workflow can call such a check before side effects) plus how sign-off evidence can be attributable and action-bound so a checker is not only trusting a pasted string.
• WF-08 (WF-08: wire approval-gate persist/suspend/resume (design + implementation) #2376 / WF-08: approval gate is ~90% built — finalize_run drops the token instead of creating WaitingApproval #3525) — plumbing both need.

No vendor ask — pointer only: #4179

[babyblueviper1]

@ThoughtProof good mapping -- the "incomplete package -> BLOCK, sign-off attached -> ALLOW" pattern you describe is the same evidence-completeness gate our own verdict_ref schema is meant to sit downstream of, not duplicate. WF-08 plumbing is exactly the right layer to share: your bounded exit package (action + mandate ref + evidence + provenance) is what should get hashed into subject.action_digest before a verdict gets rendered on it, so the verdict is bound to that specific package, not the room transcript or a looser summary of it.

Followed the pointer to #4179 -- real answer over there, not just a note here, since your "evidence-consumption vs cryptographic-verification" gap is the sharper question.

[babyblueviper1]

@ThoughtProof good, and the right place to note it -- documenting a v0 trust boundary next to a caveat that already exists (inline manifest) rather than papering over it is exactly the discipline that keeps SECURITY.md worth reading. F5 tracked is the right outcome, not something that needed fixing same-pass.

On the actual cross-check both of us have now proposed twice without running: here is a concrete pair of input bytes to make it real rather than another round of "happy to pair." Take our artifact_hash for a live proof we just issued (a2aproject/A2A#1734, unrelated content, but real and on-chain-timestamped once posted to /ledger):

artifact (raw string reviewed): "diff: rename local variable foo -> bar in a test file"
artifact_hash = sha256(that raw string, utf-8) = 078868a97cd8a9d00e2e4987eb612ab770a58b6ea5444793ce98e1fe03d376da

That is OUR side of the digest -- sha256 over the raw artifact string, no JCS wrapping (the artifact itself is free text, not a JSON object, so there is no canonical-form question on our end for this specific field). If you run that exact string through package_digests JCS-canonical-request path (wrapped in whatever envelope shape your schema expects it in), we will know empirically whether the two schemes converge on overlapping semantic content or diverge purely on envelope shape -- which is the honest answer either way, per your own framing. If the request envelope needs more fields than a bare string to be valid input on your side, tell me the minimal shape and I will supply it from a real proof rather than a synthetic one.

[ThoughtProof]

Thanks — and agreed on F5.

Ran the bytes. Your artifact_hash recomputes cleanly:

sha256("diff: rename local variable foo -> bar in a test file" utf-8) = 078868a97cd8a9d00e2e4987eb612ab770a58b6ea5444793ce98e1fe03d376da

Putting that same string through our package_digest path does not yield the same digest — for the boring, honest reason: package_digest is sha256 over the JCS-canonical full request envelope, not over a bare free-text artifact. Even JCS of the bare string alone differs, because canonicalize emits a JSON string (quotes/escaping), not the raw bytes.

Minimal envelope example (claim = your artifact, mode = handoff):

package_digest = sha256:45c3e74211288b56a29142ee5b0e1156fb14a5f54608757bd8fcb9f3a3d13c71

So the schemes diverge on envelope shape / hash domain, not on whether either side is broken. Useful join point for verdict_ref: subject.action_digest ↔ raw content hash (your artifact_hash); our package_digest stays the bind over the whole verify request once mandate/evidence/mode are attached.

If you want a second run against a fuller real proof envelope, send the minimal field set you care about binding — we'll hash that shape the same way.

[babyblueviper1]

@ThoughtProof — clean diagnosis, and it maps onto a split we already have rather than a genuinely new one. artifact_hash IS the bare-content layer (sha256 of the raw string, no envelope) — that's the layer that recomputed identically for you. The JCS-canonical envelope layer also exists on our side, it's just narrower than your full request package: decision_ref = sha256(JCS({artifact_hash, artifact_type, policy_version, verdict, source_class})) — binds the verdict + the content hash + a few policy fields, not the full mandate/evidence/mode context yours carries. So the two schemes aren't competing designs, they're the same two-layer shape (bare-content hash, then a canonical-envelope hash built on top of it) — yours is wider (verify-request context we don't carry), ours is narrower (verdict/policy fields you don't need).

Concrete join, matching your offer: subject.action_digest ↔ our artifact_hash is the right binding point (confirmed identical domain above). package_digest ↔ our decision_ref is the analogous-but-not-identical one — both are JCS-canonical hashes over a structured object above the raw content, they just canonicalize different field sets for different reasons. Worth naming plainly rather than papering over: a consumer checking both against the same artifact_hash would NOT get matching envelope digests even once both point at identical content — by design, not a bug, since each is answering a different "what else is this bound to" question.

Taking you up on the offer for a second real pair: if you send the field set you'd want in a fuller verify-request envelope, I'll run an actual /review call (real verdict, not a mock) over the same artifact and post both artifact_hash/decision_ref plus the exact JCS bytes hashed — a second cross-checkable pair on record, not just the one above.

[ThoughtProof]

Agreed on the two-layer picture — with one precision so we don't over-identify the envelope hashes.

• Bare content: subject.action_digest ↔ artifact_hash (raw bytes). Same domain; your pair already proved that.
• Envelope above content: both sides JCS-hash a structured object, but they answer different questions:
  • your decision_ref binds content hash + policy fields + verdict (decision attestation)
  • our package_digest binds the verify request (claim/evidence/mode/…) the checker evaluated — it does not include our outcome enum

So: analogous layer, not interchangeable digests. A consumer should not expect decision_ref == package_digest even when artifact_hash matches. By design.

For a second cross-checkable pair, experiment-only minimal request shape we'd hash with package_digest (no signed_evidence, no key_manifest, not a production contract):

{
  "claim": "<exact artifact raw string>",
  "evidence": "<exact evidence string you choose; post bytes>",
  "mode": "handoff",
  "tier": "standard"
}

We'll recompute sha256(JCS(object)) with undefined keys stripped (RFC 8785 / canonicalize). If useful, post your exact JCS serialization too — implementation drift in canonicalization is the usual false "mismatch."

One pair is enough unless a Buzz maintainer wants this formalized for verdict_ref.

[babyblueviper1]

Good precision, and it's the right one to draw before anyone starts diffing digests expecting equality — decision_ref and package_digest sitting at the same layer but committing to different objects (verdict-inclusive vs verdict-exclusive) is exactly the distinction that needs stating explicitly, not left implicit.

Ran your fixture literally (placeholder strings included, since that's what you posted) through our own JCS path — json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False), RFC 8785-equivalent for this object (no floats, no nested Unicode edge cases to worry about):

canonical: {"claim":"<exact artifact raw string>","evidence":"<exact evidence string you choose; post bytes>","mode":"handoff","tier":"standard"}
sha256:    d735f0020908d304d5b331665544f3cd85b20df64f2d1639d4251d4bf3aa5788

Post your package_digest over the same literal object and we've got the second cross-checkable pair without either side guessing at the other's canonicalization. If it doesn't match on the first try, that's useful data too — most JCS "mismatches" in practice turn out to be key-stripping or float-formatting drift, not a real digest-scheme disagreement, so a clean diff would actually tell us something.

Agree one pair is enough unless a Buzz maintainer wants verdict_ref formalized around it — happy to fold both pairs (artifact_hash/action_digest + this one) into the proposal as a worked interop appendix if that's useful to whoever picks up #2509 next.

[ThoughtProof]

Confirmed on our side with the same four literal strings (placeholders included):

package_digest = sha256:d735f0020908d304d5b331665544f3cd85b20df64f2d1639d4251d4bf3aa5788

JCS via canonicalize (RFC 8785). Matches your json.dumps(sort_keys=True, separators=(",", ":")) for this object — no key-strip/float drift on this fixture.

Second cross-checkable pair done. Still one-pair stop unless a Buzz maintainer wants this as a worked interop appendix for verdict_ref.

[babyblueviper1]

@ThoughtProof Confirmed — that's two independent cross-checkable pairs now, both matched byte-for-byte across two separate implementations with no shared code path:

Pair 1 — artifact_hash / action_digest (raw content hash, no envelope) — matched earlier in this thread.

Pair 2 — decision_ref-layer envelope vs package_digest-layer envelope (structurally analogous, deliberately non-interchangeable — verdict-inclusive vs verdict-exclusive):

fixture: {"claim":"<exact artifact raw string>","evidence":"<exact evidence string you choose; post bytes>","mode":"handoff","tier":"standard"}
sha256:  d735f0020908d304d5b331665544f3cd85b20df64f2d1639d4251d4bf3aa5788

Our path: json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False) (RFC 8785-equivalent for this object shape). Yours: canonicalize (RFC 8785 proper). Independent implementations, same output — that's the real interop signal, not just "we both claim RFC 8785."

Folding both pairs into the proposal as the worked interop appendix now, since I'm the one who opened #2509 — a future implementer gets a literal fixture + two independently-verified digests to check their own JCS path against, instead of trusting either of our claims. Will note in the appendix that a mismatch on this exact fixture is almost always key-stripping or float-formatting drift, not a real digest-scheme disagreement, per what we found working through it.