@humanagencyp/hap-core 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanagencyp/hap-core",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Core types, cryptographic primitives, and verification logic for the Human Agency Protocol",
   "license": "MIT",
   "repository": {
@@ -33,6 +33,7 @@
     "release:major": "pnpm version major && git push --follow-tags"
   },
   "dependencies": {
+    "@hpke/core": "1.9.0",
     "@noble/ed25519": "^2.1.0"
   },
   "devDependencies": {

package/src/canonicalize.ts

@@ -31,6 +31,9 @@
  * conformance test pins a (payload → canonical bytes) vector that any other
  * implementation can check against.
  */
+/** A high surrogate not followed by a low one, or a low one not preceded by a high one. */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+
 export function canonicalize(value: unknown): string {
   if (value === undefined) {
     throw new Error('canonicalize: undefined is not serializable');
@@ -41,6 +44,12 @@ export function canonicalize(value: unknown): string {
 
   // Primitives: string, finite number, boolean, null — JSON.stringify is already
   // canonical (RFC 8259 string escaping, ECMAScript number formatting).
+  if (typeof value === 'string' && LONE_SURROGATE.test(value)) {
+    // RFC 8785 requires I-JSON, which forbids a lone surrogate. JSON.stringify
+    // would escape it as \udXXX and sign bytes no other serializer produces;
+    // the protocol says refuse, never sign (Signing Canonicalization, rule 5).
+    throw new Error('canonicalize: string contains a lone surrogate and cannot be signed');
+  }
   if (value === null || typeof value !== 'object') {
     return JSON.stringify(value);
   }

package/src/commitment-modes.ts

@@ -1,21 +1,26 @@
 /**
  * Which commitment modes a profile allows its mandates to be signed with
- * (`AgentProfile.commitment_modes`). One source for the Authority Server's
- * refusal and the mandate screen's choice, so the two cannot disagree.
+ * (`AgentProfile.commitment_modes`; protocol.md → *Commitment Modes*, rule
+ * 8). One source for the Authority Server's refusal and the mandate screen's
+ * choice, so the two cannot disagree.
  */
-import type { AgentProfile, SignableCommitmentMode } from './types';
+import type { AgentProfile, CommitmentMode, SignableCommitmentMode } from './types';
 
 /** Every mode a signer can choose, in the order a mandate screen shows them. */
 export const SIGNABLE_COMMITMENT_MODES: readonly SignableCommitmentMode[] = ['review', 'automatic'];
 
+/** Every mode a signed mandate can carry. */
+export const COMMITMENT_MODES: readonly CommitmentMode[] = ['automatic', 'review', 'review_above_cap'];
+
 const isSignable = (v: unknown): v is SignableCommitmentMode =>
   typeof v === 'string' && (SIGNABLE_COMMITMENT_MODES as readonly string[]).includes(v);
 
 /**
- * The modes a mandate under this profile may carry, in display order.
- * No declaration → all of them. A declaration is read fail-closed: entries
- * that are not a signable mode are dropped, so a malformed list can only
- * narrow — `[]`, `"review"` (not a list) or `["reveiw"]` allow nothing.
+ * The signable modes a mandate under this profile may carry, in display
+ * order. No declaration → all of them. A declaration is read fail-closed:
+ * entries that are not a signable mode are dropped (`review_above_cap` is
+ * ignored by rule 8 — it follows from `automatic`), so a malformed list can
+ * only narrow — `[]`, `"review"` (not a list) or `["reveiw"]` allow nothing.
  */
 export function allowedCommitmentModes(profile: AgentProfile): readonly SignableCommitmentMode[] {
   const declared = (profile as { commitment_modes?: unknown }).commitment_modes;
@@ -24,7 +29,14 @@ export function allowedCommitmentModes(profile: AgentProfile): readonly Signable
   return SIGNABLE_COMMITMENT_MODES.filter((m) => declared.includes(m));
 }
 
-/** Whether a mandate under this profile may be signed with `mode`. */
+/**
+ * Whether a mandate under this profile may be SIGNED with `mode` (rule 8):
+ * `automatic` and `review` where listed; `review_above_cap` if and only if
+ * `automatic` is admitted. The Authority Server refuses any other with
+ * `COMMITMENT_MODE_NOT_ALLOWED`.
+ */
 export function isCommitmentModeAllowed(profile: AgentProfile, mode: string): boolean {
-  return isSignable(mode) && allowedCommitmentModes(profile).includes(mode);
+  const allowed = allowedCommitmentModes(profile);
+  if (mode === 'review_above_cap') return allowed.includes('automatic');
+  return isSignable(mode) && allowed.includes(mode);
 }

package/src/content-binding.ts

@@ -31,7 +31,7 @@
 
 import { createHash } from 'crypto';
 import { canonicalize } from './canonicalize';
-import type { ContentBinding } from './types';
+import type { ContentBinding, ContentFieldKind } from './types';
 
 /**
  * Canonicalize free text per the v0.5 'text' rule. Idempotent.
@@ -249,3 +249,28 @@ export function computeFieldsContentHash(
 ): string {
   return computeContentHash(binding, selectBoundFields(binding, args));
 }
+
+// ─── Field kinds (display / verification hint) ───────────────────────────────
+
+const FIELD_KINDS = new Set<ContentFieldKind>(['text', 'list', 'files']);
+
+/**
+ * Why a binding's `field_kinds` is malformed, or null when it is fine (or
+ * absent). For profile validation — a malformed hint is a profile error, not
+ * a call-time refusal, because it never changes what is hashed.
+ */
+export function invalidFieldKindsReason(binding: ContentBinding): string | null {
+  const kinds = binding.field_kinds;
+  if (kinds === undefined) return null;
+  if (!kinds || typeof kinds !== 'object' || Array.isArray(kinds)) return 'field_kinds must be an object';
+  for (const [field, kind] of Object.entries(kinds)) {
+    if (!(binding.fields ?? []).includes(field)) return `field_kinds names "${field}", which is not in fields`;
+    if (!FIELD_KINDS.has(kind)) return `field_kinds.${field} must be one of text, list, files`;
+  }
+  return null;
+}
+
+/** The bound fields declared as `files` — sealed document fingerprints. */
+export function filesFields(binding: ContentBinding): string[] {
+  return Object.entries(binding.field_kinds ?? {}).filter(([, k]) => k === 'files').map(([f]) => f);
+}

package/src/errors.ts

@@ -1,16 +1,12 @@
 /**
- * Canonical v0.7 error codes — protocol.md → *Error Codes*.
+ * Canonical v0.8 error codes — protocol.md → *Error Codes*.
  *
  * "Error codes are canonical across the protocol. Implementations MUST emit
  * exactly these codes and MUST NOT alias them under different names." This
  * module is the single list both the Gatekeeper (local checks) and any AS
  * client built on this library read from, so the two cannot drift.
  *
- * v0.7 renamed every code that carried a retired word (attestation → mandate,
- * context → scope, receipt → ticket) — see protocol.md → *Migration from
- * v0.6* → "Error-code renames" for the old→new map. There is no alias: a v0.6
- * code name is simply gone from this list, by design (no backward
- * compatibility — CLAUDE.md "Decided by the owner").
+ * v0.8 adds codes and retires none; every v0.7 code keeps its name.
  */
 
 /** Codes an Authority Server (or a local Gatekeeper check) emits refusing a mandate request. */
@@ -30,11 +26,14 @@ export const MANDATE_ERROR_CODES = [
   'BOUNDS_INVALID_VALUE',
   'SCOPE_INVALID_VALUE',
   'ABOVE_CAP_CONFIG_INVALID',
+  'COMMITMENT_MODE_NOT_ALLOWED', // v0.8
+  'GROUP_CAP_EXCEEDED', // v0.8
   'OWNER_SIGNATURE_REQUIRED',
   'OWNER_SIGNATURE_INVALID',
 ] as const;
 
-/** Codes an Authority Server emits refusing a ticket request. */
+/** Codes an Authority Server emits refusing a ticket request, plus the
+ * Gatekeeper-local and verifier codes of the same table. */
 export const TICKET_ERROR_CODES = [
   'MANDATE_NOT_FOUND',
   'MANDATE_EXPIRED',
@@ -45,6 +44,8 @@ export const TICKET_ERROR_CODES = [
   'PROFILE_NOT_FOUND',
   'INVALID_ACTION_TYPE',
   'APPROVAL_REQUIRED',
+  'APPROVAL_IMPOSSIBLE', // v0.8
+  'PROPOSAL_CONTENT_MISMATCH', // v0.8
   'PROPOSAL_REQUIRED',
   'PROPOSAL_NOT_FOUND',
   'PROPOSAL_NOT_APPROVED',
@@ -53,15 +54,30 @@ export const TICKET_ERROR_CODES = [
   'PROPOSAL_MISMATCH',
   'PROPOSAL_MANDATE_MISMATCH',
   'PROPOSAL_ALREADY_EXECUTED',
+  'PROPOSAL_WITHDRAWN', // v0.8
   'MALFORMED_TICKET_REQUEST',
+  'CONTENT_BINDING_INCOMPLETE', // v0.8, Gatekeeper · local
   'IDEMPOTENCY_KEY_REQUIRED',
   'IDEMPOTENCY_MISMATCH',
   'APPROVAL_SIGNATURE_REQUIRED',
   'APPROVAL_SIGNATURE_INVALID',
+  'TICKET_REQUEST_MISMATCH', // v0.8, Gatekeeper · local
+  'POLICY_UNMET', // v0.8, Verifier
+] as const;
+
+/** Codes an Authority Server emits refusing a proposal submission or a decision (v0.8). */
+export const PROPOSAL_ERROR_CODES = [
+  'PROPOSAL_NOT_ENCRYPTED',
+  'DECIDER_INVALID',
+  'PROPOSAL_ALREADY_DECIDED',
+  'PROPOSAL_APPROVERS_INVALID',
 ] as const;
 
 /** The full canonical surface — every code a conformant implementation may emit. */
-export type HapErrorCode = (typeof MANDATE_ERROR_CODES)[number] | (typeof TICKET_ERROR_CODES)[number];
+export type HapErrorCode =
+  | (typeof MANDATE_ERROR_CODES)[number]
+  | (typeof TICKET_ERROR_CODES)[number]
+  | (typeof PROPOSAL_ERROR_CODES)[number];
 
 /**
  * A refusal carrying one of the canonical codes above. Thrown by local

package/src/gatekeeper.ts

@@ -1,5 +1,6 @@
 /**
- * Gatekeeper — local (Phase 1) verification for bounded execution (v0.7).
+ * Gatekeeper — local (Phase 1) verification for bounded execution (v0.8;
+ * v0.7 mandates verified under their own rules).
  *
  * protocol.md → *Validation Steps* (Phase 1, never reaches the wire):
  *   1. Resolve profile from bounds.profile
@@ -24,12 +25,13 @@
  * frame-based path is retired entirely (CLAUDE.md "Decided by the owner").
  */
 
-import { decodeMandateBlob, verifyMandateSignature, checkMandateExpiry, validateMandateOwners } from './mandate';
+import { decodeMandateBlob, verifyMandateSignature, checkMandateExpiry, validateMandateOwners, validateAboveCapFields } from './mandate';
+import { checkExecutionValues, missingSumFields } from './issuance';
 import { canonicalBounds, canonicalScope, computeBoundsHash, computeScopeHash, CanonicalValueError } from './frame';
 import { computeProfileHash } from './profile';
 import { getProfile } from './profiles';
 import { HapError, type HapErrorCode } from './errors';
-import { PROTOCOL_VERSION } from './versions';
+import { isSupportedVersion, SUPPORTED_VERSIONS } from './versions';
 import type {
   GatekeeperRequest,
   GatekeeperResult,
@@ -112,8 +114,9 @@ export async function verify(request: GatekeeperRequest, opts: VerifyOptions = {
 
   // 3. Verify every mandate blob.
   const errors: GatekeeperError[] = [];
+  const verifiedPayloads: MandatePayload[] = [];
   for (const blob of request.mandates) {
-    const mandateErrors = await verifyOneMandate(blob, {
+    const { errors: mandateErrors, payload } = await verifyOneMandate(blob, {
       expectedBoundsHash,
       expectedScopeHash,
       expectedProfileHash,
@@ -121,6 +124,7 @@ export async function verify(request: GatekeeperRequest, opts: VerifyOptions = {
       now,
     });
     errors.push(...mandateErrors);
+    if (payload) verifiedPayloads.push(payload);
   }
   if (errors.length > 0) {
     return { approved: false, errors };
@@ -144,7 +148,37 @@ export async function verify(request: GatekeeperRequest, opts: VerifyOptions = {
     }
   }
 
-  // 5. per_transaction bounds and enum capability flags, locally.
+  // 5. Every value a bound reads is a finite, non-negative number
+  // (Validation Steps, step 8; v0.8) — before any bound is compared.
+  try {
+    checkExecutionValues(request.execution, profile);
+  } catch (err) {
+    return { approved: false, errors: [{ code: codeFromThrown(err), message: (err as Error).message }] };
+  }
+  // A cumulative_sum bound that governs this action type and reads an absent
+  // field is refused locally too — unless an above-cap approval is in play:
+  // where a mandate caps that field, an absent value is "above the cap" and
+  // the AS routes it to approval (Ticket Issuance, stage 7).
+  if (actionType !== undefined) {
+    const capped = new Set<string>();
+    for (const p of verifiedPayloads) {
+      for (const name of Object.keys(p.above_cap_caps ?? {})) {
+        const bt = profile.boundsSchema?.fields[name]?.boundType;
+        if (bt && bt.kind === 'per_transaction') capped.add(bt.of);
+      }
+    }
+    const missing = missingSumFields(request.execution, profile, actionType).filter((m) => !capped.has(m.field));
+    if (missing.length > 0) {
+      return {
+        approved: false,
+        errors: missing.map(({ bound, field }) => ({
+          code: 'BOUND_EXCEEDED' as const,
+          field,
+          message: `Bound "${bound}" governs "${actionType}" and reads "${field}", but this call exposes no ${field}. Refusing: an action without an amount would consume nothing of the limit (v0.8: a missing amount fails safe).`,
+        })),
+      };
+    }
+  }
   const boundsErrors = checkBounds(request, profile, actionType);
   if (boundsErrors.length > 0) {
     return { approved: false, errors: boundsErrors };
@@ -197,7 +231,16 @@ function codeFromThrown(err: unknown): HapErrorCode {
   return 'MALFORMED_MANDATE';
 }
 
-async function verifyOneMandate(blob: string, opts: MandateCheckOptions): Promise<GatekeeperError[]> {
+async function verifyOneMandate(
+  blob: string,
+  opts: MandateCheckOptions,
+): Promise<{ errors: GatekeeperError[]; payload?: MandatePayload }> {
+  const errors = await verifyOneMandateErrors(blob, opts);
+  if (errors.length > 0) return { errors };
+  return { errors, payload: decodeMandateBlob(blob).payload };
+}
+
+async function verifyOneMandateErrors(blob: string, opts: MandateCheckOptions): Promise<GatekeeperError[]> {
   let mandate: Mandate;
   try {
     mandate = decodeMandateBlob(blob);
@@ -205,10 +248,10 @@ async function verifyOneMandate(blob: string, opts: MandateCheckOptions): Promis
     return [{ code: 'MALFORMED_MANDATE', message: (err as Error).message }];
   }
 
-  if (mandate.payload.version !== PROTOCOL_VERSION) {
+  if (!isSupportedVersion(mandate.payload.version)) {
     return [{
       code: 'VERSION_UNSUPPORTED',
-      message: `mandate version ${JSON.stringify(mandate.payload.version)} is not verifiable by this Gatekeeper (verifies ${PROTOCOL_VERSION} only)`,
+      message: `mandate version ${JSON.stringify(mandate.payload.version)} is not verifiable by this Gatekeeper (verifies [${SUPPORTED_VERSIONS.join(', ')}])`,
     }];
   }
 
@@ -226,6 +269,7 @@ async function verifyOneMandate(blob: string, opts: MandateCheckOptions): Promis
 
   try {
     validateMandateOwners(mandate.payload);
+    validateAboveCapFields(mandate.payload);
   } catch (err) {
     return [{ code: codeFromThrown(err), message: (err as Error).message }];
   }

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * HAP Core — v0.7 ("mandate" / "ticket" / "scope" / "Mandate Owner")
+ * HAP Core — v0.8 (issues 0.8; verifies 0.8 and 0.7, each under its own rules)
  *
  * Shared protocol logic for agent-oriented bounded execution.
  */
@@ -18,6 +18,10 @@ export * from './profile';
 export * from './mandate';
 export * from './owner-signature';
 export * from './ticket';
+export * from './ticket-projection';
+export * from './verifier-policy';
+export * from './proposal-content';
+export * from './issuance';
 export * from './gatekeeper';
 export * from './profiles';
 export * from './did-key';

package/src/issuance.ts

@@ -0,0 +1,250 @@
+/**
+ * Pure checks both enforcement points apply around issuance and execution
+ * (v0.8). An Authority Server composes them into its stage order
+ * (protocol.md → *Mandate Issuance & Validation*, *Ticket Issuance*); a
+ * Gatekeeper applies the execution-side ones locally (*Validation Steps*).
+ * They live here so the two cannot disagree about what a value means.
+ */
+
+import { createHash } from 'crypto';
+import { canonicalize } from './canonicalize';
+import { HapError } from './errors';
+import { isKeyBearingDid } from './did-key';
+import type { AgentProfile, AgentBoundsParams, MandatePayload, ProfileBoundsField } from './types';
+
+/**
+ * `execution_context_hash` — sha256 over the JCS of the profile's
+ * `executionContextSchema`, or of `{}` when the profile has none (protocol.md
+ * → *Execution Context Schema*, stated in v0.8).
+ */
+export function computeExecutionContextHash(profile: Pick<AgentProfile, 'executionContextSchema'>): string {
+  const schema = profile.executionContextSchema ?? {};
+  return `sha256:${createHash('sha256').update(canonicalize(schema), 'utf8').digest('hex')}`;
+}
+
+/** The execution-context fields some bound of the profile reads
+ * (`boundType.of` of every `per_transaction` and `cumulative_sum` bound). */
+export function boundReadFields(profile: AgentProfile): Set<string> {
+  const fields = new Set<string>();
+  for (const def of Object.values(profile.boundsSchema?.fields ?? {})) {
+    const bt = def.boundType;
+    if (bt && (bt.kind === 'per_transaction' || bt.kind === 'cumulative_sum')) fields.add(bt.of);
+  }
+  return fields;
+}
+
+/**
+ * Build the wire execution context (*Validation Steps*, step 11; *Ticket
+ * Request Schema*, rules 7–8): only what a bound reads travels. `action_type`
+ * travels as the request's own `actionType`, scope values never travel,
+ * `_`-prefixed keys are advisory metadata. A `null` value is no value.
+ */
+export function wireExecutionContext(
+  execution: Record<string, unknown>,
+  profile: AgentProfile,
+): Record<string, unknown> {
+  const allowed = boundReadFields(profile);
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(execution)) {
+    if (!allowed.has(k) || k.startsWith('_') || v === undefined || v === null) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Every value present for a field some bound reads MUST be a finite,
+ * non-negative number (*Ticket Issuance*, stage 7; *Validation Steps*, step
+ * 8). `null` counts as absent. A `_`-prefixed key is refused.
+ * @throws HapError `MALFORMED_TICKET_REQUEST`
+ */
+export function checkExecutionValues(execution: Record<string, unknown>, profile: AgentProfile): void {
+  for (const k of Object.keys(execution)) {
+    if (k.startsWith('_')) {
+      throw new HapError('MALFORMED_TICKET_REQUEST', `executionContext key "${k}" is reserved and MUST NOT travel`);
+    }
+  }
+  for (const field of boundReadFields(profile)) {
+    const v = execution[field];
+    if (v === undefined || v === null) continue;
+    if (typeof v !== 'number' || !Number.isFinite(v) || v < 0) {
+      throw new HapError(
+        'MALFORMED_TICKET_REQUEST',
+        `executionContext.${field} MUST be a finite, non-negative number, got ${JSON.stringify(v)}`,
+      );
+    }
+  }
+}
+
+/** Whether a cumulative bound governs this action type: its `appliesTo`
+ * names it, or it has none (Bounds Schema rule 7). */
+export function boundGoverns(def: ProfileBoundsField, actionType: string): boolean {
+  return !def.appliesTo || def.appliesTo.includes(actionType);
+}
+
+/**
+ * The `cumulative_sum` bounds that govern this action type and whose field is
+ * absent from the execution context (*Ticket Issuance*, stage 7): each is a
+ * `BOUND_EXCEEDED`, unless a committed above-cap approval covers the action.
+ */
+export function missingSumFields(
+  execution: Record<string, unknown>,
+  profile: AgentProfile,
+  actionType: string,
+): Array<{ bound: string; field: string }> {
+  const missing: Array<{ bound: string; field: string }> = [];
+  for (const [name, def] of Object.entries(profile.boundsSchema?.fields ?? {})) {
+    const bt = def.boundType;
+    if (!bt || bt.kind !== 'cumulative_sum' || !boundGoverns(def, actionType)) continue;
+    const v = execution[bt.of];
+    if (v === undefined || v === null) missing.push({ bound: name, field: bt.of });
+  }
+  return missing;
+}
+
+/**
+ * Bounds values against the profile at issuance (*Mandate Issuance*, stage
+ * 4): a number where the field is numeric (`"100"` is refused), no higher
+ * than a declared `maximum`, and an `enum` value in its `values`.
+ * @throws HapError `BOUNDS_INVALID_VALUE`
+ */
+export function checkBoundsValues(bounds: AgentBoundsParams, profile: AgentProfile): void {
+  for (const [name, def] of Object.entries(profile.boundsSchema?.fields ?? {})) {
+    if (name === 'profile') continue;
+    const v = bounds[name];
+    if (v === undefined || v === null) continue;
+    if (def.type === 'number' || def.maximum !== undefined) {
+      if (typeof v !== 'number' || !Number.isFinite(v)) {
+        throw new HapError('BOUNDS_INVALID_VALUE', `bound "${name}" MUST be a number, got ${JSON.stringify(v)}`);
+      }
+      if (def.maximum !== undefined && v > def.maximum) {
+        throw new HapError('BOUNDS_INVALID_VALUE', `bound "${name}" = ${v} exceeds the profile's maximum ${def.maximum}`);
+      }
+    }
+    const bt = def.boundType;
+    if (bt?.kind === 'enum' && !bt.values.includes(String(v))) {
+      throw new HapError('BOUNDS_INVALID_VALUE', `bound "${name}" = ${JSON.stringify(v)} is not in [${bt.values.join(', ')}]`);
+    }
+  }
+}
+
+/** A group's caps for one profile, as the AS holds them. */
+export interface GroupCaps {
+  /** Caps a proposal may lift (`approval` kind) — numeric per_transaction fields only. */
+  approval?: Record<string, number>;
+  /** Hard caps: refused at signing, never routed. Numeric or enum values. */
+  hard?: Record<string, number | string>;
+}
+
+/**
+ * Whether a bound value exceeds a cap. For an `enum` bound the cap is one of
+ * its values, and a value that comes EARLIER in the profile's `values` order
+ * (more permissive) exceeds it (Bounds Schema rule 10; *Group ceilings*).
+ */
+export function exceedsCap(value: string | number, cap: string | number, def: ProfileBoundsField): boolean {
+  const bt = def.boundType;
+  if (bt?.kind === 'enum') {
+    const order = bt.values;
+    const vi = order.indexOf(String(value));
+    const ci = order.indexOf(String(cap));
+    if (vi < 0 || ci < 0) return true; // an unknown value or cap fails closed
+    return vi < ci;
+  }
+  return typeof value !== 'number' || typeof cap !== 'number' || value > cap;
+}
+
+/**
+ * Hard group ceilings at signing (*Group ceilings*; *Group roles*, rule 5):
+ * a cap on a bound the Gatekeeper alone enforces (`enforcedBy: "gatekeeper"`)
+ * or on an `enum` bound is always hard, as is every cap in `hard`; a bound
+ * above one, or an optional bound omitted where a cap exists, is refused.
+ * Caps in `approval` on a cumulative bound are hard too (Commitment Modes,
+ * rule 7). An omitted REQUIRED bound is `MALFORMED_MANDATE`, checked
+ * elsewhere.
+ * @throws HapError `GROUP_CAP_EXCEEDED`
+ */
+export function checkGroupCeilings(bounds: AgentBoundsParams, profile: AgentProfile, caps: GroupCaps): void {
+  const fields = profile.boundsSchema?.fields ?? {};
+  const hard: Record<string, number | string> = { ...(caps.hard ?? {}) };
+  for (const [name, cap] of Object.entries(caps.approval ?? {})) {
+    const def = fields[name];
+    const bt = def?.boundType;
+    if (!def || !bt) continue;
+    if (bt.kind !== 'per_transaction' || def.enforcedBy === 'gatekeeper') hard[name] = cap;
+  }
+  for (const [name, def] of Object.entries(fields)) {
+    if (name === 'profile') continue;
+    const cap = hard[name];
+    if (cap === undefined) continue;
+    const v = bounds[name];
+    if (v === undefined || v === null) {
+      if (!def.required) {
+        throw new HapError('GROUP_CAP_EXCEEDED', `bound "${name}" is omitted under a group ceiling of ${JSON.stringify(cap)} — an omitted bound is unlimited`);
+      }
+      continue;
+    }
+    if (exceedsCap(v, cap, def)) {
+      throw new HapError('GROUP_CAP_EXCEEDED', `bound "${name}" = ${JSON.stringify(v)} exceeds the group's hard cap ${JSON.stringify(cap)}`);
+    }
+  }
+}
+
+/**
+ * The above-cap configuration a mandate request or a group supplies
+ * (*Commitment Modes*, rule 7; *Group roles*, rules 2 and 4; Mandate rule
+ * 10): caps name numeric `per_transaction` bounds of the profile and never
+ * `profile`; approvers are key-bearing DIDs; outside a group the count is an
+ * integer ≥ 1 and no greater than the approvers other than the owner.
+ * @throws HapError `ABOVE_CAP_CONFIG_INVALID`
+ */
+export function validateAboveCapConfig(
+  config: { caps?: Record<string, number>; approvers?: readonly string[]; approvals?: number },
+  profile: AgentProfile,
+  opts: { ownerDid: string; inGroup: boolean },
+): void {
+  const fields = profile.boundsSchema?.fields ?? {};
+  for (const name of Object.keys(config.caps ?? {})) {
+    if (name === 'profile') throw new HapError('ABOVE_CAP_CONFIG_INVALID', 'above_cap_caps MUST NOT name profile');
+    const def = fields[name];
+    if (!def || def.boundType?.kind !== 'per_transaction' || def.type !== 'number') {
+      throw new HapError('ABOVE_CAP_CONFIG_INVALID', `above_cap_caps names "${name}", which is not a numeric per_transaction bound of ${profile.id}`);
+    }
+  }
+  for (const did of config.approvers ?? []) {
+    if (!isKeyBearingDid(did)) {
+      throw new HapError('ABOVE_CAP_CONFIG_INVALID', `above-cap approver ${did} is not a key-bearing DID`);
+    }
+  }
+  if (config.approvers !== undefined && !opts.inGroup) {
+    const others = config.approvers.filter((d) => d !== opts.ownerDid).length;
+    const n = config.approvals;
+    if (n === undefined || !Number.isInteger(n) || n < 1 || n > others) {
+      throw new HapError(
+        'ABOVE_CAP_CONFIG_INVALID',
+        `above_cap_approvals MUST be an integer between 1 and the ${others} approver(s) other than the owner, got ${JSON.stringify(n)}`,
+      );
+    }
+  }
+}
+
+/**
+ * Whether a request exceeds an approval-kind cap of the mandate, or — v0.8 —
+ * the field the cap reads is absent (an action of unknown amount is above
+ * the cap). Returns the offending caps.
+ */
+export function capsExceeded(
+  execution: Record<string, unknown>,
+  mandate: Pick<MandatePayload, 'above_cap_caps'>,
+  profile: AgentProfile,
+): Array<{ bound: string; field: string; cap: number; value: unknown }> {
+  const out: Array<{ bound: string; field: string; cap: number; value: unknown }> = [];
+  for (const [name, cap] of Object.entries(mandate.above_cap_caps ?? {})) {
+    const bt = profile.boundsSchema?.fields[name]?.boundType;
+    if (!bt || bt.kind !== 'per_transaction') continue;
+    const v = execution[bt.of];
+    if (v === undefined || v === null || typeof v !== 'number' || v > cap) {
+      out.push({ bound: name, field: bt.of, cap, value: v });
+    }
+  }
+  return out;
+}