@humanagencyp/hap-core 0.9.0 → 0.10.1

package/dist/index.d.mts

@@ -610,7 +610,21 @@ interface ExecutionLogQuery {
      * Sum a field's values within a time window for a given profile.
      * Use field="_count" to count executions instead of summing a field.
      */
-    sumByWindow(profileId: string, path: string, field: string, window: CumulativeWindow, now?: number): number;
+    sumByWindow(profileId: string, path: string, field: string, window: CumulativeWindow, now?: number, 
+    /**
+     * Only count executions whose `execution.action_type` is one of these.
+     * Omitted → every execution counts (a bound that governs all action types).
+     *
+     * Consumption is partitioned by action type (*Cumulative Tracking* rule 4):
+     * a bound counts only the action types it governs. Without the filter a
+     * profile with several action types feeds every bound the combined total —
+     * sales' "orders per day" counted quotes and sends too, and its daily order
+     * value summed quote values. Use {@link boundActionTypes} to derive it.
+     *
+     * Implementations SHOULD count an entry that carries no `action_type`
+     * against every filter: an unknown action is not evidence of headroom.
+     */
+    actionTypes?: readonly string[]): number;
 }
 /**
  * Agent frame parameters — mixed types (strings and numbers).
@@ -656,7 +670,7 @@ interface GatekeeperRequest {
  * Structured error from Gatekeeper verification.
  */
 interface GatekeeperError {
-    code: 'BOUND_EXCEEDED' | 'CUMULATIVE_LIMIT_EXCEEDED' | 'INVALID_SIGNATURE' | 'TTL_EXPIRED' | 'FRAME_MISMATCH' | 'BOUNDS_MISMATCH' | 'CONTEXT_MISMATCH' | 'DOMAIN_NOT_COVERED' | 'INVALID_PROFILE' | 'MALFORMED_ATTESTATION' | 'INVALID_ACTION_TYPE' | 'ATTESTATION_REVOKED' | 'APPROVAL_REQUIRED' | 'IDEMPOTENCY_MISMATCH' | 'MANDATE_SIGNATURE_REQUIRED' | 'MANDATE_SIGNATURE_INVALID' | 'APPROVAL_SIGNATURE_REQUIRED' | 'APPROVAL_SIGNATURE_INVALID';
+    code: 'BOUND_EXCEEDED' | 'CUMULATIVE_LIMIT_EXCEEDED' | 'INVALID_SIGNATURE' | 'TTL_EXPIRED' | 'FRAME_MISMATCH' | 'BOUNDS_MISMATCH' | 'CONTEXT_MISMATCH' | 'DOMAIN_NOT_COVERED' | 'INVALID_PROFILE' | 'MALFORMED_ATTESTATION' | 'INVALID_ACTION_TYPE' | 'ATTESTATION_REVOKED' | 'APPROVAL_REQUIRED' | 'IDEMPOTENCY_MISMATCH' | 'MANDATE_SIGNATURE_REQUIRED' | 'MANDATE_SIGNATURE_INVALID' | 'APPROVAL_SIGNATURE_REQUIRED' | 'APPROVAL_SIGNATURE_INVALID' | 'BOUNDS_INVALID_VALUE' | 'CONTEXT_INVALID_VALUE';
     field?: string;
     message: string;
     bound?: string | number;
@@ -921,8 +935,11 @@ declare function deriveIdentityLine(subject: Subject | undefined | null, { opera
  * Frame Canonicalization for Agent Profiles
  *
  * Agent profiles support mixed-type fields (strings and numbers).
- * Canonical form: all values are converted to strings via String(value).
- * Keys are ordered according to the profile's keyOrder.
+ * Canonical form: `key=value` records joined with LF, keys in the profile's
+ * keyOrder. Values are stringified with String(value) — the shortest
+ * round-trippable form for numbers — then percent-encoded per protocol.md
+ * (`=`, `%`, and every byte outside printable ASCII); a value carrying a raw
+ * LF/CR is refused, never normalized. See `canonicalRecords` below.
  *
  * v0.3: frameSchema
  * v0.4: boundsSchema + contextSchema (separate hashes)
@@ -966,19 +983,39 @@ declare function validateContextParams(params: AgentContextParams, profile: Agen
     valid: boolean;
     errors: 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
+ * straight onto the wire without string-matching a message.
+ *
+ * protocol.md → *Bounds & Scope Canonicalization* → Value encoding:
+ *   "Values MUST NOT contain raw newline (\n) or carriage-return (\r)
+ *    characters. Implementations MUST reject input containing them; silent
+ *    stripping or normalization is a violation because it produces a hash that
+ *    does not faithfully represent the input."
+ */
+declare class CanonicalValueError extends Error {
+    readonly code: 'BOUNDS_INVALID_VALUE' | 'CONTEXT_INVALID_VALUE';
+    readonly field: string;
+    constructor(code: 'BOUNDS_INVALID_VALUE' | 'CONTEXT_INVALID_VALUE', field: string, message: string);
+}
 /**
  * Builds the canonical bounds string from parameters.
- * All values are converted to strings. Keys are ordered per profile's boundsSchema.keyOrder.
+ * Keys are ordered per profile's boundsSchema.keyOrder; values are encoded per
+ * protocol.md → *Value encoding* (see `canonicalRecords`).
  *
  * @throws Error if any field fails validation
+ * @throws CanonicalValueError (code BOUNDS_INVALID_VALUE) if a value carries a raw LF/CR
  */
 declare function canonicalBounds(params: AgentBoundsParams, profile: AgentProfile): string;
 /**
  * Builds the canonical context string from parameters.
- * All values are converted to strings. Keys are ordered per profile's contextSchema.keyOrder.
+ * Keys are ordered per profile's contextSchema.keyOrder; values are encoded per
+ * protocol.md → *Value encoding* (see `canonicalRecords`).
  * For empty context (no contextSchema or no fields), returns "".
  *
  * @throws Error if any field fails validation
+ * @throws CanonicalValueError (code CONTEXT_INVALID_VALUE) if a value carries a raw LF/CR
  */
 declare function canonicalContext(params: AgentContextParams, profile: AgentProfile): string;
 /**
@@ -1103,6 +1140,23 @@ declare function verifyAttestationV4(blob: string, publicKeyHex: string, expecte
  * @param executionLog - Optional execution log for resolving cumulative fields
  */
 declare function verify(request: GatekeeperRequest, publicKeyHex: string, now?: number, executionLog?: ExecutionLogQuery): Promise<GatekeeperResult>;
+/**
+ * Which action types' executions count toward this cumulative bound's running
+ * total. `undefined` means all of them.
+ *
+ * `boundGovernsAction` decides whether a bound applies to the current call; this
+ * decides what the bound's total is made of. Both are needed: selecting the right
+ * bound and then feeding it the profile's combined total is still wrong — sales'
+ * "orders per day" was checked only on orders, but counted every quote and send.
+ * Consumption is partitioned by action type (*Cumulative Tracking* rule 4), as
+ * the Authority Server already does.
+ *
+ * Same answer, same order of preference as `boundGovernsAction`: the declared
+ * `appliesTo`; else, for a count bound named for an action (`delete_daily_max`),
+ * that action; else every action type. Exported so display surfaces report the
+ * same totals the gate enforces.
+ */
+declare function boundActionTypes(fieldName: string, fieldDef: ProfileBoundsField): readonly string[] | undefined;
 
 /**
  * Profile Registry — dynamically populated from git-hosted profile sources.
@@ -1299,4 +1353,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, 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, 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, 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 };

package/dist/index.d.ts

@@ -610,7 +610,21 @@ interface ExecutionLogQuery {
      * Sum a field's values within a time window for a given profile.
      * Use field="_count" to count executions instead of summing a field.
      */
-    sumByWindow(profileId: string, path: string, field: string, window: CumulativeWindow, now?: number): number;
+    sumByWindow(profileId: string, path: string, field: string, window: CumulativeWindow, now?: number, 
+    /**
+     * Only count executions whose `execution.action_type` is one of these.
+     * Omitted → every execution counts (a bound that governs all action types).
+     *
+     * Consumption is partitioned by action type (*Cumulative Tracking* rule 4):
+     * a bound counts only the action types it governs. Without the filter a
+     * profile with several action types feeds every bound the combined total —
+     * sales' "orders per day" counted quotes and sends too, and its daily order
+     * value summed quote values. Use {@link boundActionTypes} to derive it.
+     *
+     * Implementations SHOULD count an entry that carries no `action_type`
+     * against every filter: an unknown action is not evidence of headroom.
+     */
+    actionTypes?: readonly string[]): number;
 }
 /**
  * Agent frame parameters — mixed types (strings and numbers).
@@ -656,7 +670,7 @@ interface GatekeeperRequest {
  * Structured error from Gatekeeper verification.
  */
 interface GatekeeperError {
-    code: 'BOUND_EXCEEDED' | 'CUMULATIVE_LIMIT_EXCEEDED' | 'INVALID_SIGNATURE' | 'TTL_EXPIRED' | 'FRAME_MISMATCH' | 'BOUNDS_MISMATCH' | 'CONTEXT_MISMATCH' | 'DOMAIN_NOT_COVERED' | 'INVALID_PROFILE' | 'MALFORMED_ATTESTATION' | 'INVALID_ACTION_TYPE' | 'ATTESTATION_REVOKED' | 'APPROVAL_REQUIRED' | 'IDEMPOTENCY_MISMATCH' | 'MANDATE_SIGNATURE_REQUIRED' | 'MANDATE_SIGNATURE_INVALID' | 'APPROVAL_SIGNATURE_REQUIRED' | 'APPROVAL_SIGNATURE_INVALID';
+    code: 'BOUND_EXCEEDED' | 'CUMULATIVE_LIMIT_EXCEEDED' | 'INVALID_SIGNATURE' | 'TTL_EXPIRED' | 'FRAME_MISMATCH' | 'BOUNDS_MISMATCH' | 'CONTEXT_MISMATCH' | 'DOMAIN_NOT_COVERED' | 'INVALID_PROFILE' | 'MALFORMED_ATTESTATION' | 'INVALID_ACTION_TYPE' | 'ATTESTATION_REVOKED' | 'APPROVAL_REQUIRED' | 'IDEMPOTENCY_MISMATCH' | 'MANDATE_SIGNATURE_REQUIRED' | 'MANDATE_SIGNATURE_INVALID' | 'APPROVAL_SIGNATURE_REQUIRED' | 'APPROVAL_SIGNATURE_INVALID' | 'BOUNDS_INVALID_VALUE' | 'CONTEXT_INVALID_VALUE';
     field?: string;
     message: string;
     bound?: string | number;
@@ -921,8 +935,11 @@ declare function deriveIdentityLine(subject: Subject | undefined | null, { opera
  * Frame Canonicalization for Agent Profiles
  *
  * Agent profiles support mixed-type fields (strings and numbers).
- * Canonical form: all values are converted to strings via String(value).
- * Keys are ordered according to the profile's keyOrder.
+ * Canonical form: `key=value` records joined with LF, keys in the profile's
+ * keyOrder. Values are stringified with String(value) — the shortest
+ * round-trippable form for numbers — then percent-encoded per protocol.md
+ * (`=`, `%`, and every byte outside printable ASCII); a value carrying a raw
+ * LF/CR is refused, never normalized. See `canonicalRecords` below.
  *
  * v0.3: frameSchema
  * v0.4: boundsSchema + contextSchema (separate hashes)
@@ -966,19 +983,39 @@ declare function validateContextParams(params: AgentContextParams, profile: Agen
     valid: boolean;
     errors: 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
+ * straight onto the wire without string-matching a message.
+ *
+ * protocol.md → *Bounds & Scope Canonicalization* → Value encoding:
+ *   "Values MUST NOT contain raw newline (\n) or carriage-return (\r)
+ *    characters. Implementations MUST reject input containing them; silent
+ *    stripping or normalization is a violation because it produces a hash that
+ *    does not faithfully represent the input."
+ */
+declare class CanonicalValueError extends Error {
+    readonly code: 'BOUNDS_INVALID_VALUE' | 'CONTEXT_INVALID_VALUE';
+    readonly field: string;
+    constructor(code: 'BOUNDS_INVALID_VALUE' | 'CONTEXT_INVALID_VALUE', field: string, message: string);
+}
 /**
  * Builds the canonical bounds string from parameters.
- * All values are converted to strings. Keys are ordered per profile's boundsSchema.keyOrder.
+ * Keys are ordered per profile's boundsSchema.keyOrder; values are encoded per
+ * protocol.md → *Value encoding* (see `canonicalRecords`).
  *
  * @throws Error if any field fails validation
+ * @throws CanonicalValueError (code BOUNDS_INVALID_VALUE) if a value carries a raw LF/CR
  */
 declare function canonicalBounds(params: AgentBoundsParams, profile: AgentProfile): string;
 /**
  * Builds the canonical context string from parameters.
- * All values are converted to strings. Keys are ordered per profile's contextSchema.keyOrder.
+ * Keys are ordered per profile's contextSchema.keyOrder; values are encoded per
+ * protocol.md → *Value encoding* (see `canonicalRecords`).
  * For empty context (no contextSchema or no fields), returns "".
  *
  * @throws Error if any field fails validation
+ * @throws CanonicalValueError (code CONTEXT_INVALID_VALUE) if a value carries a raw LF/CR
  */
 declare function canonicalContext(params: AgentContextParams, profile: AgentProfile): string;
 /**
@@ -1103,6 +1140,23 @@ declare function verifyAttestationV4(blob: string, publicKeyHex: string, expecte
  * @param executionLog - Optional execution log for resolving cumulative fields
  */
 declare function verify(request: GatekeeperRequest, publicKeyHex: string, now?: number, executionLog?: ExecutionLogQuery): Promise<GatekeeperResult>;
+/**
+ * Which action types' executions count toward this cumulative bound's running
+ * total. `undefined` means all of them.
+ *
+ * `boundGovernsAction` decides whether a bound applies to the current call; this
+ * decides what the bound's total is made of. Both are needed: selecting the right
+ * bound and then feeding it the profile's combined total is still wrong — sales'
+ * "orders per day" was checked only on orders, but counted every quote and send.
+ * Consumption is partitioned by action type (*Cumulative Tracking* rule 4), as
+ * the Authority Server already does.
+ *
+ * Same answer, same order of preference as `boundGovernsAction`: the declared
+ * `appliesTo`; else, for a count bound named for an action (`delete_daily_max`),
+ * that action; else every action type. Exported so display surfaces report the
+ * same totals the gate enforces.
+ */
+declare function boundActionTypes(fieldName: string, fieldDef: ProfileBoundsField): readonly string[] | undefined;
 
 /**
  * Profile Registry — dynamically populated from git-hosted profile sources.
@@ -1299,4 +1353,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, 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, 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, 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 };

package/dist/index.js

@@ -30,11 +30,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CanonicalValueError: () => CanonicalValueError,
   ContentBindingError: () => ContentBindingError,
   MandateError: () => MandateError,
   approvalSigningBytes: () => approvalSigningBytes,
   attestationId: () => attestationId,
   bindingAppliesTo: () => bindingAppliesTo,
+  boundActionTypes: () => boundActionTypes,
   buildMandateProjection: () => buildMandateProjection,
   canonicalBounds: () => canonicalBounds,
   canonicalContext: () => canonicalContext,
@@ -376,15 +378,51 @@ function validateContextParams(params, profile) {
   }
   return { valid: errors.length === 0, errors };
 }
+var CanonicalValueError = class extends Error {
+  code;
+  field;
+  constructor(code, field, message) {
+    super(message);
+    this.name = "CanonicalValueError";
+    this.code = code;
+    this.field = field;
+  }
+};
+function percentEncodeCanonicalValue(raw) {
+  const bytes = new TextEncoder().encode(raw);
+  let out = "";
+  for (const b of bytes) {
+    if (b === 61 || b === 37 || b < 32 || b > 126) {
+      out += "%" + b.toString(16).toUpperCase().padStart(2, "0");
+    } else {
+      out += String.fromCharCode(b);
+    }
+  }
+  return out;
+}
+function canonicalRecords(params, keyOrder, code) {
+  const lines = [];
+  for (const key of keyOrder) {
+    const value = params[key];
+    if (value === void 0 || value === null) continue;
+    const raw = String(value);
+    if (raw.includes("\n") || raw.includes("\r")) {
+      throw new CanonicalValueError(
+        code,
+        key,
+        `Value for "${key}" contains a raw newline or carriage return. Refusing: a hash over stripped or normalized input would not represent what was authorized.`
+      );
+    }
+    lines.push(`${key}=${percentEncodeCanonicalValue(raw)}`);
+  }
+  return lines.join("\n");
+}
 function canonicalBounds(params, profile) {
   const validation = validateBoundsParams(params, profile);
   if (!validation.valid) {
     throw new Error(`Invalid bounds parameters: ${validation.errors.join("; ")}`);
   }
-  const lines = profile.boundsSchema.keyOrder.map(
-    (key) => `${key}=${String(params[key])}`
-  );
-  return lines.join("\n");
+  return canonicalRecords(params, profile.boundsSchema.keyOrder, "BOUNDS_INVALID_VALUE");
 }
 function canonicalContext(params, profile) {
   if (!profile.contextSchema || Object.keys(profile.contextSchema.fields).length === 0) {
@@ -394,10 +432,7 @@ function canonicalContext(params, profile) {
   if (!validation.valid) {
     throw new Error(`Invalid context parameters: ${validation.errors.join("; ")}`);
   }
-  const lines = profile.contextSchema.keyOrder.map(
-    (key) => `${key}=${String(params[key])}`
-  );
-  return lines.join("\n");
+  return canonicalRecords(params, profile.contextSchema.keyOrder, "CONTEXT_INVALID_VALUE");
 }
 function computeBoundsHash(params, profile) {
   const canonical = canonicalBounds(params, profile);
@@ -527,7 +562,17 @@ async function verify(request, publicKeyHex, now = Math.floor(Date.now() / 1e3),
     return verifyV3(request, profile, publicKeyHex, now, executionLog, errors);
   }
 }
+function noAttestationSupplied(request) {
+  return !Array.isArray(request.attestations) || request.attestations.length === 0;
+}
+function noAttestationResult() {
+  return {
+    approved: false,
+    errors: [{ code: "MALFORMED_ATTESTATION", message: "No attestation supplied \u2014 nothing to verify" }]
+  };
+}
 async function verifyV3(request, profile, publicKeyHex, now, executionLog, errors) {
+  if (noAttestationSupplied(request)) return noAttestationResult();
   let expectedFrameHash;
   try {
     expectedFrameHash = computeFrameHash(request.frame, profile);
@@ -588,6 +633,7 @@ async function verifyV3(request, profile, publicKeyHex, now, executionLog, error
   return { approved: true };
 }
 async function verifyV4(request, profile, publicKeyHex, now, executionLog) {
+  if (noAttestationSupplied(request)) return noAttestationResult();
   const errors = [];
   const bounds = request.frame;
   const context = request.context;
@@ -740,6 +786,14 @@ function boundGovernsAction(fieldName, fieldDef, bt, actionType) {
   const matches = prefix === actionType || prefix.startsWith("transaction");
   return !namedForAnAction || matches;
 }
+function boundActionTypes(fieldName, fieldDef) {
+  if (fieldDef.appliesTo) return fieldDef.appliesTo;
+  const bt = fieldDef.boundType;
+  if (!bt || bt.kind !== "cumulative_count") return void 0;
+  const prefix = fieldName.replace(/_(?:daily|monthly|weekly)_max$/, "");
+  if (prefix === fieldName || prefix.startsWith("transaction")) return void 0;
+  return [prefix];
+}
 function checkBoundsV4(request, profile, executionLog, now) {
   const errors = [];
   if (!profile.boundsSchema) return errors;
@@ -800,7 +854,14 @@ function checkBoundsV4(request, profile, executionLog, now) {
           break;
         }
         if (!executionLog) break;
-        const runningTotal = executionLog.sumByWindow(profileId, path, bt.of, bt.window, now);
+        const runningTotal = executionLog.sumByWindow(
+          profileId,
+          path,
+          bt.of,
+          bt.window,
+          now,
+          boundActionTypes(fieldName, fieldDef)
+        );
         const currentRaw = request.execution[bt.of];
         const current = typeof currentRaw === "number" ? currentRaw : currentRaw !== void 0 ? Number(currentRaw) : 0;
         const total = runningTotal + current;
@@ -827,7 +888,14 @@ function checkBoundsV4(request, profile, executionLog, now) {
           break;
         }
         if (!executionLog) break;
-        const runningCount = executionLog.sumByWindow(profileId, path, "_count", bt.window, now);
+        const runningCount = executionLog.sumByWindow(
+          profileId,
+          path,
+          "_count",
+          bt.window,
+          now,
+          boundActionTypes(fieldName, fieldDef)
+        );
         const total = runningCount + 1;
         if (total > boundValue) {
           errors.push({
@@ -1156,11 +1224,13 @@ async function verifyReceiptSignature(receipt, publicKeyHex) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CanonicalValueError,
   ContentBindingError,
   MandateError,
   approvalSigningBytes,
   attestationId,
   bindingAppliesTo,
+  boundActionTypes,
   buildMandateProjection,
   canonicalBounds,
   canonicalContext,

package/dist/index.mjs

@@ -287,15 +287,51 @@ function validateContextParams(params, profile) {
   }
   return { valid: errors.length === 0, errors };
 }
+var CanonicalValueError = class extends Error {
+  code;
+  field;
+  constructor(code, field, message) {
+    super(message);
+    this.name = "CanonicalValueError";
+    this.code = code;
+    this.field = field;
+  }
+};
+function percentEncodeCanonicalValue(raw) {
+  const bytes = new TextEncoder().encode(raw);
+  let out = "";
+  for (const b of bytes) {
+    if (b === 61 || b === 37 || b < 32 || b > 126) {
+      out += "%" + b.toString(16).toUpperCase().padStart(2, "0");
+    } else {
+      out += String.fromCharCode(b);
+    }
+  }
+  return out;
+}
+function canonicalRecords(params, keyOrder, code) {
+  const lines = [];
+  for (const key of keyOrder) {
+    const value = params[key];
+    if (value === void 0 || value === null) continue;
+    const raw = String(value);
+    if (raw.includes("\n") || raw.includes("\r")) {
+      throw new CanonicalValueError(
+        code,
+        key,
+        `Value for "${key}" contains a raw newline or carriage return. Refusing: a hash over stripped or normalized input would not represent what was authorized.`
+      );
+    }
+    lines.push(`${key}=${percentEncodeCanonicalValue(raw)}`);
+  }
+  return lines.join("\n");
+}
 function canonicalBounds(params, profile) {
   const validation = validateBoundsParams(params, profile);
   if (!validation.valid) {
     throw new Error(`Invalid bounds parameters: ${validation.errors.join("; ")}`);
   }
-  const lines = profile.boundsSchema.keyOrder.map(
-    (key) => `${key}=${String(params[key])}`
-  );
-  return lines.join("\n");
+  return canonicalRecords(params, profile.boundsSchema.keyOrder, "BOUNDS_INVALID_VALUE");
 }
 function canonicalContext(params, profile) {
   if (!profile.contextSchema || Object.keys(profile.contextSchema.fields).length === 0) {
@@ -305,10 +341,7 @@ function canonicalContext(params, profile) {
   if (!validation.valid) {
     throw new Error(`Invalid context parameters: ${validation.errors.join("; ")}`);
   }
-  const lines = profile.contextSchema.keyOrder.map(
-    (key) => `${key}=${String(params[key])}`
-  );
-  return lines.join("\n");
+  return canonicalRecords(params, profile.contextSchema.keyOrder, "CONTEXT_INVALID_VALUE");
 }
 function computeBoundsHash(params, profile) {
   const canonical = canonicalBounds(params, profile);
@@ -438,7 +471,17 @@ async function verify(request, publicKeyHex, now = Math.floor(Date.now() / 1e3),
     return verifyV3(request, profile, publicKeyHex, now, executionLog, errors);
   }
 }
+function noAttestationSupplied(request) {
+  return !Array.isArray(request.attestations) || request.attestations.length === 0;
+}
+function noAttestationResult() {
+  return {
+    approved: false,
+    errors: [{ code: "MALFORMED_ATTESTATION", message: "No attestation supplied \u2014 nothing to verify" }]
+  };
+}
 async function verifyV3(request, profile, publicKeyHex, now, executionLog, errors) {
+  if (noAttestationSupplied(request)) return noAttestationResult();
   let expectedFrameHash;
   try {
     expectedFrameHash = computeFrameHash(request.frame, profile);
@@ -499,6 +542,7 @@ async function verifyV3(request, profile, publicKeyHex, now, executionLog, error
   return { approved: true };
 }
 async function verifyV4(request, profile, publicKeyHex, now, executionLog) {
+  if (noAttestationSupplied(request)) return noAttestationResult();
   const errors = [];
   const bounds = request.frame;
   const context = request.context;
@@ -651,6 +695,14 @@ function boundGovernsAction(fieldName, fieldDef, bt, actionType) {
   const matches = prefix === actionType || prefix.startsWith("transaction");
   return !namedForAnAction || matches;
 }
+function boundActionTypes(fieldName, fieldDef) {
+  if (fieldDef.appliesTo) return fieldDef.appliesTo;
+  const bt = fieldDef.boundType;
+  if (!bt || bt.kind !== "cumulative_count") return void 0;
+  const prefix = fieldName.replace(/_(?:daily|monthly|weekly)_max$/, "");
+  if (prefix === fieldName || prefix.startsWith("transaction")) return void 0;
+  return [prefix];
+}
 function checkBoundsV4(request, profile, executionLog, now) {
   const errors = [];
   if (!profile.boundsSchema) return errors;
@@ -711,7 +763,14 @@ function checkBoundsV4(request, profile, executionLog, now) {
           break;
         }
         if (!executionLog) break;
-        const runningTotal = executionLog.sumByWindow(profileId, path, bt.of, bt.window, now);
+        const runningTotal = executionLog.sumByWindow(
+          profileId,
+          path,
+          bt.of,
+          bt.window,
+          now,
+          boundActionTypes(fieldName, fieldDef)
+        );
         const currentRaw = request.execution[bt.of];
         const current = typeof currentRaw === "number" ? currentRaw : currentRaw !== void 0 ? Number(currentRaw) : 0;
         const total = runningTotal + current;
@@ -738,7 +797,14 @@ function checkBoundsV4(request, profile, executionLog, now) {
           break;
         }
         if (!executionLog) break;
-        const runningCount = executionLog.sumByWindow(profileId, path, "_count", bt.window, now);
+        const runningCount = executionLog.sumByWindow(
+          profileId,
+          path,
+          "_count",
+          bt.window,
+          now,
+          boundActionTypes(fieldName, fieldDef)
+        );
         const total = runningCount + 1;
         if (total > boundValue) {
           errors.push({
@@ -1066,11 +1132,13 @@ async function verifyReceiptSignature(receipt, publicKeyHex) {
   }
 }
 export {
+  CanonicalValueError,
   ContentBindingError,
   MandateError,
   approvalSigningBytes,
   attestationId,
   bindingAppliesTo,
+  boundActionTypes,
   buildMandateProjection,
   canonicalBounds,
   canonicalContext,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanagencyp/hap-core",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Core types, cryptographic primitives, and verification logic for the Human Agency Protocol",
   "license": "MIT",
   "repository": {
@@ -24,6 +24,7 @@
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
     "prepublishOnly": "pnpm build",

package/src/frame.ts

@@ -2,8 +2,11 @@
  * Frame Canonicalization for Agent Profiles
  *
  * Agent profiles support mixed-type fields (strings and numbers).
- * Canonical form: all values are converted to strings via String(value).
- * Keys are ordered according to the profile's keyOrder.
+ * Canonical form: `key=value` records joined with LF, keys in the profile's
+ * keyOrder. Values are stringified with String(value) — the shortest
+ * round-trippable form for numbers — then percent-encoded per protocol.md
+ * (`=`, `%`, and every byte outside printable ASCII); a value carrying a raw
+ * LF/CR is refused, never normalized. See `canonicalRecords` below.
  *
  * v0.3: frameSchema
  * v0.4: boundsSchema + contextSchema (separate hashes)
@@ -176,11 +179,115 @@ export function validateContextParams(
   return { valid: errors.length === 0, errors };
 }
 
+// ─── Value Encoding (normative, v0.5+) ───────────────────────────────────────
+
+/**
+ * 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
+ * straight onto the wire without string-matching a message.
+ *
+ * protocol.md → *Bounds & Scope Canonicalization* → Value encoding:
+ *   "Values MUST NOT contain raw newline (\n) or carriage-return (\r)
+ *    characters. Implementations MUST reject input containing them; silent
+ *    stripping or normalization is a violation because it produces a hash that
+ *    does not faithfully represent the input."
+ */
+export class CanonicalValueError extends Error {
+  readonly code: 'BOUNDS_INVALID_VALUE' | 'CONTEXT_INVALID_VALUE';
+  readonly field: string;
+
+  constructor(code: 'BOUNDS_INVALID_VALUE' | 'CONTEXT_INVALID_VALUE', field: string, message: string) {
+    super(message);
+    this.name = 'CanonicalValueError';
+    this.code = code;
+    this.field = field;
+  }
+}
+
+/**
+ * Percent-encode a value per protocol.md → *Value encoding*.
+ *
+ * Encoded, over the value's UTF-8 bytes, as `%` + two UPPERCASE hex digits:
+ *   - `=` (0x3D) — otherwise it would be read as the key/value separator
+ *   - `%` (0x25) — so the encoding is self-inverse
+ *   - every byte outside printable ASCII 0x20–0x7E
+ *
+ * LF and CR are deliberately NOT in this list: they are refused upstream, so
+ * encoding them is unreachable (v0.7 removed the spec's contradiction here).
+ *
+ * This runs at canonicalization time only. Stored values keep the human's
+ * original bytes.
+ */
+function percentEncodeCanonicalValue(raw: string): string {
+  const bytes = new TextEncoder().encode(raw);
+  let out = '';
+  for (const b of bytes) {
+    if (b === 0x3d || b === 0x25 || b < 0x20 || b > 0x7e) {
+      out += '%' + b.toString(16).toUpperCase().padStart(2, '0');
+    } else {
+      out += String.fromCharCode(b);
+    }
+  }
+  return out;
+}
+
+/**
+ * The one place `key=value` records are built for bounds and context.
+ *
+ * Rules applied here (all normative, protocol.md → *Bounds & Scope
+ * Canonicalization*):
+ *   - keys in the schema's keyOrder, never alphabetical
+ *   - a value carrying a raw LF/CR is REFUSED (never stripped or encoded)
+ *   - `=`, `%`, and any byte outside 0x20–0x7E are percent-encoded (UPPERCASE)
+ *   - numbers use JS `String()`, which is the shortest round-trippable form
+ *     (`String(20.0)` === "20")
+ *   - a key with no value is OMITTED entirely — it emits no record
+ *
+ * On the omission rule: required keys are guaranteed present by the caller's
+ * validation (`validateBoundsParams` / `validateContextParams` reject a missing
+ * required field), so "explicit inclusion of all required keys" still holds.
+ * What remains are *optional* keys the human never set. Rendering those as the
+ * literal string "undefined" — the pre-fix behaviour — hashed a JavaScript
+ * artifact that no other language would produce and that collides with a real
+ * value of "undefined". Omitting them (rather than emitting `key=`) also keeps
+ * "the human set no limit" distinct from "the human set an empty value", and
+ * matches this package's JSON canonicalization, which drops undefined-valued
+ * properties.
+ */
+function canonicalRecords(
+  params: Record<string, string | number | undefined>,
+  keyOrder: string[],
+  code: 'BOUNDS_INVALID_VALUE' | 'CONTEXT_INVALID_VALUE',
+): string {
+  const lines: string[] = [];
+
+  for (const key of keyOrder) {
+    const value = params[key];
+    if (value === undefined || value === null) continue;
+
+    const raw = String(value);
+    if (raw.includes('\n') || raw.includes('\r')) {
+      throw new CanonicalValueError(
+        code,
+        key,
+        `Value for "${key}" contains a raw newline or carriage return. ` +
+          'Refusing: a hash over stripped or normalized input would not represent what was authorized.',
+      );
+    }
+
+    lines.push(`${key}=${percentEncodeCanonicalValue(raw)}`);
+  }
+
+  return lines.join('\n');
+}
+
 /**
  * Builds the canonical bounds string from parameters.
- * All values are converted to strings. Keys are ordered per profile's boundsSchema.keyOrder.
+ * Keys are ordered per profile's boundsSchema.keyOrder; values are encoded per
+ * protocol.md → *Value encoding* (see `canonicalRecords`).
  *
  * @throws Error if any field fails validation
+ * @throws CanonicalValueError (code BOUNDS_INVALID_VALUE) if a value carries a raw LF/CR
  */
 export function canonicalBounds(params: AgentBoundsParams, profile: AgentProfile): string {
   const validation = validateBoundsParams(params, profile);
@@ -188,19 +295,17 @@ export function canonicalBounds(params: AgentBoundsParams, profile: AgentProfile
     throw new Error(`Invalid bounds parameters: ${validation.errors.join('; ')}`);
   }
 
-  const lines = profile.boundsSchema!.keyOrder.map(
-    (key) => `${key}=${String(params[key])}`
-  );
-
-  return lines.join('\n');
+  return canonicalRecords(params, profile.boundsSchema!.keyOrder, 'BOUNDS_INVALID_VALUE');
 }
 
 /**
  * Builds the canonical context string from parameters.
- * All values are converted to strings. Keys are ordered per profile's contextSchema.keyOrder.
+ * Keys are ordered per profile's contextSchema.keyOrder; values are encoded per
+ * protocol.md → *Value encoding* (see `canonicalRecords`).
  * For empty context (no contextSchema or no fields), returns "".
  *
  * @throws Error if any field fails validation
+ * @throws CanonicalValueError (code CONTEXT_INVALID_VALUE) if a value carries a raw LF/CR
  */
 export function canonicalContext(params: AgentContextParams, profile: AgentProfile): string {
   // No contextSchema or no fields → empty context
@@ -213,11 +318,7 @@ export function canonicalContext(params: AgentContextParams, profile: AgentProfi
     throw new Error(`Invalid context parameters: ${validation.errors.join('; ')}`);
   }
 
-  const lines = profile.contextSchema.keyOrder.map(
-    (key) => `${key}=${String(params[key])}`
-  );
-
-  return lines.join('\n');
+  return canonicalRecords(params, profile.contextSchema.keyOrder, 'CONTEXT_INVALID_VALUE');
 }
 
 /**

package/src/gatekeeper.ts

@@ -86,6 +86,28 @@ export async function verify(
   }
 }
 
+/**
+ * Fail closed when there is nothing to verify.
+ *
+ * The attestation loop below is a `for` over `request.attestations`. With an
+ * empty (or missing) array it runs zero times, pushes zero errors, and control
+ * falls through to the bounds check — which happily approves a call whose
+ * signature, bounds_hash, and TTL were never checked. "No errors" is not the
+ * same as "verified"; an absent attestation is the one case where silence must
+ * read as refusal.
+ */
+function noAttestationSupplied(request: GatekeeperRequest): boolean {
+  return !Array.isArray(request.attestations) || request.attestations.length === 0;
+}
+
+/** Built fresh per call so a caller cannot mutate a shared error array. */
+function noAttestationResult(): GatekeeperResult {
+  return {
+    approved: false,
+    errors: [{ code: 'MALFORMED_ATTESTATION', message: 'No attestation supplied — nothing to verify' }],
+  };
+}
+
 // ─── v0.3 Verification ────────────────────────────────────────────────────────
 
 async function verifyV3(
@@ -96,6 +118,8 @@ async function verifyV3(
   executionLog: ExecutionLogQuery | undefined,
   errors: GatekeeperError[],
 ): Promise<GatekeeperResult> {
+  if (noAttestationSupplied(request)) return noAttestationResult();
+
   let expectedFrameHash: string;
   try {
     expectedFrameHash = computeFrameHash(request.frame, profile);
@@ -179,6 +203,8 @@ async function verifyV4(
   now: number,
   executionLog: ExecutionLogQuery | undefined,
 ): Promise<GatekeeperResult> {
+  if (noAttestationSupplied(request)) return noAttestationResult();
+
   const errors: GatekeeperError[] = [];
 
   // In v0.4 the `frame` param carries bounds; `context` carries context params
@@ -443,6 +469,36 @@ function boundGovernsAction(
   return !namedForAnAction || matches;
 }
 
+/**
+ * Which action types' executions count toward this cumulative bound's running
+ * total. `undefined` means all of them.
+ *
+ * `boundGovernsAction` decides whether a bound applies to the current call; this
+ * decides what the bound's total is made of. Both are needed: selecting the right
+ * bound and then feeding it the profile's combined total is still wrong — sales'
+ * "orders per day" was checked only on orders, but counted every quote and send.
+ * Consumption is partitioned by action type (*Cumulative Tracking* rule 4), as
+ * the Authority Server already does.
+ *
+ * Same answer, same order of preference as `boundGovernsAction`: the declared
+ * `appliesTo`; else, for a count bound named for an action (`delete_daily_max`),
+ * that action; else every action type. Exported so display surfaces report the
+ * same totals the gate enforces.
+ */
+export function boundActionTypes(
+  fieldName: string,
+  fieldDef: ProfileBoundsField,
+): readonly string[] | undefined {
+  if (fieldDef.appliesTo) return fieldDef.appliesTo;
+
+  const bt = fieldDef.boundType;
+  if (!bt || bt.kind !== 'cumulative_count') return undefined;
+
+  const prefix = fieldName.replace(/_(?:daily|monthly|weekly)_max$/, '');
+  if (prefix === fieldName || prefix.startsWith('transaction')) return undefined;
+  return [prefix];
+}
+
 function checkBoundsV4(
   request: GatekeeperRequest,
   profile: AgentProfile,
@@ -526,7 +582,9 @@ function checkBoundsV4(
         }
         if (!executionLog) break;
 
-        const runningTotal = executionLog.sumByWindow(profileId, path, bt.of, bt.window, now);
+        const runningTotal = executionLog.sumByWindow(
+          profileId, path, bt.of, bt.window, now, boundActionTypes(fieldName, fieldDef),
+        );
         const currentRaw = request.execution[bt.of];
         const current = typeof currentRaw === 'number'
           ? currentRaw
@@ -558,7 +616,9 @@ function checkBoundsV4(
         }
         if (!executionLog) break;
 
-        const runningCount = executionLog.sumByWindow(profileId, path, '_count', bt.window, now);
+        const runningCount = executionLog.sumByWindow(
+          profileId, path, '_count', bt.window, now, boundActionTypes(fieldName, fieldDef),
+        );
         const total = runningCount + 1;
 
         if (total > boundValue) {

package/src/types.ts

@@ -636,7 +636,27 @@ export interface ExecutionLogQuery {
    * Sum a field's values within a time window for a given profile.
    * Use field="_count" to count executions instead of summing a field.
    */
-  sumByWindow(profileId: string, path: string, field: string, window: CumulativeWindow, now?: number): number;
+  sumByWindow(
+    profileId: string,
+    path: string,
+    field: string,
+    window: CumulativeWindow,
+    now?: number,
+    /**
+     * Only count executions whose `execution.action_type` is one of these.
+     * Omitted → every execution counts (a bound that governs all action types).
+     *
+     * Consumption is partitioned by action type (*Cumulative Tracking* rule 4):
+     * a bound counts only the action types it governs. Without the filter a
+     * profile with several action types feeds every bound the combined total —
+     * sales' "orders per day" counted quotes and sends too, and its daily order
+     * value summed quote values. Use {@link boundActionTypes} to derive it.
+     *
+     * Implementations SHOULD count an entry that carries no `action_type`
+     * against every filter: an unknown action is not evidence of headroom.
+     */
+    actionTypes?: readonly string[],
+  ): number;
 }
 
 // ─── Frame Types ─────────────────────────────────────────────────────────────
@@ -712,7 +732,13 @@ export interface GatekeeperError {
     | 'MANDATE_SIGNATURE_REQUIRED'
     | 'MANDATE_SIGNATURE_INVALID'
     | 'APPROVAL_SIGNATURE_REQUIRED'
-    | 'APPROVAL_SIGNATURE_INVALID';
+    | 'APPROVAL_SIGNATURE_INVALID'
+    // Canonicalization refusals (protocol.md → Bounds & Scope Canonicalization
+    // → Value encoding). Raised when a value cannot be canonicalized at all —
+    // a raw LF/CR, or a profile `constraint.pattern` violation. Distinct from
+    // BOUNDS_MISMATCH / CONTEXT_MISMATCH, which mean the hashes disagree.
+    | 'BOUNDS_INVALID_VALUE'
+    | 'CONTEXT_INVALID_VALUE';
   field?: string;
   message: string;
   bound?: string | number;