@humanagencyp/hap-core 0.11.0 → 0.11.2

package/dist/index.d.mts

@@ -315,6 +315,19 @@ interface ProfileBoundsField {
      * kinds, and the same boundType can carry different units.
      */
     unit?: FieldUnit;
+    /**
+     * The largest value a mandate may set for this (numeric) bound — a ceiling
+     * on what the owner can grant, declared by the profile. E.g. reporting@0.2
+     * `read_max_age_days: { maximum: 366 }`: no reporting mandate may read back
+     * further than a year.
+     *
+     * Distinct from the bound itself: the bound limits each ACTION; `maximum`
+     * limits the MANDATE. A value above it is not a valid mandate for this
+     * profile — the mandate editor caps its input, the issuing Authority Server
+     * should refuse it, and an enforcement point that reads the bound applies
+     * min(value, maximum). Absent → no ceiling.
+     */
+    maximum?: number;
     /** @deprecated v0.4: use boundType instead. */
     constraint?: FieldConstraint;
     /** @deprecated v0.4: use boundType: { kind: 'enum', values: [...] }. */
@@ -467,6 +480,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;
@@ -508,6 +526,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.
@@ -1081,6 +1111,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
  *
@@ -1401,4 +1456,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, validateBoundsRequiredFor, 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

@@ -315,6 +315,19 @@ interface ProfileBoundsField {
      * kinds, and the same boundType can carry different units.
      */
     unit?: FieldUnit;
+    /**
+     * The largest value a mandate may set for this (numeric) bound — a ceiling
+     * on what the owner can grant, declared by the profile. E.g. reporting@0.2
+     * `read_max_age_days: { maximum: 366 }`: no reporting mandate may read back
+     * further than a year.
+     *
+     * Distinct from the bound itself: the bound limits each ACTION; `maximum`
+     * limits the MANDATE. A value above it is not a valid mandate for this
+     * profile — the mandate editor caps its input, the issuing Authority Server
+     * should refuse it, and an enforcement point that reads the bound applies
+     * min(value, maximum). Absent → no ceiling.
+     */
+    maximum?: number;
     /** @deprecated v0.4: use boundType instead. */
     constraint?: FieldConstraint;
     /** @deprecated v0.4: use boundType: { kind: 'enum', values: [...] }. */
@@ -467,6 +480,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;
@@ -508,6 +526,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.
@@ -1081,6 +1111,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
  *
@@ -1401,4 +1456,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, validateBoundsRequiredFor, 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,
@@ -73,6 +76,7 @@ __export(index_exports, {
   signMandateProjection: () => signMandateProjection,
   validateBoundsParams: () => validateBoundsParams,
   validateBoundsRequiredFor: () => validateBoundsRequiredFor,
+  validateCommitmentModes: () => validateCommitmentModes,
   validateContextParams: () => validateContextParams,
   validateFrameParams: () => validateFrameParams,
   validateSubject: () => validateSubject,
@@ -478,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"));
@@ -1276,6 +1307,8 @@ async function verifyReceiptSignature(receipt, publicKeyHex) {
   CanonicalValueError,
   ContentBindingError,
   MandateError,
+  SIGNABLE_COMMITMENT_MODES,
+  allowedCommitmentModes,
   approvalSigningBytes,
   attestationId,
   bindingAppliesTo,
@@ -1305,6 +1338,7 @@ async function verifyReceiptSignature(receipt, publicKeyHex) {
   getAllProfiles,
   getProfile,
   intentDisclosureCanonicalBytes,
+  isCommitmentModeAllowed,
   isFieldBinding,
   isKeyBearingDid,
   isV4Attestation,
@@ -1316,6 +1350,7 @@ async function verifyReceiptSignature(receipt, publicKeyHex) {
   signMandateProjection,
   validateBoundsParams,
   validateBoundsRequiredFor,
+  validateCommitmentModes,
   validateContextParams,
   validateFrameParams,
   validateSubject,

package/dist/index.mjs

@@ -386,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";
@@ -1183,6 +1210,8 @@ export {
   CanonicalValueError,
   ContentBindingError,
   MandateError,
+  SIGNABLE_COMMITMENT_MODES,
+  allowedCommitmentModes,
   approvalSigningBytes,
   attestationId,
   bindingAppliesTo,
@@ -1212,6 +1241,7 @@ export {
   getAllProfiles,
   getProfile,
   intentDisclosureCanonicalBytes,
+  isCommitmentModeAllowed,
   isFieldBinding,
   isKeyBearingDid,
   isV4Attestation,
@@ -1223,6 +1253,7 @@ export {
   signMandateProjection,
   validateBoundsParams,
   validateBoundsRequiredFor,
+  validateCommitmentModes,
   validateContextParams,
   validateFrameParams,
   validateSubject,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanagencyp/hap-core",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "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/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

@@ -320,6 +320,19 @@ export interface ProfileBoundsField {
    * kinds, and the same boundType can carry different units.
    */
   unit?: FieldUnit;
+  /**
+   * The largest value a mandate may set for this (numeric) bound — a ceiling
+   * on what the owner can grant, declared by the profile. E.g. reporting@0.2
+   * `read_max_age_days: { maximum: 366 }`: no reporting mandate may read back
+   * further than a year.
+   *
+   * Distinct from the bound itself: the bound limits each ACTION; `maximum`
+   * limits the MANDATE. A value above it is not a valid mandate for this
+   * profile — the mandate editor caps its input, the issuing Authority Server
+   * should refuse it, and an enforcement point that reads the bound applies
+   * min(value, maximum). Absent → no ceiling.
+   */
+  maximum?: number;
   /** @deprecated v0.4: use boundType instead. */
   constraint?: FieldConstraint;
   /** @deprecated v0.4: use boundType: { kind: 'enum', values: [...] }. */
@@ -479,6 +492,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;
@@ -523,6 +542,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.