Skip to content
Kindgi

HITL audit bundle

@kindgi/specs/audit-bundle.schema.json, schema version 1.0.0.

A signed export bundling one or more HITL approvals + their decisions + references to the provenance DAGs those approvals concern. Produced by the Kindgi runtime's HITL audit export. Ed25519-signed with the same key material used for provenance signing. Verifiable outside the runtime by an external auditor with only the public key.

  • id (string, required): Unique bundle identifier (UUID). Stable across re-reads.
  • tenantId (string, required): Sovereignty boundary. All included approvals + decisions belong to this tenant.
  • generatedAt (string (date-time), required): ISO 8601 UTC timestamp when the bundle was materialized.
  • approvals (array of approval, required): The approval records included in this bundle. Ordering is not guaranteed; consumers must key by id.
  • decisions (array of reviewDecision, required): The decision records for approvals in this bundle. Some approvals may not yet have a decision (bundle exported mid-flight); a consumer joins by approvalId.
  • provenanceRefs (array of object, required): Back-references to the provenance DAGs the approvals concern. Only present when an approval carried a provenanceRef. Consumers fetch the DAGs from the provenance API separately — they are NOT embedded here to keep bundles small.
    • runId (string, required)
    • provenanceId (string)
  • signature (signature, required)

Definitions

Section titled “Definitions”

approval

Section titled “approval”
  • id (string, required)
  • tenantId (string, required)
  • projectId (string)
  • subjectKind (string, required): Free-form kind identifier (e.g. 'agent-turn:session-hitl-gate', 'supervisor:fix-proposal', 'pack:install'). Callers namespace their kinds.
  • subjectRef (map of any, required): Polymorphic payload describing what needs approval. Shape depends on subjectKind.
  • requiredRole (reviewerRole, required)
  • status (approvalStatus, required)
  • assignedTo (string)
  • batchKey (string)
  • title (string)
  • description (string)
  • context (map of any)
  • provenanceRef (object)
    • runId (string, required)
    • provenanceId (string)
  • waitTokenId (string)
  • createdAt (string (date-time), required)
  • updatedAt (string (date-time), required)
  • decidedAt (string (date-time))
  • expiresAt (string (date-time))

reviewDecision

Section titled “reviewDecision”
  • id (string, required)
  • tenantId (string, required)
  • approvalId (string, required)
  • reviewerId (string, required)
  • decision ("approve" | "reject" | "escalate" | "withdraw", required)
  • rationale (string)
  • evidence (map of any)
  • reviewerRoleAtDecision (reviewerRole, required): Snapshot of the reviewer's role at the moment of decision. A subsequent role rotation does not rewrite this audit record.
  • decidedAt (string (date-time), required)

reviewerRole

Section titled “reviewerRole”

Reviewer role class. Ordered by escalation authority: standard < senior < admin. requiredRole on an approval is the minimum; a higher-ranked reviewer can always decide a lower-tier approval.

Type: "standard" | "senior" | "admin"

approvalStatus

Section titled “approvalStatus”

Type: "pending" | "assigned" | "in_review" | "approved" | "rejected" | "escalated" | "expired" | "withdrawn"

signature

Section titled “signature”

Ed25519 signature over the canonical JSON projection of the bundle (all fields except this signature). Same algorithm and canonicalization as signed provenance exports.

  • algorithm ("ed25519", required)
  • keyId (string, required)
  • value (string, required)
  • signedAt (string (date-time), required)