@wowok/agent-mcp 3.1.3 → 3.1.4

package/dist/knowledge/baselines/rules/payment.json

@@ -0,0 +1,205 @@
+{
+  "comment": "Payment rule pack (R-PAYMENT) — declarative form of the retired in-code Payment risk rules. Facts are produced by the kernel extractor (payment-risk.ts, bound to the on-chain recipient cap); rules only reference fact names. Note the pack order carries the old check() semantics: R-PAYMENT-05 sits LAST in the rules array because the retired check appended its always-on variant guidance after every other rule. Levels/wording can be retuned per rule and rules can be disabled (enabled=false, trace left) via the judgment document — factory rules can never be deleted or invented here.",
+  "facts": {
+    "recipient_count": "Recipient count for the new Payment.",
+    "recipient_count_at_limit": "recipient_count has reached MAX_RECIPIENT_COUNT (chain-limit comparison sunk into the extractor).",
+    "uses_unsafe_unwrap": "The caller uses the unchecked unwrap (no Payment match check) instead of the type-checked variant.",
+    "expects_mutation": "The caller relies on post-creation modification (impossible — Payment is frozen at create).",
+    "coin_field_lint_reviewed": "Whether the CoinWrapper coin_field lint suppression has been intentionally reviewed (false keeps the review reminder audible).",
+    "expects_user_recipient_registered": "The caller expects every recipient to be registered via the object-linker tx index (only object-address recipients are).",
+    "uses_signer_for_provenance": "The caller relies on Payment.signer for provenance (informational only, not authorization).",
+    "uses_scene_binding": "The Payment uses the for_object + for_guard + index scene binding (exception branch anti-reuse).",
+    "scene_binding_missing": "Rendered list of missing scene-binding legs ('for_object not set (Order binding missing)', etc.), ', '-joined — empty when the binding is complete.",
+    "scene_binding_missing_count": "Number of missing scene-binding legs (0 when complete).",
+    "payment_info_variant_display": "Rendered PaymentInfo constructor variant name, 'unknown' when the context carries none.",
+    "max_recipient_count": "KERNEL CONSTANT — recipients per Payment cap (MAX_RECIPIENT_COUNT).",
+    "always_true": "Extractor sentinel — unconditionally true; marks the always-on guidance rule (R-PAYMENT-05)."
+  },
+  "rules": [
+    {
+      "rule_id": "R-PAYMENT-01",
+      "dimension": "permission",
+      "trigger": "caller uses the unchecked unwrap",
+      "cases": [
+        {
+          "when": { "field": "uses_unsafe_unwrap", "op": "eq", "value": true },
+          "level": "high",
+          "title": "unwrap() performs no Payment match check — may unwrap wrong CoinWrapper",
+          "description": "unwrap(wrapper, ctx) returns (Coin, payment_address) without verifying that wrapper.payment matches any expected Payment. Callers who use the unchecked unwrap can release a CoinWrapper that was minted for a different Payment, leading to fund loss or accounting corruption. The type-checked unwrap variant exists specifically to enforce the match.",
+          "scenario": "Caller uses unwrap on a wrapper from a different Payment; funds are released anyway",
+          "mitigation": "SDK should force callers to use the type-checked unwrap and deprecate the unchecked variant. The only safe use of unwrap is when the caller has already verified the match off-chain.",
+          "evidence": "uses_unsafe_unwrap=true (no Payment match check)",
+          "stakeholders": ["signer", "recipient"],
+          "exposure": {
+            "loss_parties": [
+              { "role": "buyer", "basis": "Compensation escrowed in a wrapper can be released outside its intended payment flow — the match check is the only pin tying the wrapper to the Payment it was minted for." },
+              { "role": "merchant", "basis": "Order-payment wrappers released through the unchecked unwrap land outside the intended distribution flow — accounting corrupts silently." }
+            ],
+            "gain_paths": [
+              {
+                "role": "neutral",
+                "path": "A caller extracts a wrapper minted for a different Payment and walks away with the released coin — no on-chain check ties the release back to the expected Payment.",
+                "viability": "viable",
+                "gate": "The unchecked unwrap performs no Payment match verification; the type-checked variant exists precisely to enforce it."
+              }
+            ]
+          }
+        }
+      ]
+    },
+    {
+      "rule_id": "R-PAYMENT-02",
+      "dimension": "structural",
+      "trigger": "recipient count reaches MAX_RECIPIENT_COUNT",
+      "cases": [
+        {
+          "when": { "field": "recipient_count_at_limit", "op": "eq", "value": true },
+          "level": "medium",
+          "title": "MAX_RECIPIENT_COUNT=${max_recipient_count} permissive — gas and confirmation cost",
+          "description": "A single Payment may carry up to MAX_RECIPIENT_COUNT=${max_recipient_count} recipients. The limit aborts with ERECIPIENT_COUNT_EXCEEDED (1) only at the boundary. 200 recipients in one transaction inflates gas, slows finalization, and complicates retry on partial failure.",
+          "scenario": "Caller submits a Payment with 200 recipients; transaction is heavy and slow",
+          "mitigation": "Business layer should self-limit recipient count (e.g. ≤50). For mass payouts, split across multiple Payment objects in separate transactions.",
+          "evidence": "recipient_count=${recipient_count}, limit=${max_recipient_count}",
+          "stakeholders": ["signer", "recipient"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-PAYMENT-03",
+      "dimension": "lifecycle",
+      "trigger": "caller relies on post-creation modification (Payment is frozen)",
+      "cases": [
+        {
+          "when": { "field": "expects_mutation", "op": "eq", "value": true },
+          "level": "low",
+          "title": "Payment is immutable after create — errors cannot be corrected",
+          "description": "create() calls transfer::freeze_object(payment). All fields (amount, time, info, from_object, signer, record) are permanently fixed. There is no update, refund, or void API on the Payment object itself — correction requires a new Payment (and off-chain reconciliation).",
+          "scenario": "Signer mistypes a recipient address; the Payment cannot be edited post-create",
+          "mitigation": "Verify all fields before calling create. For refunds, create a new Payment in the opposite direction. Off-chain systems should treat Payment as an immutable receipt.",
+          "evidence": "expects_mutation=true (Payment is frozen at create)",
+          "stakeholders": ["signer", "consumer"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-PAYMENT-04",
+      "dimension": "structural",
+      "trigger": "coin_field lint suppression not reviewed",
+      "cases": [
+        {
+          "when": { "field": "coin_field_lint_reviewed", "op": "falsy" },
+          "level": "medium",
+          "title": "CoinWrapper suppresses coin_field lint — Balance<T> stored in a struct field",
+          "description": "CoinWrapper<phantom T> stores Balance<T> directly in a struct field and uses #[allow(lint(coin_field))] to suppress the Wow lint. The lint normally warns against storing Balance in arbitrary structs because of object lifecycle concerns. The suppression is intentional but should be reviewed whenever the Wow framework updates its coin_field rules.",
+          "scenario": "Wow framework tightens coin_field lint semantics; CoinWrapper becomes non-compliant",
+          "mitigation": "Review the coin_field suppression on each Wow upgrade. Confirm that Balance<T> ownership transfer in the unchecked and type-checked unwrap paths is correct.",
+          "evidence": "coin_field_lint_reviewed=false (needs review)",
+          "stakeholders": ["system"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-PAYMENT-06",
+      "dimension": "cross_object",
+      "trigger": "caller expects user-address recipients in the object-linker tx registration",
+      "cases": [
+        {
+          "when": { "field": "expects_user_recipient_registered", "op": "eq", "value": true },
+          "level": "medium",
+          "title": "object-linker tx registration filters recipients by the object-address check — user addresses skipped",
+          "description": "create() iterates recipients and registers an object-linker affiliation only for addresses that pass the on-chain object-address check. User addresses (EOAs) are not registered in the object-linker tx index. Callers who expect every recipient to appear in object-linker tx queries will miss EOA recipients.",
+          "scenario": "Caller queries object-linker tx for all Payment recipients; EOA recipients are missing",
+          "mitigation": "Document that the affiliation link is registered only for object-address recipients. Off-chain systems should track EOA recipients via the NewPaymentEvent record, not via object-linker tx.",
+          "evidence": "expects_user_recipient_registered=true (EOAs are skipped)",
+          "stakeholders": ["signer", "consumer"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-PAYMENT-07",
+      "dimension": "semantic",
+      "trigger": "caller relies on Payment.signer for provenance",
+      "cases": [
+        {
+          "when": { "field": "uses_signer_for_provenance", "op": "eq", "value": true },
+          "level": "low",
+          "title": "Payment.signer records payer — useful for provenance but not authorization",
+          "description": "Payment.signer is set to ctx.sender() at creation. It can be read back from the Payment object for provenance (e.g. 'who paid for this order'). It is purely informational — it does NOT authorize any later operation. Consumers must not treat signer as a permission grant.",
+          "scenario": "Consumer treats Payment.signer as authorizing a refund; signer is just provenance",
+          "mitigation": "Use Payment.signer only for audit/provenance. Authorization must come from the referencing object's own Permission, not from Payment.signer.",
+          "evidence": "uses_signer_for_provenance=true (informational only)",
+          "stakeholders": ["consumer"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-PAYMENT-08",
+      "dimension": "semantic",
+      "trigger": "scene binding used but a binding leg (for_object/for_guard/index) is missing",
+      "cases": [
+        {
+          "when": { "all": [
+            { "field": "uses_scene_binding", "op": "eq", "value": true },
+            { "field": "scene_binding_missing_count", "op": "gte", "value": 1 }
+          ] },
+          "level": "medium",
+          "title": "Payment scene binding (for_object + for_guard + index) — anti-reuse for exception branches",
+          "description": "PaymentInfo supports for_object (binds to specific Order), for_guard (binds to specific Guard), and index (binds to specific Progress step). When all three are set via payment_info_with_guard, the Payment is scene-bound: it can ONLY be used in the specific order + guard + progress context. This is the anti-reuse design for exception branch compensation (e.g., delivery delay >30min triggers auto-compensation). Payment is immutable (freeze_object) — binding cannot be altered. VERIFIER-EVIDENCE DESIGN: customer submits Payment, Guard verifies binding fields match current context.",
+          "scenario": "Treasury creates compensation Payment with PaymentInfo(for_object=order, for_guard=exception_guard, index=current_progress) for delivery delay",
+          "mitigation": "Use payment_info_with_guard for all exception branch Payments. Ensure for_object, for_guard, and index all match the intended context. Use tpl_payment_exception_compensation (guard-templates.ts) as design template.",
+          "evidence": "incomplete scene binding: ${scene_binding_missing}",
+          "stakeholders": ["signer", "recipient", "consumer"],
+          "exposure": {
+            "loss_parties": [
+              { "role": "merchant", "basis": "Exception-branch compensation minted for one specific order context can be redeemed in another — the missing binding legs are the only pin against reuse, and the funds come out of the merchant's compensation pocket." }
+            ],
+            "gain_paths": [
+              {
+                "role": "neutral",
+                "path": "A claimant redeploys the weakly-bound Payment in a different order/guard context than the one it was minted for.",
+                "viability": "conditional",
+                "gate": "Executes only if the consuming Guard's verification accepts the incomplete binding — audit the consumer template to confirm or block the reuse."
+              }
+            ]
+          }
+        }
+      ]
+    },
+    {
+      "rule_id": "R-PAYMENT-09",
+      "dimension": "semantic",
+      "trigger": "scene binding used without the full payment_info_with_guard variant",
+      "cases": [
+        {
+          "when": { "all": [
+            { "field": "uses_scene_binding", "op": "eq", "value": true },
+            { "field": "payment_info_variant_display", "op": "neq", "value": "payment_info_with_guard" }
+          ] },
+          "level": "low",
+          "title": "PaymentInfo variant selection — use payment_info_with_guard for exception branches",
+          "description": "PaymentInfo has 4 constructor variants: payment_info (for_object+remark+index, no for_guard), payment_info_basic (remark+index, no for_object/for_guard), payment_info_with_guard (for_object+for_guard+remark+index — FULL binding), payment_info_basic_guarded (for_guard+remark+index, no for_object). For exception branch compensation, ALWAYS use payment_info_with_guard to get full scene binding. Using payment_info (without for_guard) or payment_info_basic (without for_object) weakens anti-reuse protection.",
+          "scenario": "Caller uses payment_info instead of payment_info_with_guard for exception compensation; for_guard is lost",
+          "mitigation": "For exception branch Payments: always use payment_info_with_guard(for_object, for_guard, remark, index). For simple Payments without scene binding: payment_info or payment_info_basic is fine. SDK should auto-select the variant based on which fields are provided.",
+          "evidence": "uses_scene_binding=true but variant=${payment_info_variant_display} (should be payment_info_with_guard)",
+          "stakeholders": ["signer", "consumer"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-PAYMENT-05",
+      "dimension": "semantic",
+      "trigger": "always — PaymentInfo variant guidance applies to every construction (the retired check appended it last)",
+      "cases": [
+        {
+          "when": { "field": "always_true", "op": "eq", "value": true },
+          "level": "low",
+          "title": "PaymentInfo has 4 constructor variants — caller may pick the wrong one",
+          "description": "PaymentInfo can be built via payment_info (for_object+remark+index), payment_info_basic (remark+index, no for_object), payment_info_with_guard (for_object+for_guard+remark+index), or payment_info_basic_guarded (for_guard+remark+index, no for_object). Selecting the wrong variant leaves for_object/for_guard as None, breaking downstream lookups.",
+          "scenario": "Caller uses payment_info_basic when they meant payment_info_with_guard; for_object is lost",
+          "mitigation": "Document each variant's use case clearly. SDK should pick the variant automatically based on which optional fields the caller provides.",
+          "stakeholders": ["signer", "consumer"]
+        }
+      ]
+    }
+  ]
+}

package/dist/knowledge/baselines/rules/permission.json

@@ -0,0 +1,330 @@
+{
+  "comment": "Permission rule pack (R-P) — declarative form of the retired in-code Permission risk rules. Facts are produced by the kernel extractor (permission-risk.ts, bound to the live permission limits, the builtin-index ledger and the scene catalog); rules only reference fact names. Levels/wording can be retuned per rule and rules can be disabled (enabled=false, trace left) via the judgment document — factory rules can never be deleted or invented here.",
+  "facts": {
+    "apply": "Target object addresses of the apply operation (raw list; presence gates R-P-5-01).",
+    "builder": "New owner address of the ownership transfer operation.",
+    "um": "UM (User Manager) Contact address being set.",
+    "current_admin_count": "Number of admins already configured on the Permission object.",
+    "current_entity_count": "Number of entities already configured on the Permission object.",
+    "target_objects_types": "Host object types of the apply targets (e.g. Service, Machine, Progress).",
+    "user_defined_perm_index_start": "KERNEL CONSTANT — live USER_DEFINED_PERM_INDEX_START (custom indexes start here).",
+    "max_entity_count": "KERNEL CONSTANT — live MAX_ENTITY_COUNT limit from the published package.",
+    "max_perm_for_entity": "KERNEL CONSTANT — live MAX_PERM_FOR_ENTITY limit from the published package.",
+    "max_admin_count": "KERNEL CONSTANT — live MAX_ADMIN_COUNT limit from the published package.",
+    "table_index_number": "KERNEL — the table op's permission index when given as a number (absent for the by-entity form).",
+    "table_entity": "KERNEL — the entity address of a by-entity table op (index array form).",
+    "perm_count_for_entity": "KERNEL — number of permission indexes in a by-entity table op.",
+    "admin_op": "KERNEL — the admin operation kind (add / remove / set).",
+    "admin_address_count": "KERNEL — number of addresses in the admin operation.",
+    "admin_effective_count": "KERNEL — projected admin count after the operation (add: current + incoming; otherwise the incoming count).",
+    "admin_dispersion_count": "KERNEL — dispersion view of the admin set (set: incoming count; otherwise the current count).",
+    "entity_op": "KERNEL — the entity operation kind (swap / replace / copy / del).",
+    "entity_replace_from": "KERNEL — entity1 of a replace operation (loses all permissions).",
+    "entity_replace_to": "KERNEL — entity2 of a replace operation (the replacement).",
+    "custom_index_invalid": "KERNEL — the table op's numeric index is below USER_DEFINED_PERM_INDEX_START and is not a builtin permission.",
+    "custom_index_without_remark": "KERNEL — the table op uses a custom index (>= start) and the same call does not set a remark for it.",
+    "entity_count": "KERNEL — effective entity count (current_entity_count, defaulting to 0).",
+    "entity_count_over_limit": "KERNEL — entity_count exceeds the live MAX_ENTITY_COUNT.",
+    "perm_count_over_limit": "KERNEL — perm_count_for_entity exceeds the live MAX_PERM_FOR_ENTITY.",
+    "admin_count_over_limit": "KERNEL — admin_effective_count exceeds the live MAX_ADMIN_COUNT.",
+    "builtin_permission_name": "KERNEL — builtin constant name of the table op's index (from the permission scene ledger).",
+    "perm_scene_host_object": "KERNEL — host object type of the scene that consumes the table op's builtin index.",
+    "target_types_mismatched_count": "KERNEL — apply targets whose host object type differs from the builtin index's scene.",
+    "mismatched_targets_csv": "KERNEL — comma-space joined mismatched apply target types.",
+    "mismatched_targets_csv_nospace": "KERNEL — comma joined mismatched apply target types (compact form).",
+    "targets_include_progress": "KERNEL — whether the apply target types include Progress (post-bind mutability limit).",
+    "um_is_builder": "KERNEL — UM is set to the same address as the builder (owner self-reference heuristic).",
+    "apply_count": "KERNEL — number of apply targets (present only when apply is given).",
+    "unique_target_type_count": "KERNEL — number of distinct host object types among the apply targets.",
+    "unique_target_types_csv": "KERNEL — comma-space joined distinct apply target types.",
+    "unique_target_types_csv_nospace": "KERNEL — comma joined distinct apply target types (compact form).",
+    "treasury_external_guard_name": "KERNEL — builtin constant name when the index is a treasury external guard index (255/256).",
+    "treasury_external_guard_op": "KERNEL — 'deposit' or 'withdraw' for the matching treasury external guard index."
+  },
+  "rules": [
+    {
+      "rule_id": "R-P-1-01",
+      "dimension": "structural",
+      "trigger": "custom permission index below USER_DEFINED_PERM_INDEX_START and not builtin",
+      "cases": [
+        {
+          "when": { "field": "custom_index_invalid", "op": "eq", "value": true },
+          "level": "critical",
+          "title": "Invalid permission index (< 1000 and not builtin)",
+          "description": "Permission index ${table_index_number} is below USER_DEFINED_PERM_INDEX_START (${user_defined_perm_index_start}) and not a builtin permission. Custom indexes must be >= 1000.",
+          "scenario": "User defines a custom permission with index < 1000",
+          "mitigation": "Use index >= ${user_defined_perm_index_start} for custom permissions, or use a builtin index if applicable",
+          "evidence": "index=${table_index_number}",
+          "stakeholders": ["owner", "admin", "system"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-P-1-02",
+      "dimension": "structural",
+      "trigger": "entity count exceeds MAX_ENTITY_COUNT",
+      "cases": [
+        {
+          "when": { "field": "entity_count_over_limit", "op": "eq", "value": true },
+          "level": "high",
+          "title": "Entity count exceeds limit",
+          "description": "Permission has ${entity_count} entities, exceeds MAX_ENTITY_COUNT ${max_entity_count}",
+          "scenario": "Adding entities beyond the protocol limit",
+          "mitigation": "Split into multiple Permission objects or remove inactive entities",
+          "evidence": "entity_count=${entity_count}",
+          "stakeholders": ["owner", "admin"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-P-1-03",
+      "dimension": "structural",
+      "trigger": "per-entity permission count exceeds MAX_PERM_FOR_ENTITY",
+      "cases": [
+        {
+          "when": { "field": "perm_count_over_limit", "op": "eq", "value": true },
+          "level": "high",
+          "title": "Per-entity permission count exceeds limit",
+          "description": "Entity ${table_entity} has ${perm_count_for_entity} permissions, exceeds MAX_PERM_FOR_ENTITY ${max_perm_for_entity}",
+          "scenario": "Granting too many permissions to one entity",
+          "mitigation": "Consolidate similar permissions or split entity into multiple roles",
+          "evidence": "perm_count=${perm_count_for_entity}",
+          "stakeholders": ["entity", "admin"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-P-1-04",
+      "dimension": "structural",
+      "trigger": "projected admin count exceeds MAX_ADMIN_COUNT",
+      "cases": [
+        {
+          "when": { "field": "admin_count_over_limit", "op": "eq", "value": true },
+          "level": "high",
+          "title": "Admin count exceeds limit",
+          "description": "Admin count would be ${admin_effective_count}, exceeds MAX_ADMIN_COUNT ${max_admin_count}",
+          "scenario": "Adding too many admins",
+          "mitigation": "Remove inactive admins before adding new ones",
+          "evidence": "admin_count=${admin_effective_count}",
+          "stakeholders": ["owner", "admin"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-P-2-01",
+      "dimension": "semantic",
+      "trigger": "builtin permission index used outside its host object scene",
+      "cases": [
+        {
+          "when": { "field": "target_types_mismatched_count", "op": "gt", "value": 0 },
+          "level": "high",
+          "title": "Permission index host object mismatch",
+          "description": "Permission ${table_index_number} (${builtin_permission_name}) is for ${perm_scene_host_object}, but apply targets: ${mismatched_targets_csv}",
+          "scenario": "Using SERVICE_* index on Machine object",
+          "mitigation": "Use ${perm_scene_host_object}-specific permission indexes for ${mismatched_targets_csv}",
+          "evidence": "index=${table_index_number}, targets=${mismatched_targets_csv_nospace}",
+          "stakeholders": ["owner", "admin"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-P-2-02",
+      "dimension": "semantic",
+      "trigger": "custom permission (>= 1000) without a remark in the same call",
+      "cases": [
+        {
+          "when": { "field": "custom_index_without_remark", "op": "eq", "value": true },
+          "level": "low",
+          "title": "Custom permission without remark",
+          "description": "Custom permission ${table_index_number} has no remark; future maintainers won't know its purpose",
+          "scenario": "Adding custom permission without documentation",
+          "mitigation": "Add remark: { op: \"set\", index: ${table_index_number}, remark: \"<purpose>\" }",
+          "evidence": "index=${table_index_number}",
+          "stakeholders": ["admin"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-P-3-01",
+      "dimension": "authority",
+      "trigger": "permission over-concentration: owner is the only admin (set with a single address)",
+      "cases": [
+        {
+          "when": { "all": [ { "field": "admin_op", "op": "eq", "value": "set" }, { "field": "admin_address_count", "op": "eq", "value": 1 } ] },
+          "level": "medium",
+          "title": "Permission over-concentration",
+          "description": "Only one admin (likely owner); loss of owner key means permanent lockout",
+          "scenario": "Single-admin Permission",
+          "mitigation": "Add 1-2 backup admins with limited permission indexes",
+          "evidence": "admin_count=1",
+          "stakeholders": ["owner"],
+          "exposure": {
+            "loss_parties": [
+              { "role": "merchant", "basis": "With a single admin (the owner), losing that key permanently locks the Permission object — every role assignment, authority grant and fund-flow control it carries becomes unreachable, with no recovery path on-chain." }
+            ],
+            "gain_paths": []
+          }
+        }
+      ]
+    },
+    {
+      "rule_id": "R-P-3-02",
+      "dimension": "authority",
+      "trigger": "permission over-dispersion: admin count above 50",
+      "cases": [
+        {
+          "when": { "field": "admin_dispersion_count", "op": "gt", "value": 50 },
+          "level": "medium",
+          "title": "Permission over-dispersion",
+          "description": "${admin_dispersion_count} admins increases coordination cost and key-management risk",
+          "scenario": "Large admin committee",
+          "mitigation": "Use multi-sig or hierarchical admin structure",
+          "evidence": "admin_count=${admin_dispersion_count}",
+          "stakeholders": ["owner", "admin"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-P-3-03",
+      "dimension": "authority",
+      "trigger": "UM is the owner self-reference (same address as builder)",
+      "cases": [
+        {
+          "when": { "field": "um_is_builder", "op": "eq", "value": true },
+          "level": "medium",
+          "title": "UM is owner self-reference",
+          "description": "Setting UM to owner address defeats separation of concerns",
+          "scenario": "Owner delegates UM to self",
+          "mitigation": "Use a separate Contact object address for UM",
+          "evidence": "um=${um}",
+          "stakeholders": ["owner"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-P-4-01",
+      "dimension": "lifecycle",
+      "trigger": "ownership transfer operation (builder field set)",
+      "cases": [
+        {
+          "when": { "field": "builder", "op": "truthy" },
+          "level": "high",
+          "title": "Ownership transfer — irreversible",
+          "description": "Transferring Permission to ${builder}. Once executed, original owner loses ALL control permanently.",
+          "scenario": "Owner transfers Permission to new address",
+          "mitigation": "1) Verify new owner address twice. 2) Export Permission JSON before transfer. 3) Coordinate with new owner to confirm receipt.",
+          "evidence": "new_owner=${builder}",
+          "stakeholders": ["owner"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-P-4-02",
+      "dimension": "lifecycle",
+      "trigger": "apply to more than 3 objects at once",
+      "cases": [
+        {
+          "when": { "field": "apply_count", "op": "gt", "value": 3 },
+          "level": "medium",
+          "title": "Batch apply to multiple objects",
+          "description": "Applying Permission to ${apply_count} objects at once; if any object type mismatches, transaction may fail or silently misalign",
+          "scenario": "Batch apply across heterogeneous objects",
+          "mitigation": "Apply to 1-3 objects at a time; verify each object type matches permission indexes",
+          "evidence": "apply_count=${apply_count}",
+          "stakeholders": ["owner"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-P-4-03",
+      "dimension": "lifecycle",
+      "trigger": "entity replace operation (destructive)",
+      "cases": [
+        {
+          "when": { "field": "entity_op", "op": "eq", "value": "replace" },
+          "level": "medium",
+          "title": "Entity replace — destructive",
+          "description": "Replacing ${entity_replace_from} with ${entity_replace_to}; entity1 loses ALL permissions permanently",
+          "scenario": "Replacing a user who left the organization",
+          "mitigation": "Prefer 'copy' over 'replace' if entity1 should retain permissions",
+          "evidence": "entity1=${entity_replace_from}, entity2=${entity_replace_to}",
+          "stakeholders": ["entity"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-P-5-01",
+      "dimension": "cross_object",
+      "trigger": "apply to a Progress object (Permission becomes immutable on bind)",
+      "cases": [
+        {
+          "when": { "all": [ { "field": "apply", "op": "present" }, { "field": "targets_include_progress", "op": "eq", "value": true } ] },
+          "level": "medium",
+          "title": "Apply to Progress — post-bind mutability limited",
+          "description": "Once Permission is bound to Progress (which binds Machine), permission table changes may not affect already-published Machine workflow",
+          "scenario": "Permission shared across Machine/Progress",
+          "mitigation": "Configure all permission indexes before Machine publish",
+          "evidence": "target=Progress",
+          "stakeholders": ["owner"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-P-5-02",
+      "dimension": "cross_object",
+      "trigger": "permission reused across multiple host object types",
+      "cases": [
+        {
+          "when": { "field": "unique_target_type_count", "op": "gt", "value": 1 },
+          "level": "medium",
+          "title": "Permission shared across heterogeneous objects",
+          "description": "Single Permission applied to ${unique_target_types_csv}; permission indexes may have different semantics per object",
+          "scenario": "One Permission for both Service and Treasury",
+          "mitigation": "Use separate Permission objects per host object type for clarity",
+          "evidence": "types=${unique_target_types_csv_nospace}",
+          "stakeholders": ["owner", "admin"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-P-5-03",
+      "dimension": "cross_object",
+      "trigger": "treasury external_*_guard management index (255/256) granted — verify guard lists are populated",
+      "cases": [
+        {
+          "when": { "field": "treasury_external_guard_op", "op": "eq", "value": "withdraw" },
+          "level": "high",
+          "title": "Treasury external guard management granted — populate guard lists",
+          "description": "Permission ${table_index_number} (${treasury_external_guard_name}) granted; ensure external_${treasury_external_guard_op}_guard list is populated via external_*_guard_add so external operations are authorized",
+          "scenario": "External treasury guard management without populated guard lists",
+          "mitigation": "Call treasury.external_${treasury_external_guard_op}_guard_add to register Guard objects; external_deposit/external_withdraw require Guard + Passport (no Permission index)",
+          "evidence": "index=${table_index_number}",
+          "stakeholders": ["owner", "admin"],
+          "exposure": {
+            "loss_parties": [
+              { "role": "merchant", "basis": "The 256-class grant lets its holder remount the Treasury's release Guards, opening a permission-free external_withdraw gate over the Treasury balance." }
+            ],
+            "gain_paths": [
+              {
+                "role": "collaborator",
+                "path": "A non-owner holder of index ${table_index_number} replaces the external_withdraw_guard list with a permissive Guard and pulls funds to an address they control (the release pays the transaction sender).",
+                "viability": "viable",
+                "gate": "Guard-list write power is implied by the grant and the withdraw itself needs no Treasury Permission; confirm the holder is not the owner and review guard-list history."
+              }
+            ]
+          }
+        },
+        {
+          "when": { "field": "treasury_external_guard_op", "op": "eq", "value": "deposit" },
+          "level": "high",
+          "title": "Treasury external guard management granted — populate guard lists",
+          "description": "Permission ${table_index_number} (${treasury_external_guard_name}) granted; ensure external_${treasury_external_guard_op}_guard list is populated via external_*_guard_add so external operations are authorized",
+          "scenario": "External treasury guard management without populated guard lists",
+          "mitigation": "Call treasury.external_${treasury_external_guard_op}_guard_add to register Guard objects; external_deposit/external_withdraw require Guard + Passport (no Permission index)",
+          "evidence": "index=${table_index_number}",
+          "stakeholders": ["owner", "admin"]
+        }
+      ]
+    }
+  ]
+}