@humanagencyp/hap-core 0.10.1 → 0.11.1

package/dist/index.d.mts

@@ -205,10 +205,29 @@ type BoundType =
  * Per-transaction cap. The execution context field named in `of` must
  * satisfy `execution[of] <= bound` for the current call. No cumulative
  * tracking. Used by: amount_max, recipient_max, booking_duration_max, etc.
+ *
+ * `requiredFor` (v0.8+) closes the converse: without it, a call that does
+ * not carry `of` at all is simply skipped — a 5,000 cap refuses 6,000 but
+ * permits a call that declares no value whatsoever, which is indistinguishable
+ * from an unenforced bound. The same hole, and the same fix, as
+ * `FieldConstraint.requiredFor` on a scope constraint (below): values drawn
+ * from the profile's `boundsSchema.actionTypes` registry. For a listed
+ * `action_type`, an execution whose context lacks `of` — or whose value is
+ * not a finite number — MUST be refused rather than skipped. For an
+ * unlisted (or when `requiredFor` is absent) action type, today's
+ * skip-on-absence behaviour is unchanged. Meaningful only on
+ * `per_transaction`; the other `BoundType` kinds have no per-call "value
+ * exposed or not" question — `cumulative_sum`/`cumulative_count` always read
+ * from the execution log regardless of what this call declares, and `enum`
+ * is a capability flag, not a runtime value — so the field does not exist
+ * on those variants and a profile that puts it there has it silently
+ * ignored by every enforcement point (TypeScript also refuses it when the
+ * profile is authored against this type rather than raw JSON).
  */
 {
     kind: 'per_transaction';
     of: string;
+    requiredFor?: string[];
 }
 /**
  * Cumulative sum within a time window. The SP maintains a running sum
@@ -448,6 +467,11 @@ interface ExecutionPath {
  *
  * Supports both v0.3 (frameSchema) and v0.4 (boundsSchema + contextSchema).
  */
