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

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.

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.

Fourth Law signaling (two valid worlds)

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

Legacy: 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 legacy path. Document the deprecation timeline in release notes, not only in comments.

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 (pseudocode)

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 and types live in the packages—this is the shape, not a copy-paste vendor lock-in.

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.

Next: ML risk from audit embeddings. Narrative: Four lines of Python.

— Part of