Skip to main content
HUMΛN
HUMΛN
←Community
HumanOS
HumanOS

Building a multi-language governance wrapper: JWT preflight and Fourth Law signaling

HUMΛN Team··16 min·SDK + Platform engineers

Your Python agent got HTTP 200. Your Go agent got 409. Same call. Same low confidence. Same human who should have been asked.

That is not “SDK flavor.” That is governance divergence—and it is how multi-language platforms quietly invent two protocols.

HumanOS’s answer: one contract in @human/core, client preflight before you burn a round trip, and Fourth Law signaling that every binding must understand the same way.

Contract first

Shared types live in @human/core: HumanCallOptions, HumanCallResult, escalation and provenance shapes. No language-specific semantics—only idiomatic error surfaces (Python exceptions, Go (result, err), Rust Result).

If two SDKs disagree on what “low confidence” means, you do not have a protocol—you have documentation debt with semver. The wrapper exists so that so that a Go service and a TypeScript Companion never disagree about whether a human must review.

Preflight before HTTP

JWT handling in browsers and Node has sharp edges:

  1. Base64url — normalize _/+, pad to multiple of 4 before atob / Buffer decode. Mixed alphabets are a classic cross-runtime bug.
  2. Expiry — reject locally before burning a round trip; clock skew policy belongs in one place.
  3. Capability subset — when requiredCapabilities is present, fail closed if the delegation does not cover the call. Do not rely on the server to be the first gate.

Scroll-stopper: A client that only discovers missing scopes after the server returns is a client that taught the network your intent for free.

Fourth Law signaling (two valid worlds)

Canon’s Fourth Law: AI must know when it does not know—and escalate.

Preferred: HTTP 409 for governance conflicts when the deployment supports it—clear, cache-friendly, easy to monitor.

Previous: HTTP 200 with fourth_law_triggered: true in the body. Some stacks shipped this before clients could handle 409 everywhere.

SDK requirement: accept both until a breaking major removes the compat path. Document the deprecation timeline in release notes, not only in comments. Silent “we only handle 409 now” is how one language binding becomes a production incident.

Observability

  • Propagate X-Trace-ID (UUID v4) from client through gateway.
  • Surface provenance_ref on success responses so Workforce and audit pipelines can join without scraping logs.

Integration snippet (shape, not vendor lock-in)

const result = await humanCall({
  messages,
  requiredCapabilities: ['workforce.task.execute'],
});

if (result.fourth_law_triggered) {
  // Escalate UX: human review, not silent retry with higher temperature
  await escalateToHuman({ result });
}

Exact imports live in the packages. The shape is the protocol: detect uncertainty → escalate → provenance.

Checklist: new language binding

  • Types generated or hand-written from @human/core — no forked parallel structs.
  • JWT preflight matches test vectors (base64url edge cases).
  • Fourth Law: both 409 and 200+flag paths covered in tests.
  • Trace + provenance headers documented in README.

Go deeper

— Part of