@humanagencyp/hap-core 0.10.0 → 0.11.0

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
@@ -503,6 +522,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).
@@ -610,7 +639,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).
@@ -969,6 +1012,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
@@ -1126,6 +1188,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.
@@ -1322,4 +1401,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, 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, validateBoundsRequiredFor, 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
@@ -503,6 +522,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).
@@ -610,7 +639,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).
@@ -969,6 +1012,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
@@ -1126,6 +1188,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.
@@ -1322,4 +1401,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, 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, validateBoundsRequiredFor, validateContextParams, validateFrameParams, validateSubject, verify, verifyApproval, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash, verifyOwnerMandate, verifyOwnerMandates, verifyReceiptSignature };

package/dist/index.js

@@ -36,6 +36,7 @@ __export(index_exports, {
   approvalSigningBytes: () => approvalSigningBytes,
   attestationId: () => attestationId,
   bindingAppliesTo: () => bindingAppliesTo,
+  boundActionTypes: () => boundActionTypes,
   buildMandateProjection: () => buildMandateProjection,
   canonicalBounds: () => canonicalBounds,
   canonicalContext: () => canonicalContext,
@@ -71,6 +72,7 @@ __export(index_exports, {
   signApproval: () => signApproval,
   signMandateProjection: () => signMandateProjection,
   validateBoundsParams: () => validateBoundsParams,
+  validateBoundsRequiredFor: () => validateBoundsRequiredFor,
   validateContextParams: () => validateContextParams,
   validateFrameParams: () => validateFrameParams,
   validateSubject: () => validateSubject,
@@ -377,6 +379,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;
@@ -785,6 +819,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;
@@ -811,6 +853,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({
@@ -845,7 +903,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;
@@ -872,7 +937,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({
@@ -1207,6 +1279,7 @@ async function verifyReceiptSignature(receipt, publicKeyHex) {
   approvalSigningBytes,
   attestationId,
   bindingAppliesTo,
+  boundActionTypes,
   buildMandateProjection,
   canonicalBounds,
   canonicalContext,
@@ -1242,6 +1315,7 @@ async function verifyReceiptSignature(receipt, publicKeyHex) {
   signApproval,
   signMandateProjection,
   validateBoundsParams,
+  validateBoundsRequiredFor,
   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;
@@ -695,6 +727,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;
@@ -721,6 +761,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({
@@ -755,7 +811,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;
@@ -782,7 +845,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({
@@ -1116,6 +1186,7 @@ export {
   approvalSigningBytes,
   attestationId,
   bindingAppliesTo,
+  boundActionTypes,
   buildMandateProjection,
   canonicalBounds,
   canonicalContext,
@@ -1151,6 +1222,7 @@ export {
   signApproval,
   signMandateProjection,
   validateBoundsParams,
+  validateBoundsRequiredFor,
   validateContextParams,
   validateFrameParams,
   validateSubject,

package/package.json

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

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

@@ -469,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,
@@ -516,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({
@@ -552,7 +619,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
@@ -584,7 +653,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

@@ -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
@@ -520,6 +538,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[];
   };
 
   /**
@@ -636,7 +664,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 ─────────────────────────────────────────────────────────────