+/**
+ * A commitment mode a person can choose when signing a mandate. (`review_above_cap`
+ * is not chosen by the signer — it follows from team caps.)
+ */
+type SignableCommitmentMode = 'automatic' | 'review';
 interface AgentProfile {
     id: string;
     name?: string;
@@ -489,6 +513,18 @@ interface AgentProfile {
      * a forwarded message has usually lost the footer that carried it.
      */
     receipt_lookup?: boolean;
+    /**
+     * The commitment modes a mandate under this profile may be signed with.
+     * Absent → every mode (`automatic`, `review`), as before this field existed.
+     *
+     * Lets a profile be review-only: every action it governs then needs a
+     * person's approval, whatever the signer would have picked. The Authority
+     * Server refuses to sign a mandate whose `commitment_mode` is not listed;
+     * a mandate screen offers only the listed modes. Fail-closed: a declared
+     * list with no valid entry allows nothing — a malformed declaration never
+     * widens what a profile allows. See {@link allowedCommitmentModes}.
+     */
+    commitment_modes?: readonly SignableCommitmentMode[];
     /**
      * v0.3 frame schema (deprecated, kept for backward compat).
      * Used when boundsSchema is not present.
@@ -503,6 +539,16 @@ interface AgentProfile {
     boundsSchema?: {
         keyOrder: string[];
         fields: Record<string, ProfileBoundsField>;
+        /**
+         * v0.5+ registry of the action types this profile recognizes (e.g.
+         * `["send", "delete", "setup"]`). Every `execution.action_type` the
+         * Authority Server and gateway accept for this profile MUST be a member
+         * when the registry is declared (protocol.md → Bounds Schema, rule 2);
+         * it is also what a `per_transaction` bound's `requiredFor` draws from.
+         * Absent on profiles published before the registry existed — membership
+         * is then uncheckable, not a violation.
+         */
+        actionTypes?: readonly string[];
     };
     /**
      * v0.4 context schema — defines the execution context parameters (e.g., currency, action_type).
@@ -983,6 +1029,25 @@ declare function validateContextParams(params: AgentContextParams, profile: Agen
     valid: boolean;
     errors: string[];
 };
+/**
+ * Authoring-time check for `per_transaction` bound `requiredFor` (v0.8+):
+ * entries must name a real `action_type` from the profile's declared
+ * `boundsSchema.actionTypes` registry, and the field is only meaningful on
+ * `per_transaction` bounds (see `BoundType`'s doc comment for why the other
+ * kinds don't carry it).
+ *
+ * This is NOT wired into `registerProfile` or any enforcement path — nothing
+ * in hap-core validates profile JSON at load time today (the pre-existing
+ * `requiredFor` on a context/scope constraint has the same gap), so adding
+ * an automatic refusal here would be new behaviour beyond this change's
+ * scope. Call it explicitly from an authoring tool, a hap-profiles CI check,
+ * or a test, to catch a `requiredFor` entry that can never match (misspelled
+ * action type) or is attached to a bound kind that silently ignores it.
+ *
+ * Returns an empty array when the profile has no boundsSchema or nothing to
+ * check — never throws.
+ */
+declare function validateBoundsRequiredFor(profile: AgentProfile): string[];
 /**
  * Thrown when a value cannot be canonicalized at all — currently only for raw
  * LF/CR inside a value. Carries the protocol error code so callers can map it
@@ -1033,6 +1098,31 @@ declare function computeBoundsHash(params: AgentBoundsParams, profile: AgentProf
  */
 declare function computeContextHash(params: AgentContextParams, profile: AgentProfile): string;
 
+/**
+ * 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.
+ */
+
+/** Every mode a signer can choose, in the order a mandate screen shows them. */
+declare const SIGNABLE_COMMITMENT_MODES: readonly SignableCommitmentMode[];
+/**
+ * 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.
+ */
+declare function allowedCommitmentModes(profile: AgentProfile): readonly SignableCommitmentMode[];
+/** Whether a mandate under this profile may be signed with `mode`. */
+declare function isCommitmentModeAllowed(profile: AgentProfile, mode: string): boolean;
+/**
+ * Authoring check for a profile's `commitment_modes` declaration — for
+ * hap-profiles CI, an authoring tool or a test. Like `validateBoundsRequiredFor`
+ * it is not wired into profile loading; enforcement reads the declaration
+ * fail-closed through `allowedCommitmentModes`. Empty array = nothing to fix.
+ */
+declare function validateCommitmentModes(profile: AgentProfile): string[];
+
 /**
  * Attestation Encoding, Decoding, and Verification
  *
@@ -1353,4 +1443,4 @@ interface ReceiptPayload {
  */
 declare function verifyReceiptSignature(receipt: ReceiptPayload, publicKeyHex: string): Promise<void>;
 
-export { type AgentBoundsParams, type AgentContextParams, type AgentFrameParams, type AgentProfile, type ApprovalObject, type Attestation, type AttestationHeader, type AttestationPayload, type BoundType, CanonicalValueError, type ContentBinding, ContentBindingError, type ContentBindingErrorCode, type CumulativeFieldDef, type CumulativeWindow, type DeclaredFieldDef, type ExecutionContextFieldDef, type ExecutionLogEntry, type ExecutionLogQuery, type ExecutionMappingTransform, type ExecutionMappingValue, type ExecutionPath, type FieldConstraint, type FieldUnit, type GateQuestion, type GatekeeperError, type GatekeeperRequest, type GatekeeperResult, type MandateBinding, MandateError, type MandateProjection, type OwnerMandate, type ProfileBoundsField, type ProfileContextField, type ProfileFrameField, type ProfileToolGating, type ProfileToolGatingEntry, type ReceiptPayload, type ResolvedDomain, type SigningSurface, type Subject, type SubjectValidation, approvalSigningBytes, attestationId, bindingAppliesTo, boundActionTypes, buildMandateProjection, canonicalBounds, canonicalContext, canonicalFrame, canonicalize, canonicalizeText, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContentHash, computeContextHash, computeFieldsContentHash, computeFrameHash, computeIntentDisclosureHash, computeIntentHash, contentCanonicalBytes, decodeAttestationBlob, decodeDidKey, deriveIdentityLine, encodeAttestationBlob, encodeDidKey, frameHash, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, isFieldBinding, isKeyBearingDid, isV4Attestation, listProfiles, mandateSigningBytes, registerProfile, selectBoundFields, signApproval, signMandateProjection, validateBoundsParams, validateContextParams, validateFrameParams, validateSubject, verify, verifyApproval, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash, verifyOwnerMandate, verifyOwnerMandates, verifyReceiptSignature };
+export { type AgentBoundsParams, type AgentContextParams, type AgentFrameParams, type AgentProfile, type ApprovalObject, type Attestation, type AttestationHeader, type AttestationPayload, type BoundType, CanonicalValueError, type ContentBinding, ContentBindingError, type ContentBindingErrorCode, type CumulativeFieldDef, type CumulativeWindow, type DeclaredFieldDef, type ExecutionContextFieldDef, type ExecutionLogEntry, type ExecutionLogQuery, type ExecutionMappingTransform, type ExecutionMappingValue, type ExecutionPath, type FieldConstraint, type FieldUnit, type GateQuestion, type GatekeeperError, type GatekeeperRequest, type GatekeeperResult, type MandateBinding, MandateError, type MandateProjection, type OwnerMandate, type ProfileBoundsField, type ProfileContextField, type ProfileFrameField, type ProfileToolGating, type ProfileToolGatingEntry, type ReceiptPayload, type ResolvedDomain, SIGNABLE_COMMITMENT_MODES, type SignableCommitmentMode, type SigningSurface, type Subject, type SubjectValidation, allowedCommitmentModes, approvalSigningBytes, attestationId, bindingAppliesTo, boundActionTypes, buildMandateProjection, canonicalBounds, canonicalContext, canonicalFrame, canonicalize, canonicalizeText, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContentHash, computeContextHash, computeFieldsContentHash, computeFrameHash, computeIntentDisclosureHash, computeIntentHash, contentCanonicalBytes, decodeAttestationBlob, decodeDidKey, deriveIdentityLine, encodeAttestationBlob, encodeDidKey, frameHash, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, isCommitmentModeAllowed, isFieldBinding, isKeyBearingDid, isV4Attestation, listProfiles, mandateSigningBytes, registerProfile, selectBoundFields, signApproval, signMandateProjection, validateBoundsParams, validateBoundsRequiredFor, validateCommitmentModes, validateContextParams, validateFrameParams, validateSubject, verify, verifyApproval, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash, verifyOwnerMandate, verifyOwnerMandates, verifyReceiptSignature };

package/dist/index.d.ts

@@ -205,10 +205,29 @@ type BoundType =
  * Per-transaction cap. The execution context field named in `of` must
  * satisfy `execution[of] <= bound` for the current call. No cumulative
  * tracking. Used by: amount_max, recipient_max, booking_duration_max, etc.
+ *
+ * `requiredFor` (v0.8+) closes the converse: without it, a call that does
+ * not carry `of` at all is simply skipped — a 5,000 cap refuses 6,000 but
+ * permits a call that declares no value whatsoever, which is indistinguishable
+ * from an unenforced bound. The same hole, and the same fix, as
+ * `FieldConstraint.requiredFor` on a scope constraint (below): values drawn
+ * from the profile's `boundsSchema.actionTypes` registry. For a listed
+ * `action_type`, an execution whose context lacks `of` — or whose value is
+ * not a finite number — MUST be refused rather than skipped. For an
+ * unlisted (or when `requiredFor` is absent) action type, today's
+ * skip-on-absence behaviour is unchanged. Meaningful only on
+ * `per_transaction`; the other `BoundType` kinds have no per-call "value
+ * exposed or not" question — `cumulative_sum`/`cumulative_count` always read
+ * from the execution log regardless of what this call declares, and `enum`
+ * is a capability flag, not a runtime value — so the field does not exist
+ * on those variants and a profile that puts it there has it silently
+ * ignored by every enforcement point (TypeScript also refuses it when the
+ * profile is authored against this type rather than raw JSON).
  */
 {
     kind: 'per_transaction';
     of: string;
+    requiredFor?: string[];
 }
 /**
  * Cumulative sum within a time window. The SP maintains a running sum
@@ -448,6 +467,11 @@ interface ExecutionPath {
  *
  * Supports both v0.3 (frameSchema) and v0.4 (boundsSchema + contextSchema).
  */
+/**
+ * A commitment mode a person can choose when signing a mandate. (`review_above_cap`
+ * is not chosen by the signer — it follows from team caps.)
+ */
+type SignableCommitmentMode = 'automatic' | 'review';
 interface AgentProfile {
     id: string;
     name?: string;
@@ -489,6 +513,18 @@ interface AgentProfile {
      * a forwarded message has usually lost the footer that carried it.
      */
     receipt_lookup?: boolean;
+    /**
+     * The commitment modes a mandate under this profile may be signed with.
+     * Absent → every mode (`automatic`, `review`), as before this field existed.
+     *
+     * Lets a profile be review-only: every action it governs then needs a
+     * person's approval, whatever the signer would have picked. The Authority
+     * Server refuses to sign a mandate whose `commitment_mode` is not listed;
+     * a mandate screen offers only the listed modes. Fail-closed: a declared
+     * list with no valid entry allows nothing — a malformed declaration never
+     * widens what a profile allows. See {@link allowedCommitmentModes}.
+     */
+    commitment_modes?: readonly SignableCommitmentMode[];
     /**
      * v0.3 frame schema (deprecated, kept for backward compat).
      * Used when boundsSchema is not present.
@@ -503,6 +539,16 @@ interface AgentProfile {
     boundsSchema?: {
         keyOrder: string[];
         fields: Record<string, ProfileBoundsField>;
+        /**
+         * v0.5+ registry of the action types this profile recognizes (e.g.
+         * `["send", "delete", "setup"]`). Every `execution.action_type` the
+         * Authority Server and gateway accept for this profile MUST be a member
+         * when the registry is declared (protocol.md → Bounds Schema, rule 2);
+         * it is also what a `per_transaction` bound's `requiredFor` draws from.
+         * Absent on profiles published before the registry existed — membership
+         * is then uncheckable, not a violation.
+         */
+        actionTypes?: readonly string[];
     };
     /**
      * v0.4 context schema — defines the execution context parameters (e.g., currency, action_type).
@@ -983,6 +1029,25 @@ declare function validateContextParams(params: AgentContextParams, profile: Agen
     valid: boolean;
     errors: string[];
 };
+/**
+ * Authoring-time check for `per_transaction` bound `requiredFor` (v0.8+):
+ * entries must name a real `action_type` from the profile's declared
+ * `boundsSchema.actionTypes` registry, and the field is only meaningful on
+ * `per_transaction` bounds (see `BoundType`'s doc comment for why the other
+ * kinds don't carry it).
+ *
+ * This is NOT wired into `registerProfile` or any enforcement path — nothing
+ * in hap-core validates profile JSON at load time today (the pre-existing
+ * `requiredFor` on a context/scope constraint has the same gap), so adding
+ * an automatic refusal here would be new behaviour beyond this change's
+ * scope. Call it explicitly from an authoring tool, a hap-profiles CI check,
+ * or a test, to catch a `requiredFor` entry that can never match (misspelled
+ * action type) or is attached to a bound kind that silently ignores it.
+ *
+ * Returns an empty array when the profile has no boundsSchema or nothing to
+ * check — never throws.
+ */
+declare function validateBoundsRequiredFor(profile: AgentProfile): string[];
 /**
  * Thrown when a value cannot be canonicalized at all — currently only for raw
  * LF/CR inside a value. Carries the protocol error code so callers can map it
@@ -1033,6 +1098,31 @@ declare function computeBoundsHash(params: AgentBoundsParams, profile: AgentProf
  */
 declare function computeContextHash(params: AgentContextParams, profile: AgentProfile): string;
 
+/**
+ * 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.
+ */
+
+/** Every mode a signer can choose, in the order a mandate screen shows them. */
+declare const SIGNABLE_COMMITMENT_MODES: readonly SignableCommitmentMode[];
+/**
+ * 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.
+ */
+declare function allowedCommitmentModes(profile: AgentProfile): readonly SignableCommitmentMode[];
+/** Whether a mandate under this profile may be signed with `mode`. */
+declare function isCommitmentModeAllowed(profile: AgentProfile, mode: string): boolean;
+/**
+ * Authoring check for a profile's `commitment_modes` declaration — for
+ * hap-profiles CI, an authoring tool or a test. Like `validateBoundsRequiredFor`
+ * it is not wired into profile loading; enforcement reads the declaration
+ * fail-closed through `allowedCommitmentModes`. Empty array = nothing to fix.
+ */
+declare function validateCommitmentModes(profile: AgentProfile): string[];
+
 /**
  * Attestation Encoding, Decoding, and Verification
  *
@@ -1353,4 +1443,4 @@ interface ReceiptPayload {
  */
 declare function verifyReceiptSignature(receipt: ReceiptPayload, publicKeyHex: string): Promise<void>;
 
-export { type AgentBoundsParams, type AgentContextParams, type AgentFrameParams, type AgentProfile, type ApprovalObject, type Attestation, type AttestationHeader, type AttestationPayload, type BoundType, CanonicalValueError, type ContentBinding, ContentBindingError, type ContentBindingErrorCode, type CumulativeFieldDef, type CumulativeWindow, type DeclaredFieldDef, type ExecutionContextFieldDef, type ExecutionLogEntry, type ExecutionLogQuery, type ExecutionMappingTransform, type ExecutionMappingValue, type ExecutionPath, type FieldConstraint, type FieldUnit, type GateQuestion, type GatekeeperError, type GatekeeperRequest, type GatekeeperResult, type MandateBinding, MandateError, type MandateProjection, type OwnerMandate, type ProfileBoundsField, type ProfileContextField, type ProfileFrameField, type ProfileToolGating, type ProfileToolGatingEntry, type ReceiptPayload, type ResolvedDomain, type SigningSurface, type Subject, type SubjectValidation, approvalSigningBytes, attestationId, bindingAppliesTo, boundActionTypes, buildMandateProjection, canonicalBounds, canonicalContext, canonicalFrame, canonicalize, canonicalizeText, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContentHash, computeContextHash, computeFieldsContentHash, computeFrameHash, computeIntentDisclosureHash, computeIntentHash, contentCanonicalBytes, decodeAttestationBlob, decodeDidKey, deriveIdentityLine, encodeAttestationBlob, encodeDidKey, frameHash, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, isFieldBinding, isKeyBearingDid, isV4Attestation, listProfiles, mandateSigningBytes, registerProfile, selectBoundFields, signApproval, signMandateProjection, validateBoundsParams, validateContextParams, validateFrameParams, validateSubject, verify, verifyApproval, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash, verifyOwnerMandate, verifyOwnerMandates, verifyReceiptSignature };
+export { type AgentBoundsParams, type AgentContextParams, type AgentFrameParams, type AgentProfile, type ApprovalObject, type Attestation, type AttestationHeader, type AttestationPayload, type BoundType, CanonicalValueError, type ContentBinding, ContentBindingError, type ContentBindingErrorCode, type CumulativeFieldDef, type CumulativeWindow, type DeclaredFieldDef, type ExecutionContextFieldDef, type ExecutionLogEntry, type ExecutionLogQuery, type ExecutionMappingTransform, type ExecutionMappingValue, type ExecutionPath, type FieldConstraint, type FieldUnit, type GateQuestion, type GatekeeperError, type GatekeeperRequest, type GatekeeperResult, type MandateBinding, MandateError, type MandateProjection, type OwnerMandate, type ProfileBoundsField, type ProfileContextField, type ProfileFrameField, type ProfileToolGating, type ProfileToolGatingEntry, type ReceiptPayload, type ResolvedDomain, SIGNABLE_COMMITMENT_MODES, type SignableCommitmentMode, type SigningSurface, type Subject, type SubjectValidation, allowedCommitmentModes, approvalSigningBytes, attestationId, bindingAppliesTo, boundActionTypes, buildMandateProjection, canonicalBounds, canonicalContext, canonicalFrame, canonicalize, canonicalizeText, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContentHash, computeContextHash, computeFieldsContentHash, computeFrameHash, computeIntentDisclosureHash, computeIntentHash, contentCanonicalBytes, decodeAttestationBlob, decodeDidKey, deriveIdentityLine, encodeAttestationBlob, encodeDidKey, frameHash, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, isCommitmentModeAllowed, isFieldBinding, isKeyBearingDid, isV4Attestation, listProfiles, mandateSigningBytes, registerProfile, selectBoundFields, signApproval, signMandateProjection, validateBoundsParams, validateBoundsRequiredFor, validateCommitmentModes, validateContextParams, validateFrameParams, validateSubject, verify, verifyApproval, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash, verifyOwnerMandate, verifyOwnerMandates, verifyReceiptSignature };

package/dist/index.js

@@ -33,6 +33,8 @@ __export(index_exports, {
   CanonicalValueError: () => CanonicalValueError,
   ContentBindingError: () => ContentBindingError,
   MandateError: () => MandateError,
+  SIGNABLE_COMMITMENT_MODES: () => SIGNABLE_COMMITMENT_MODES,
+  allowedCommitmentModes: () => allowedCommitmentModes,
   approvalSigningBytes: () => approvalSigningBytes,
   attestationId: () => attestationId,
   bindingAppliesTo: () => bindingAppliesTo,
@@ -62,6 +64,7 @@ __export(index_exports, {
   getAllProfiles: () => getAllProfiles,
   getProfile: () => getProfile,
   intentDisclosureCanonicalBytes: () => intentDisclosureCanonicalBytes,
+  isCommitmentModeAllowed: () => isCommitmentModeAllowed,
   isFieldBinding: () => isFieldBinding,
   isKeyBearingDid: () => isKeyBearingDid,
   isV4Attestation: () => isV4Attestation,
@@ -72,6 +75,8 @@ __export(index_exports, {
   signApproval: () => signApproval,
   signMandateProjection: () => signMandateProjection,
   validateBoundsParams: () => validateBoundsParams,
+  validateBoundsRequiredFor: () => validateBoundsRequiredFor,
+  validateCommitmentModes: () => validateCommitmentModes,
   validateContextParams: () => validateContextParams,
   validateFrameParams: () => validateFrameParams,
   validateSubject: () => validateSubject,
@@ -378,6 +383,38 @@ function validateContextParams(params, profile) {
   }
   return { valid: errors.length === 0, errors };
 }
+function validateBoundsRequiredFor(profile) {
+  const errors = [];
+  const boundsSchema = profile.boundsSchema;
+  if (!boundsSchema) return errors;
+  const actionTypes = boundsSchema.actionTypes ? [...boundsSchema.actionTypes] : void 0;
+  for (const [fieldName, fieldDef] of Object.entries(boundsSchema.fields)) {
+    const bt = fieldDef.boundType;
+    if (!bt) continue;
+    const requiredFor = bt.requiredFor;
+    if (requiredFor === void 0) continue;
+    if (!Array.isArray(requiredFor) || !requiredFor.every((v) => typeof v === "string")) {
+      errors.push(`Bound "${fieldName}": requiredFor must be a string array.`);
+      continue;
+    }
+    if (bt.kind !== "per_transaction") {
+      errors.push(
+        `Bound "${fieldName}": requiredFor is only meaningful on a per_transaction bound (found on kind "${bt.kind}") \u2014 every enforcement point ignores it there. Remove it.`
+      );
+      continue;
+    }
+    if (actionTypes) {
+      for (const actionType of requiredFor) {
+        if (!actionTypes.includes(actionType)) {
+          errors.push(
+            `Bound "${fieldName}": requiredFor names action type "${actionType}", which is not in this profile's boundsSchema.actionTypes registry [${actionTypes.join(", ")}]. It can never match a real execution and the requirement is dead.`
+          );
+        }
+      }
+    }
+  }
+  return errors;
+}
 var CanonicalValueError = class extends Error {
   code;
   field;
@@ -445,6 +482,33 @@ function computeContextHash(params, profile) {
   return `sha256:${hash}`;
 }
 
+// src/commitment-modes.ts
+var SIGNABLE_COMMITMENT_MODES = ["review", "automatic"];
+var isSignable = (v) => typeof v === "string" && SIGNABLE_COMMITMENT_MODES.includes(v);
+function allowedCommitmentModes(profile) {
+  const declared = profile.commitment_modes;
+  if (declared === void 0) return SIGNABLE_COMMITMENT_MODES;
+  if (!Array.isArray(declared)) return [];
+  return SIGNABLE_COMMITMENT_MODES.filter((m) => declared.includes(m));
+}
+function isCommitmentModeAllowed(profile, mode) {
+  return isSignable(mode) && allowedCommitmentModes(profile).includes(mode);
+}
+function validateCommitmentModes(profile) {
+  const declared = profile.commitment_modes;
+  if (declared === void 0) return [];
+  if (!Array.isArray(declared)) return ["commitment_modes must be a list of modes."];
+  const errors = [];
+  if (declared.length === 0) errors.push("commitment_modes is empty \u2014 no mandate could ever be signed under this profile.");
+  const seen = /* @__PURE__ */ new Set();
+  for (const m of declared) {
+    if (!isSignable(m)) errors.push(`commitment_modes: "${String(m)}" is not a mode a signer can choose (${SIGNABLE_COMMITMENT_MODES.join(", ")}).`);
+    if (seen.has(m)) errors.push(`commitment_modes: "${String(m)}" appears twice.`);
+    seen.add(m);
+  }
+  return errors;
+}
+
 // src/attestation.ts
 var import_crypto4 = require("crypto");
 var ed = __toESM(require("@noble/ed25519"));
@@ -820,6 +884,22 @@ function checkBoundsV4(request, profile, executionLog, now) {
     switch (bt.kind) {
       case "per_transaction": {
         const actual = request.execution[bt.of];
+        const engaged = !!bt.requiredFor?.length && actionType !== void 0 && bt.requiredFor.includes(actionType);
+        if (engaged) {
+          const missing = actual === void 0 || actual === null;
+          const numericActual = missing ? NaN : typeof actual === "number" ? actual : Number(actual);
+          const missingOrNonNumeric = missing || Number.isNaN(numericActual);
+          if (missingOrNonNumeric) {
+            errors.push({
+              code: "BOUND_EXCEEDED",
+              field: bt.of,
+              message: missing ? `Bound "${fieldName}" requires "${bt.of}" for "${actionType}" calls, but this call exposes no ${bt.of} to check against it. Refusing: the call cannot be shown to stay within ${fieldName}.` : `Bound "${fieldName}" requires a numeric "${bt.of}" for "${actionType}" calls, but this call's value (${String(actual)}) is not a number. Refusing: the call cannot be shown to stay within ${fieldName}.`,
+              bound: boundValue,
+              actual
+            });
+            continue;
+          }
+        }
         if (actual === void 0) continue;
         if (typeof boundValue !== "number" || typeof actual !== "number") {
           errors.push({
@@ -1227,6 +1307,8 @@ async function verifyReceiptSignature(receipt, publicKeyHex) {
   CanonicalValueError,
   ContentBindingError,
   MandateError,
+  SIGNABLE_COMMITMENT_MODES,
+  allowedCommitmentModes,
   approvalSigningBytes,
   attestationId,
   bindingAppliesTo,
@@ -1256,6 +1338,7 @@ async function verifyReceiptSignature(receipt, publicKeyHex) {
   getAllProfiles,
   getProfile,
   intentDisclosureCanonicalBytes,
+  isCommitmentModeAllowed,
   isFieldBinding,
   isKeyBearingDid,
   isV4Attestation,
@@ -1266,6 +1349,8 @@ async function verifyReceiptSignature(receipt, publicKeyHex) {
   signApproval,
   signMandateProjection,
   validateBoundsParams,
+  validateBoundsRequiredFor,
+  validateCommitmentModes,
   validateContextParams,
   validateFrameParams,
   validateSubject,

package/dist/index.mjs

@@ -287,6 +287,38 @@ function validateContextParams(params, profile) {
   }
   return { valid: errors.length === 0, errors };
 }
+function validateBoundsRequiredFor(profile) {
+  const errors = [];
+  const boundsSchema = profile.boundsSchema;
+  if (!boundsSchema) return errors;
+  const actionTypes = boundsSchema.actionTypes ? [...boundsSchema.actionTypes] : void 0;
+  for (const [fieldName, fieldDef] of Object.entries(boundsSchema.fields)) {
+    const bt = fieldDef.boundType;
+    if (!bt) continue;
+    const requiredFor = bt.requiredFor;
+    if (requiredFor === void 0) continue;
+    if (!Array.isArray(requiredFor) || !requiredFor.every((v) => typeof v === "string")) {
+      errors.push(`Bound "${fieldName}": requiredFor must be a string array.`);
+      continue;
+    }
+    if (bt.kind !== "per_transaction") {
+      errors.push(
+        `Bound "${fieldName}": requiredFor is only meaningful on a per_transaction bound (found on kind "${bt.kind}") \u2014 every enforcement point ignores it there. Remove it.`
+      );
+      continue;
+    }
+    if (actionTypes) {
+      for (const actionType of requiredFor) {
+        if (!actionTypes.includes(actionType)) {
+          errors.push(
+            `Bound "${fieldName}": requiredFor names action type "${actionType}", which is not in this profile's boundsSchema.actionTypes registry [${actionTypes.join(", ")}]. It can never match a real execution and the requirement is dead.`
+          );
+        }
+      }
+    }
+  }
+  return errors;
+}
 var CanonicalValueError = class extends Error {
   code;
   field;
@@ -354,6 +386,33 @@ function computeContextHash(params, profile) {
   return `sha256:${hash}`;
 }
 
+// src/commitment-modes.ts
+var SIGNABLE_COMMITMENT_MODES = ["review", "automatic"];
+var isSignable = (v) => typeof v === "string" && SIGNABLE_COMMITMENT_MODES.includes(v);
+function allowedCommitmentModes(profile) {
+  const declared = profile.commitment_modes;
+  if (declared === void 0) return SIGNABLE_COMMITMENT_MODES;
+  if (!Array.isArray(declared)) return [];
+  return SIGNABLE_COMMITMENT_MODES.filter((m) => declared.includes(m));
+}
+function isCommitmentModeAllowed(profile, mode) {
+  return isSignable(mode) && allowedCommitmentModes(profile).includes(mode);
+}
+function validateCommitmentModes(profile) {
+  const declared = profile.commitment_modes;
+  if (declared === void 0) return [];
+  if (!Array.isArray(declared)) return ["commitment_modes must be a list of modes."];
+  const errors = [];
+  if (declared.length === 0) errors.push("commitment_modes is empty \u2014 no mandate could ever be signed under this profile.");
+  const seen = /* @__PURE__ */ new Set();
+  for (const m of declared) {
+    if (!isSignable(m)) errors.push(`commitment_modes: "${String(m)}" is not a mode a signer can choose (${SIGNABLE_COMMITMENT_MODES.join(", ")}).`);
+    if (seen.has(m)) errors.push(`commitment_modes: "${String(m)}" appears twice.`);
+    seen.add(m);
+  }
+  return errors;
+}
+
 // src/attestation.ts
 import { createHash as createHash4 } from "crypto";
 import * as ed from "@noble/ed25519";
@@ -729,6 +788,22 @@ function checkBoundsV4(request, profile, executionLog, now) {
     switch (bt.kind) {
       case "per_transaction": {
         const actual = request.execution[bt.of];
+        const engaged = !!bt.requiredFor?.length && actionType !== void 0 && bt.requiredFor.includes(actionType);
+        if (engaged) {
+          const missing = actual === void 0 || actual === null;
+          const numericActual = missing ? NaN : typeof actual === "number" ? actual : Number(actual);
+          const missingOrNonNumeric = missing || Number.isNaN(numericActual);
+          if (missingOrNonNumeric) {
+            errors.push({
+              code: "BOUND_EXCEEDED",
+              field: bt.of,
+              message: missing ? `Bound "${fieldName}" requires "${bt.of}" for "${actionType}" calls, but this call exposes no ${bt.of} to check against it. Refusing: the call cannot be shown to stay within ${fieldName}.` : `Bound "${fieldName}" requires a numeric "${bt.of}" for "${actionType}" calls, but this call's value (${String(actual)}) is not a number. Refusing: the call cannot be shown to stay within ${fieldName}.`,
+              bound: boundValue,
+              actual
+            });
+            continue;
+          }
+        }
         if (actual === void 0) continue;
         if (typeof boundValue !== "number" || typeof actual !== "number") {
           errors.push({
@@ -1135,6 +1210,8 @@ export {
   CanonicalValueError,
   ContentBindingError,
   MandateError,
+  SIGNABLE_COMMITMENT_MODES,
+  allowedCommitmentModes,
   approvalSigningBytes,
   attestationId,
   bindingAppliesTo,
@@ -1164,6 +1241,7 @@ export {
   getAllProfiles,
   getProfile,
   intentDisclosureCanonicalBytes,
+  isCommitmentModeAllowed,
   isFieldBinding,
   isKeyBearingDid,
   isV4Attestation,
@@ -1174,6 +1252,8 @@ export {
   signApproval,
   signMandateProjection,
   validateBoundsParams,
+  validateBoundsRequiredFor,
+  validateCommitmentModes,
   validateContextParams,
   validateFrameParams,
   validateSubject,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanagencyp/hap-core",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "description": "Core types, cryptographic primitives, and verification logic for the Human Agency Protocol",
   "license": "MIT",
   "repository": {

package/src/commitment-modes.ts

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ */
+import type { AgentProfile, 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'];
+
+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.
+ */
+export function allowedCommitmentModes(profile: AgentProfile): readonly SignableCommitmentMode[] {
+  const declared = (profile as { commitment_modes?: unknown }).commitment_modes;
+  if (declared === undefined) return SIGNABLE_COMMITMENT_MODES;
+  if (!Array.isArray(declared)) return [];
+  return SIGNABLE_COMMITMENT_MODES.filter((m) => declared.includes(m));
+}
+
+/** Whether a mandate under this profile may be signed with `mode`. */
+export function isCommitmentModeAllowed(profile: AgentProfile, mode: string): boolean {
+  return isSignable(mode) && allowedCommitmentModes(profile).includes(mode);
+}
+
+/**
+ * Authoring check for a profile's `commitment_modes` declaration — for
+ * hap-profiles CI, an authoring tool or a test. Like `validateBoundsRequiredFor`
+ * it is not wired into profile loading; enforcement reads the declaration
+ * fail-closed through `allowedCommitmentModes`. Empty array = nothing to fix.
+ */
+export function validateCommitmentModes(profile: AgentProfile): string[] {
+  const declared = (profile as { commitment_modes?: unknown }).commitment_modes;
+  if (declared === undefined) return [];
+  if (!Array.isArray(declared)) return ['commitment_modes must be a list of modes.'];
+  const errors: string[] = [];
+  if (declared.length === 0) errors.push('commitment_modes is empty — no mandate could ever be signed under this profile.');
+  const seen = new Set<unknown>();
+  for (const m of declared) {
+    if (!isSignable(m)) errors.push(`commitment_modes: "${String(m)}" is not a mode a signer can choose (${SIGNABLE_COMMITMENT_MODES.join(', ')}).`);
+    if (seen.has(m)) errors.push(`commitment_modes: "${String(m)}" appears twice.`);
+    seen.add(m);
+  }
+  return errors;
+}

package/src/frame.ts

@@ -13,7 +13,7 @@
  */
 
 import { createHash } from 'crypto';
-import type { AgentFrameParams, AgentBoundsParams, AgentContextParams, AgentProfile } from './types';
+import type { AgentFrameParams, AgentBoundsParams, AgentContextParams, AgentProfile, BoundType } from './types';
 
 // ─── v0.3 Frame Functions ─────────────────────────────────────────────────────
 
@@ -179,6 +179,68 @@ export function validateContextParams(
   return { valid: errors.length === 0, errors };
 }
 
+/**
+ * Authoring-time check for `per_transaction` bound `requiredFor` (v0.8+):
+ * entries must name a real `action_type` from the profile's declared
+ * `boundsSchema.actionTypes` registry, and the field is only meaningful on
+ * `per_transaction` bounds (see `BoundType`'s doc comment for why the other
+ * kinds don't carry it).
+ *
+ * This is NOT wired into `registerProfile` or any enforcement path — nothing
+ * in hap-core validates profile JSON at load time today (the pre-existing
+ * `requiredFor` on a context/scope constraint has the same gap), so adding
+ * an automatic refusal here would be new behaviour beyond this change's
+ * scope. Call it explicitly from an authoring tool, a hap-profiles CI check,
+ * or a test, to catch a `requiredFor` entry that can never match (misspelled
+ * action type) or is attached to a bound kind that silently ignores it.
+ *
+ * Returns an empty array when the profile has no boundsSchema or nothing to
+ * check — never throws.
+ */
+export function validateBoundsRequiredFor(profile: AgentProfile): string[] {
+  const errors: string[] = [];
+  const boundsSchema = profile.boundsSchema;
+  if (!boundsSchema) return errors;
+
+  const actionTypes = boundsSchema.actionTypes ? [...boundsSchema.actionTypes] : undefined;
+
+  for (const [fieldName, fieldDef] of Object.entries(boundsSchema.fields)) {
+    const bt = fieldDef.boundType as (BoundType & { requiredFor?: unknown }) | undefined;
+    if (!bt) continue;
+    const requiredFor = (bt as { requiredFor?: unknown }).requiredFor;
+    if (requiredFor === undefined) continue;
+
+    if (!Array.isArray(requiredFor) || !requiredFor.every((v) => typeof v === 'string')) {
+      errors.push(`Bound "${fieldName}": requiredFor must be a string array.`);
+      continue;
+    }
+
+    if (bt.kind !== 'per_transaction') {
+      errors.push(
+        `Bound "${fieldName}": requiredFor is only meaningful on a per_transaction bound ` +
+        `(found on kind "${bt.kind}") — every enforcement point ignores it there. Remove it.`,
+      );
+      continue;
+    }
+
+    if (actionTypes) {
+      for (const actionType of requiredFor) {
+        if (!actionTypes.includes(actionType)) {
+          errors.push(
+            `Bound "${fieldName}": requiredFor names action type "${actionType}", which is not ` +
+            `in this profile's boundsSchema.actionTypes registry [${actionTypes.join(', ')}]. ` +
+            `It can never match a real execution and the requirement is dead.`,
+          );
+        }
+      }
+    }
+    // No actionTypes registry declared: membership cannot be checked (same
+    // tolerance the AS receipt route applies to pre-registry profiles).
+  }
+
+  return errors;
+}
+
 // ─── Value Encoding (normative, v0.5+) ───────────────────────────────────────
 
 /**

package/src/gatekeeper.ts

@@ -546,6 +546,43 @@ function checkBoundsV4(
     switch (bt.kind) {
       case 'per_transaction': {
         const actual = request.execution[bt.of];
+
+        // `requiredFor`: for a listed action_type, absence (or a non-numeric
+        // value) is a denial, not a skip — see BoundType.per_transaction's
+        // doc comment for why. Unlisted action types, or no `requiredFor` at
+        // all, keep the pre-existing skip-on-absence behaviour below.
+        const engaged = !!bt.requiredFor?.length
+          && actionType !== undefined
+          && bt.requiredFor.includes(actionType);
+
+        if (engaged) {
+          // `null` is treated as "missing", not as the number 0 — JSON has no
+          // undefined, so a value lost somewhere upstream (an unmapped
+          // connector field serialized through JSON) commonly arrives as
+          // null. `Number(null) === 0` would otherwise read as "an amount of
+          // zero was declared and is within bound", which is the exact
+          // silent-pass this feature exists to close.
+          const missing = actual === undefined || actual === null;
+          const numericActual = missing ? NaN : (typeof actual === 'number' ? actual : Number(actual));
+          const missingOrNonNumeric = missing || Number.isNaN(numericActual);
+          if (missingOrNonNumeric) {
+            errors.push({
+              code: 'BOUND_EXCEEDED',
+              field: bt.of,
+              message: missing
+                ? `Bound "${fieldName}" requires "${bt.of}" for "${actionType}" calls, but this ` +
+                  `call exposes no ${bt.of} to check against it. Refusing: the call cannot be ` +
+                  `shown to stay within ${fieldName}.`
+                : `Bound "${fieldName}" requires a numeric "${bt.of}" for "${actionType}" calls, ` +
+                  `but this call's value (${String(actual)}) is not a number. Refusing: the call ` +
+                  `cannot be shown to stay within ${fieldName}.`,
+              bound: boundValue,
+              actual,
+            });
+            continue;
+          }
+        }
+
         if (actual === undefined) continue;
         if (typeof boundValue !== 'number' || typeof actual !== 'number') {
           errors.push({

package/src/index.ts

@@ -10,6 +10,7 @@ export * from './content-binding';
 export * from './intent-disclosure';
 export * from './identity';
 export * from './frame';
+export * from './commitment-modes';
 export * from './attestation';
 export * from './gatekeeper';
 export * from './profiles';

package/src/types.ts

@@ -218,8 +218,26 @@ export type BoundType =
    * Per-transaction cap. The execution context field named in `of` must
    * satisfy `execution[of] <= bound` for the current call. No cumulative
    * tracking. Used by: amount_max, recipient_max, booking_duration_max, etc.
+   *
+   * `requiredFor` (v0.8+) closes the converse: without it, a call that does
+   * not carry `of` at all is simply skipped — a 5,000 cap refuses 6,000 but
+   * permits a call that declares no value whatsoever, which is indistinguishable
+   * from an unenforced bound. The same hole, and the same fix, as
+   * `FieldConstraint.requiredFor` on a scope constraint (below): values drawn
+   * from the profile's `boundsSchema.actionTypes` registry. For a listed
+   * `action_type`, an execution whose context lacks `of` — or whose value is
+   * not a finite number — MUST be refused rather than skipped. For an
+   * unlisted (or when `requiredFor` is absent) action type, today's
+   * skip-on-absence behaviour is unchanged. Meaningful only on
+   * `per_transaction`; the other `BoundType` kinds have no per-call "value
+   * exposed or not" question — `cumulative_sum`/`cumulative_count` always read
+   * from the execution log regardless of what this call declares, and `enum`
+   * is a capability flag, not a runtime value — so the field does not exist
+   * on those variants and a profile that puts it there has it silently
+   * ignored by every enforcement point (TypeScript also refuses it when the
+   * profile is authored against this type rather than raw JSON).
    */
-  | { kind: 'per_transaction'; of: string }
+  | { kind: 'per_transaction'; of: string; requiredFor?: string[] }
   /**
    * Cumulative sum within a time window. The SP maintains a running sum
    * of `execution[of]` across all prior executions in the window; the
@@ -461,6 +479,12 @@ export interface ExecutionPath {
  *
  * Supports both v0.3 (frameSchema) and v0.4 (boundsSchema + contextSchema).
  */
+/**
+ * A commitment mode a person can choose when signing a mandate. (`review_above_cap`
+ * is not chosen by the signer — it follows from team caps.)
+ */
+export type SignableCommitmentMode = 'automatic' | 'review';
+
 export interface AgentProfile {
   id: string;
   name?: string;
@@ -505,6 +529,19 @@ export interface AgentProfile {
    */
   receipt_lookup?: boolean;
 
+  /**
+   * The commitment modes a mandate under this profile may be signed with.
+   * Absent → every mode (`automatic`, `review`), as before this field existed.
+   *
+   * Lets a profile be review-only: every action it governs then needs a
+   * person's approval, whatever the signer would have picked. The Authority
+   * Server refuses to sign a mandate whose `commitment_mode` is not listed;
+   * a mandate screen offers only the listed modes. Fail-closed: a declared
+   * list with no valid entry allows nothing — a malformed declaration never
+   * widens what a profile allows. See {@link allowedCommitmentModes}.
+   */
+  commitment_modes?: readonly SignableCommitmentMode[];
+
   /**
    * v0.3 frame schema (deprecated, kept for backward compat).
    * Used when boundsSchema is not present.
@@ -520,6 +557,16 @@ export interface AgentProfile {
   boundsSchema?: {
     keyOrder: string[];
     fields: Record<string, ProfileBoundsField>;
+    /**
+     * v0.5+ registry of the action types this profile recognizes (e.g.
+     * `["send", "delete", "setup"]`). Every `execution.action_type` the
+     * Authority Server and gateway accept for this profile MUST be a member
+     * when the registry is declared (protocol.md → Bounds Schema, rule 2);
+     * it is also what a `per_transaction` bound's `requiredFor` draws from.
+     * Absent on profiles published before the registry existed — membership
+     * is then uncheckable, not a violation.
+     */
+    actionTypes?: readonly string[];
   };
 
   /**