Version 0.2 January 2026

Integration

See it in action: The Deploy Gate Demo shows HAP integration for GitHub PRs with multi-person approval and AI-assisted review.

The Integration layer describes how any application—local, cloud, mobile, embedded, or enterprise—implements the Human Agency Protocol.

It does not require using the reference SDK. Applications may:

What matters is not how you implement it. What matters is what must be enforced.

HAP integration means one thing:

Your application cannot execute irreversible actions without a valid human attestation conforming to a trusted HAP Profile.

Everything else is an implementation detail.

The Responsibility of Applications

Every HAP-compliant application must implement four structural responsibilities:

Detect Direction Gaps

Your system must detect when a human decision is missing at any stage:

These gaps are not semantic. They are structural.

You decide how you detect them:

HAP only requires that when the gap exists, execution must stop.

Enforce Stop → Ask → Confirm → Proceed

Once a direction gap is detected:

Stop

Ask

Confirm

Proceed

Applications control:

What they may not do is proceed without confirmation.

Maintain Direction Integrity

Your app must record, track, and enforce the Six Human Gates:

This structure is mandatory. Your app may extend it, but may not skip or reorder it.

Applications must derive structured execution payloads from the ratified Frame locally, and bind them to the attestation (e.g., via hash inclusion or encryption). These payloads must not contain natural language or interpretable context.

Request Attestations Before Execution

Before executing any irreversible action, the application must request an Attestation from a Service Provider.

To receive the attestation, your app must prove (structurally):

If the attestation is denied:

This guarantees executors never interact with users directly and never run without confirmed human direction.

Frame Construction (v0.2)

In v0.2, Frames are key-value maps with deterministic canonicalization. Your application must:

  1. Include all required keys defined by the Profile
  2. Order keys according to Profile specification (or lexicographically by default)
  3. Encode values correctly (percent-encode = and non-printable ASCII)
  4. Compute frame_hash as SHA-256 of the canonical frame string

Example (Deploy Gate Profile):

repo=org/service
sha=abc123def456
env=prod
profile=deploy-gate@0.2
path=deploy-prod-canary
disclosure_hash=sha256:789...

Disclosure Hash

Disclosure represents what the human actually reviewed. Your application must:

  1. Construct a disclosure object containing review context
  2. Canonicalize according to Profile rules (sorted keys, no whitespace, set fields sorted)
  3. Compute disclosure_hash as SHA-256 of canonical JSON
  4. Include disclosure_hash in the Frame

Integrating the Six Human Gates Into Your Application

HAP doesn’t tell you how to implement this. It tells you what must be true.

Applications decide:

The protocol only requires structural compliance.

Minimal example of internal state tracking:

directionState = {
  frame: { resolved: false, hash: null },
  problem: { resolved: false },
  objective: { resolved: false },
  tradeoff: { resolved: false },
  commitment: { resolved: false },
  decisionOwner: { resolved: false, did: null },
  decisionOwnerScope: { resolved: false, scope: null }
};

Example gap detector (application-defined):

if (!directionState.frame.resolved) return { gateState: "frame" };
if (!directionState.problem.resolved) return { gateState: "problem" };
if (!directionState.objective.resolved) return { gateState: "objective" };
if (!directionState.tradeoff.resolved) return { gateState: "tradeoff" };
if (!directionState.commitment.resolved) return { gateState: "commitment" };
if (!directionState.decisionOwner.resolved) return { gateState: "decisionOwner" };

return null; // all good

Applications define these rules.

HAP only enforces the outcome: No progress without resolution.

Applications Can Use Their Own Models

Applications may run:

These models are:

Local models:

Execution is only performed after Attestation issuance, and never directly by the user.

Accessing Execution Safely: The Attestation Flow

The Attestation is the cryptographic enforcement layer.

When your app wants to execute:

  1. Check Direction — all required stages resolved
  2. Construct canonical Frame per Profile
  3. Compute frame_hash and disclosure_hash
  4. Request Attestation from Service Provider
  5. Service Provider validates your structure against Profile
  6. Attestation issued (or rejected with error code)
  7. Execute with attestation via Executor Proxy
  8. Executor operates within the attestation’s scope

When direction is unresolved:

This architecture guarantees:

Handling Attestation Errors

Executor Proxies return structured errors when validation fails:

ErrorMeaningApplication Response
INVALID_SIGNATUREAttestation signature failedCheck SP key configuration
EXPIREDTTL exceededRequest new attestation
FRAME_MISMATCHHash doesn’t matchVerify frame construction
PATH_MISMATCHWrong execution pathMatch path to attestation
SCOPE_INSUFFICIENTMissing required scopesAdd required Decision Owners
MALFORMED_ATTESTATIONStructure invalidCheck attestation format

Local vs. Remote Execution

Applications control what runs locally vs. remotely:

Local execution:

Remote execution:

Executors cannot escalate, expand scope, or reinterpret direction.

Application Integration Checklist

Every HAP-compliant app must:

Required

Optional but encouraged

Developer Autonomy

HAP is not a framework. It is not an API-first product. It is a structural contract between:

Applications are free to:

As long as the application satisfies:

It is fully compliant.

Summary

Integrating HAP means your application:

Your implementation can be:

HAP defines only the structure — you invent everything else.

Multi-Participant Decision Coordination

When an application participates in a shared decision instance (e.g., team planning, joint purchase, couple’s agreement), it must:

1. Maintain Local Direction State Per Domain

Each materially affected domain (e.g., user.wellbeing, user.time) is resolved entirely locally. No semantic content leaves the device.

Also maintain decision_owner_scope per owner. This structure must be included in structural emissions if required by the Profile.

2. Publish Only Structural Domain Status

When participating in a shared decision, the app may emit:

{
  "decision_id": "uuid",
  "frame_hash": "sha256:...",
  "domain": "wellbeing",
  "resolved_gates": ["problem", "tradeoff", "commitment"],
  "resolved": true,
  "owner_scope": {
    "did": "did:key:...",
    "domain": "wellbeing",
    "env": "personal"
  }
}

→ Never include Problem text, Tradeoff description, or reasoning.

3. Consume Structural Signals from Other Participants

The app may receive similar structural signals from other certified participants. It must not:

4. Block Shared Execution Until All Required Domains Are Closed

Before enabling joint action (e.g., sending a calendar invite, transferring funds), the app must verify:

5. Treat Frame Drift as a Stop Condition

If any participant’s frame_hash differs from the declared Frame, the app must halt and signal: “Direction conflict: Frames do not align.”

6. Handle Divergence with Generative Prompts

When structural signals reveal irreconcilable directions (e.g., mismatched frame_hash or tradeoffs that imply mutually exclusive actions), the app must not simulate agreement.

Instead, it should offer a clear, non-coercive path forward:

“Your directions diverge. Would you like to initiate a new decision?”

This transforms potential conflict into explicit, ratifiable next steps—keeping agency human and collaboration honest.

Next: Service Providers →