@wowok/agent-mcp 3.4.3 → 3.4.4

package/dist/knowledge/baselines/rules/registrar.json.good

@@ -0,0 +1,159 @@
+{
+  "comment": "Registrar+Entity rule pack (R-REG) — declarative form of the retired in-code Registrar/Entity risk rules. Facts are produced by the kernel extractor (registrar-risk.ts, bound to the on-chain registrar limits and the Vote.info bitmask); 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": {
+    "expects_singleton_migration": "The caller assumes the Entity/Registrar system singletons can be re-deployed or migrated (they cannot).",
+    "address_count": "Number of addresses registered (or about to be registered) in the Entity/Registrar ParentTables.",
+    "address_count_at_limit": "address_count has reached MAX_ADDRESS_COUNT (chain-limit comparison sunk into the extractor).",
+    "uses_reserved_vote_bits": "The caller relies on reserved Vote.info bits 4-7 staying unused.",
+    "expects_fresh_resource_on_register": "The caller calls entity_register expecting a fresh Resource (registration is idempotent).",
+    "expects_affiliation_event": "The caller expects object-linker affiliation/disaffiliation to emit events (none are emitted).",
+    "relies_on_typed_value_convention": "The caller relies on the Record.typed_value first-byte ValueType convention (docs-only enforcement).",
+    "is_resource_transfer": "The caller is performing an entity resource transfer.",
+    "expects_vote_time_only_on_like": "The caller expects Vote.time to update only on like (it updates on every toggle).",
+    "bit_no_info": "KERNEL CONSTANT — Vote.info bitmask value for no-info (BIT_NO_INFO).",
+    "bit_like": "KERNEL CONSTANT — Vote.info bitmask value for like (BIT_LIKE).",
+    "bit_dislike": "KERNEL CONSTANT — Vote.info bitmask value for dislike (BIT_DISLIKE).",
+    "bit_affiliation": "KERNEL CONSTANT — Vote.info bitmask value for affiliation (BIT_AFFILIATION).",
+    "max_address_count": "KERNEL CONSTANT — ParentTable address cap (MAX_ADDRESS_COUNT).",
+    "max_record_length": "KERNEL CONSTANT — per-record byte cap (MAX_RECORD_LENGTH).",
+    "max_record_count_registrar": "KERNEL CONSTANT — per-user record count cap (MAX_RECORD_COUNT_REGISTRAR)."
+  },
+  "rules": [
+    {
+      "rule_id": "R-REG-01",
+      "dimension": "lifecycle",
+      "trigger": "caller assumes the Entity/Registrar singletons can be migrated post-deploy",
+      "cases": [
+        {
+          "when": { "field": "expects_singleton_migration", "op": "eq", "value": true },
+          "level": "high",
+          "title": "Entity and Registrar are system singletons — cannot be migrated post-deploy",
+          "description": "Entity and Registrar are created once at package init by @0x0 and are globally unique. They cannot be re-created, migrated, or re-initialized. If the singleton's storage layout needs to change (e.g. ParentTable schema), the only option is a new package version with a migration path. There is no in-place migration API. All 22 objects depend on these singletons via object-linker bindings, so a migration would cascade to every object.",
+          "scenario": "Operator wants to migrate Entity to a new schema; no migration API exists",
+          "mitigation": "Confirm the schema before deployment. For schema evolution, plan a new package version with an explicit migration script. Never assume the singleton can be 'reset'.",
+          "evidence": "expects_singleton_migration=true (no migration API)",
+          "stakeholders": ["system", "user"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-REG-02",
+      "dimension": "structural",
+      "trigger": "registered address count reaches MAX_ADDRESS_COUNT",
+      "cases": [
+        {
+          "when": { "field": "address_count_at_limit", "op": "eq", "value": true },
+          "level": "medium",
+          "title": "MAX_ADDRESS_COUNT=${max_address_count} may be insufficient for large deployments",
+          "description": "The Entity and Registrar ParentTables are bounded by MAX_ADDRESS_COUNT=${max_address_count}. Exceeding the cap aborts address registration. For mass-market applications, ${max_address_count} entries may be too few; the limit is a single Move constant that requires a package upgrade to change.",
+          "scenario": "Popular service reaches 5200 registered users; new registrations abort",
+          "mitigation": "Monitor address_count. Plan a package upgrade that raises MAX_ADDRESS_COUNT before hitting the cap. For shardable workloads, consider multiple Entity tables in a future package version.",
+          "evidence": "address_count=${address_count}, limit=${max_address_count}",
+          "stakeholders": ["system", "user"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-REG-03",
+      "dimension": "semantic",
+      "trigger": "caller relies on reserved Vote.info bits 4-7",
+      "cases": [
+        {
+          "when": { "field": "uses_reserved_vote_bits", "op": "eq", "value": true },
+          "level": "medium",
+          "title": "Vote.info uses u8 bitmask — bits 4-7 reserved, future expansion must stay compatible",
+          "description": "Vote.info is a u8 bitmask: BIT_NO_INFO=${bit_no_info}, BIT_LIKE=${bit_like}, BIT_DISLIKE=${bit_dislike}, BIT_AFFILIATION=${bit_affiliation}. Bits 4-7 are reserved. A future version that repurposes bits 4-7 would conflict with any off-chain code that reads the raw byte. The reserved bits MUST be treated as zero today; non-zero values in bits 4-7 indicate a forward-incompatible voter.",
+          "scenario": "Future version assigns bit 4 to a new flag; old indexers misread the byte",
+          "mitigation": "Off-chain code must mask to bits 0-3 today and ignore bits 4-7. When a new flag is assigned, ship a coordinated Move + SDK + indexer update.",
+          "evidence": "uses_reserved_vote_bits=true (bits 4-7 are reserved)",
+          "stakeholders": ["voter", "system"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-REG-05",
+      "dimension": "cross_object",
+      "trigger": "caller expects object-linker affiliation changes to emit events",
+      "cases": [
+        {
+          "when": { "field": "expects_affiliation_event", "op": "eq", "value": true },
+          "level": "medium",
+          "title": "object-linker affiliation / disaffiliation emit no events — indexers must poll object_linker tables",
+          "description": "The affiliation binding, unbinding, and binding-change operations mutate the binding graph but emit no events. External indexers that track the object-dependency graph cannot rely on an event stream; they must poll the ParentTable, which is expensive as the graph grows.",
+          "scenario": "Indexer expects an AffiliationEvent; none is emitted, dependency graph is stale",
+          "mitigation": "Indexers should poll object_linker tables on a cadence and diff. Future versions may add AffiliationEvent; until then, do not build critical UX on affiliation event streams.",
+          "evidence": "expects_affiliation_event=true (no events)",
+          "stakeholders": ["system"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-REG-04",
+      "dimension": "lifecycle",
+      "trigger": "caller expects a fresh Resource from idempotent registration",
+      "cases": [
+        {
+          "when": { "field": "expects_fresh_resource_on_register", "op": "eq", "value": true },
+          "level": "low",
+          "title": "Registration is idempotent — returns existing Resource, not a fresh one",
+          "description": "Registration checks whether the sender already has an Entity record. If so, it returns the existing Resource address without creating a new one. Callers who expect a fresh Resource on each call (e.g. after a forced destroy) will silently receive the old one. Use the forced re-registration path to force-reallocate, and only when the old Resource is truly gone.",
+          "scenario": "User destroys their Resource then re-registers; gets the old (now-invalid) address",
+          "mitigation": "Document the idempotent behavior. After a forced destroy, callers MUST use the forced re-registration path. SDK should detect destroyed Resource and route accordingly.",
+          "evidence": "expects_fresh_resource_on_register=true (idempotent)",
+          "stakeholders": ["user"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-REG-06",
+      "dimension": "semantic",
+      "trigger": "caller relies on the Record.typed_value ValueType byte convention",
+      "cases": [
+        {
+          "when": { "field": "relies_on_typed_value_convention", "op": "eq", "value": true },
+          "level": "low",
+          "title": "Record.typed_value first byte is a ValueType — convention enforced only by docs",
+          "description": "Record.typed_value is a vector<u8> whose first byte encodes the ValueType. The Move layer validates that the vector is non-empty and within MAX_RECORD_LENGTH=${max_record_length}, but it does not validate that the first byte is a known ValueType. Off-chain consumers must agree on the ValueType byte layout; a misencoded record will deserialize to garbage without an on-chain abort. Record count is bounded by MAX_RECORD_COUNT_REGISTRAR=${max_record_count_registrar}.",
+          "scenario": "Caller writes a record with first byte 0xFF; no on-chain error, but consumers cannot decode",
+          "mitigation": "SDK must validate the first byte against the ValueType enum before submitting. Document the ValueType byte layout in both Move and SDK. Add a sync test that asserts the ValueType enum matches across layers.",
+          "evidence": "relies_on_typed_value_convention=true (docs-only enforcement)",
+          "stakeholders": ["user", "system"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-REG-07",
+      "dimension": "cross_object",
+      "trigger": "an entity resource transfer detaches the Resource from its source address",
+      "cases": [
+        {
+          "when": { "field": "is_resource_transfer", "op": "eq", "value": true },
+          "level": "medium",
+          "title": "Resource transfer detaches the Resource from the source address",
+          "description": "The entity resource transfer moves the Resource backing a user's identity mark to a new address. After transfer, the source address has no Resource — any downstream service that keyed identity on the source address loses the binding. There is no automatic forwarding stub left behind.",
+          "scenario": "User transfers Resource to a new wallet; old-wallet-based services break",
+          "mitigation": "Surface a 'transfer will detach the Resource from this address' warning. Consumers should track users by Resource address, not by user address. Provide a migration window where both addresses are valid.",
+          "evidence": "is_resource_transfer=true (source loses Resource)",
+          "stakeholders": ["user", "system"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-REG-08",
+      "dimension": "semantic",
+      "trigger": "caller expects Vote.time to advance only on like",
+      "cases": [
+        {
+          "when": { "field": "expects_vote_time_only_on_like", "op": "eq", "value": true },
+          "level": "low",
+          "title": "Vote.time updates on every toggle — including like→no-like",
+          "description": "Vote.time is set to clock.timestamp_ms() on every like/dislike operation, including toggles that remove a like (like→no-like). Consumers who interpret Vote.time as 'last liked at' will be confused when it advances on an un-like. The field semantically means 'last vote op time', not 'last positive vote'.",
+          "scenario": "User un-likes; Vote.time advances; indexer reads it as 'recently liked'",
+          "mitigation": "Document Vote.time as 'last vote operation time'. For 'last liked at' semantics, track the previous Vote.info state and only record time when BIT_LIKE transitions to set.",
+          "evidence": "expects_vote_time_only_on_like=true (updates on toggle)",
+          "stakeholders": ["voter", "system"]
+        }
+      ]
+    }
+  ]
+}

package/dist/knowledge/baselines/rules/repository.json.good

@@ -0,0 +1,244 @@
+{
+  "comment": "Repository rule pack (R-REP) — declarative form of the retired in-code Repository risk rules. Facts are produced by the kernel extractor (repository-risk.ts, bound to the live repository limits and the id_from routing semantics); 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": {
+    "policies": "The policy drafts under evaluation (name, id_from routing, write_guard size, submission routing flags).",
+    "existing_policy_count": "Number of policies already stored on the Repository object.",
+    "data_size": "Data payload size in bytes of the current write.",
+    "id_count_once": "Number of data IDs targeted by the current single operation.",
+    "reward_count": "Number of Reward objects referenced by the Repository.",
+    "is_data_remove_with_passport": "Whether the operation is the passport-driven data removal entry point (R-D-2 check).",
+    "constants_synced": "Whether the Repository constants are synced to onchain-constants.ts (the sync reminder fires when falsy).",
+    "has_quote_guard": "Whether quote_guard is set (Some) on any policy.",
+    "quote_guard_is_depended": "Whether the quote_guard satisfies is_depended (immutable + no relies + rep=true).",
+    "quote_guard_verifies_payment": "Whether the quote_guard verifies Payment for subscription.",
+    "has_owner_receive": "Whether the Repository has owner_receive configured for Payment revenue.",
+    "max_policy_count": "KERNEL CONSTANT — live MAX_POLICY_COUNT limit from the published package.",
+    "max_policy_guard_count": "KERNEL CONSTANT — live MAX_POLICY_GUARD_COUNT limit from the published package.",
+    "max_data_size": "KERNEL CONSTANT — live MAX_DATA_SIZE limit in bytes from the published package.",
+    "max_id_count_once": "KERNEL CONSTANT — live MAX_ID_COUNT_ONCE limit from the published package.",
+    "max_reward_count": "KERNEL CONSTANT — live MAX_REWARD_COUNT limit from the published package.",
+    "policies_count": "KERNEL — number of policy drafts being added in this operation.",
+    "total_policy_count": "KERNEL — existing_policy_count + policies_count (present only when both inputs exist).",
+    "policy_count_over_limit": "KERNEL — total_policy_count exceeds the live MAX_POLICY_COUNT.",
+    "policy_none_guard_no_id_count": "KERNEL — policies with id_from=None (caller-provided id) AND an empty write_guard list.",
+    "policy_none_guard_no_id_list": "KERNEL — comma-space joined names of the id_from=None + empty write_guard policies.",
+    "policy_auto_id_submission_count": "KERNEL — policies with id_from=Clock/Signer (auto-generated id) whose guard sets id_from_submission.",
+    "policy_auto_id_submission_list": "KERNEL — comma-space joined 'name(id_from=<raw>)' entries of the auto-id + id_from_submission policies.",
+    "policy_guard_over_limit_count": "KERNEL — policies whose write_guard count exceeds the live MAX_POLICY_GUARD_COUNT.",
+    "policy_guard_over_limit_list": "KERNEL — comma-space joined 'name(count)' entries of the over-limit policies.",
+    "data_size_over_limit": "KERNEL — data_size exceeds the live MAX_DATA_SIZE.",
+    "id_count_over_limit": "KERNEL — id_count_once exceeds the live MAX_ID_COUNT_ONCE.",
+    "reward_count_at_limit": "KERNEL — reward_count has reached the live MAX_REWARD_COUNT (>= limit).",
+    "policy_data_sub_no_id_sub_count": "KERNEL — policies whose guard sets data_from_submission without id_from_submission (Mode 5 mixed write).",
+    "policy_data_sub_no_id_sub_list": "KERNEL — comma-space joined names of the data_from_submission-only policies.",
+    "policy_data_sub_removal_count": "KERNEL — policies whose guard sets data_from_submission while the operation is passport-driven data removal.",
+    "policy_data_sub_removal_list": "KERNEL — comma-space joined names of those policies.",
+    "quote_guard_gap": "KERNEL — what the quote_guard subscription design is missing ('quote_guard does not verify Payment' / 'Repository missing owner_receive for revenue', joined by '; '; empty when fully configured)."
+  },
+  "rules": [
+    {
+      "rule_id": "R-REP-01",
+      "dimension": "structural",
+      "trigger": "existing + new policy count exceeds MAX_POLICY_COUNT",
+      "cases": [
+        {
+          "when": { "field": "policy_count_over_limit", "op": "eq", "value": true },
+          "level": "medium",
+          "title": "Policy count exceeds MAX_POLICY_COUNT (${max_policy_count})",
+          "description": "A single Repository may hold up to MAX_POLICY_COUNT=${max_policy_count} policies. Exceeding this limit aborts with E_POLICY_COUNT_EXCEEDED (3) when a policy is added. Each policy defines a named data slot with its own write_guard list and id_from routing — having too many policies makes the Repository hard to audit and increases gas cost for policy lookups (an O(n) scan by policy name).",
+          "scenario": "Caller adds 51 policies to a single Repository",
+          "mitigation": "Consolidate related data under fewer policies. If truly needed, split data across multiple Repository objects and reference them via Service.repository or Progress.context_repositories.",
+          "evidence": "existing=${existing_policy_count}, adding=${policies_count}, total=${total_policy_count}, limit=${max_policy_count}",
+          "stakeholders": ["creator"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-REP-02",
+      "dimension": "policy",
+      "trigger": "a policy sets id_from=None with an empty write_guard list",
+      "cases": [
+        {
+          "when": { "field": "policy_none_guard_no_id_count", "op": "gt", "value": 0 },
+          "level": "high",
+          "title": "write_guard empty when id_from=None — unauthorized writes (R-D-1 Move assert)",
+          "description": "When id_from is None, the data ID must be provided by the caller (via the passport-guarded data write or the mixed id+data write). Without a write_guard, ANY address can write data with any ID — this is almost certainly a misconfiguration. The Move contract now enforces this via E_POLICY_WRITE_GUARD_REQUIRED (22) at policy-add time [R-D-1=A].",
+          "scenario": "Caller creates a policy with id_from=None and empty write_guard list",
+          "mitigation": "When id_from=None, provide at least one PolicyGuard entry in write_guard. If you want unrestricted writes, use id_from=Clock or id_from=Signer instead (which auto-generates the ID and requires empty write_guard).",
+          "evidence": "policies with id_from=None + empty write_guard: ${policy_none_guard_no_id_list}",
+          "stakeholders": ["creator", "writer"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-REP-03",
+      "dimension": "policy",
+      "trigger": "a guard sets id_from_submission while the policy routes id_from=Clock/Signer",
+      "cases": [
+        {
+          "when": { "field": "policy_auto_id_submission_count", "op": "gt", "value": 0 },
+          "level": "high",
+          "title": "id_from_submission set when id_from=Clock/Signer — id routing conflict (R-D-1 Move assert)",
+          "description": "When id_from is Clock or Signer, the data ID is auto-generated (timestamp or signer address). A PolicyGuard with id_from_submission set would try to route the id from a Passport submission, conflicting with the auto-generated id_from path. The Move contract enforces that id_from_submission MUST be None for every PolicyGuard when id_from is Clock/Signer (data_from_submission is still allowed — it is used by the guarded data-extraction entry point to extract data from the submission). Violations abort with E_POLICY_ID_FROM_SUBMISSION_FORBIDDEN (23) at policy-add time [R-D-1=A, refined].",
+          "scenario": "Caller creates a policy with id_from=Clock and a write_guard entry whose id_from_submission is set",
+          "mitigation": "When id_from=Clock or Signer, ensure every PolicyGuard has id_from_submission=null. data_from_submission may still be set if you want the guard to supply the data payload (routed via the guarded data-extraction entry point). If you need submission-derived ids, switch to id_from=None and set id_from_submission on the guard.",
+          "evidence": "policies with id_from=Clock/Signer + id_from_submission set: ${policy_auto_id_submission_list}",
+          "stakeholders": ["creator", "writer"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-REP-04",
+      "dimension": "structural",
+      "trigger": "a policy's write_guard count exceeds MAX_POLICY_GUARD_COUNT",
+      "cases": [
+        {
+          "when": { "field": "policy_guard_over_limit_count", "op": "gt", "value": 0 },
+          "level": "medium",
+          "title": "Policy write_guard count exceeds MAX_POLICY_GUARD_COUNT (${max_policy_guard_count})",
+          "description": "Each policy may define up to MAX_POLICY_GUARD_COUNT=${max_policy_guard_count} guard entries in its write_guard list. Exceeding this limit aborts with E_POLICY_GUARD_COUNT_EXCEEDED (2). Each entry maps to a Guard object that must be verified via Passport submission, so more guards = more complex write authorization semantics.",
+          "scenario": "Caller creates a policy with 11 guard entries in write_guard",
+          "mitigation": "Consolidate guard logic. If multiple guards must verify the same data, consider composing them into a single Guard with relies/rep fields, or split the data across multiple policies with fewer guards each.",
+          "evidence": "policies exceeding guard count: ${policy_guard_over_limit_list}",
+          "stakeholders": ["creator"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-REP-05",
+      "dimension": "structural",
+      "trigger": "a data payload exceeds MAX_DATA_SIZE",
+      "cases": [
+        {
+          "when": { "field": "data_size_over_limit", "op": "eq", "value": true },
+          "level": "medium",
+          "title": "Data value exceeds MAX_DATA_SIZE (${max_data_size} bytes)",
+          "description": "A single Repository data value must be ≤ MAX_DATA_SIZE=${max_data_size} bytes. Exceeding this limit aborts with E_DATA_EXCEEDED (4). The value is stored as a BCS-serialized vector<u8> with a type-tag prefix byte. Large data should be stored off-chain (e.g. IPFS, Walrus) and referenced by hash/address, NOT inlined into the Repository data value.",
+          "scenario": "Caller writes a 50KB JSON blob as a Repository data value",
+          "mitigation": "Store large payloads off-chain and write only the content hash (32-64 bytes) to the Repository. Use about_address on a Proof object to bind the off-chain data to an on-chain attestation.",
+          "evidence": "data_size=${data_size}, limit=${max_data_size}",
+          "stakeholders": ["writer"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-REP-06",
+      "dimension": "routing",
+      "trigger": "a guard sets data_from_submission without id_from_submission (Mode 5 mixed write)",
+      "cases": [
+        {
+          "when": { "field": "policy_data_sub_no_id_sub_count", "op": "gt", "value": 0 },
+          "level": "low",
+          "title": "Policy has data_from_submission but no id_from_submission — verify Mode 5 routing intent",
+          "description": "When a PolicyGuard has data_from_submission set (data comes from Passport submission) but no id_from_submission (id comes from caller), the SDK routes to the mixed id+data passport write (Mode 5). This is a valid but advanced pattern — ensure the caller provides matching id vectors. The SDK hasSubmissionSettings helper now correctly detects this case [P1-1 fix, R-D-3=A].",
+          "scenario": "Policy has a guard with data_from_submission=2, id_from_submission=undefined",
+          "mitigation": "Document the expected caller input shape. Ensure the caller provides both the id vector (positional) and the Passport submission (for data). Verify routing via the SDK hasSubmissionSettings helper.",
+          "evidence": "policies with data_from_submission but no id_from_submission: ${policy_data_sub_no_id_sub_list}",
+          "stakeholders": ["creator", "writer"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-REP-07",
+      "dimension": "submission",
+      "trigger": "passport-driven data removal targets a policy whose guard sets data_from_submission",
+      "cases": [
+        {
+          "when": { "field": "policy_data_sub_removal_count", "op": "gt", "value": 0 },
+          "level": "high",
+          "title": "data_from_submission set on a policy used for passport-driven data removal — Move will abort (R-D-2)",
+          "description": "Passport-driven data removal only removes data identified by the caller-provided id vector; it cannot consume Passport submissions for either id or data. The Move contract now enforces that BOTH id_from_submission AND data_from_submission MUST be None for this entry point [R-D-2=A], aborting with E_GUARD_SPECIFIED_ID_FROM_SUBMISSION (11). Previously, only id_from_submission was checked, allowing data_from_submission to be silently ignored — masking a routing bug.",
+          "scenario": "Caller uses passport-driven data removal on a policy whose guard has data_from_submission=2",
+          "mitigation": "For data removal via Passport, use the mixed id+data removal entry point instead (which requires id_from_submission and derives the id from the submission). Do not set data_from_submission on policies intended for passport-driven data removal.",
+          "evidence": "policies with data_from_submission used in passport-driven data removal: ${policy_data_sub_removal_list}",
+          "stakeholders": ["writer", "verifier"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-REP-08",
+      "dimension": "structural",
+      "trigger": "a single op's ID count exceeds MAX_ID_COUNT_ONCE",
+      "cases": [
+        {
+          "when": { "field": "id_count_over_limit", "op": "eq", "value": true },
+          "level": "low",
+          "title": "ID count per single op exceeds MAX_ID_COUNT_ONCE (${max_id_count_once})",
+          "description": "A single Repository call (data_add, data_remove, id_data_*) may operate on at most MAX_ID_COUNT_ONCE=${max_id_count_once} IDs. Exceeding this limit aborts with E_ID_COUNT_EXCEEDED (5). Batch large operations across multiple transactions.",
+          "scenario": "Caller passes 150 IDs in a single data_remove call",
+          "mitigation": "Split into batches of ≤ ${max_id_count_once} IDs per transaction.",
+          "evidence": "id_count=${id_count_once}, limit=${max_id_count_once}",
+          "stakeholders": ["writer"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-REP-09",
+      "dimension": "structural",
+      "trigger": "reward count reaches MAX_REWARD_COUNT",
+      "cases": [
+        {
+          "when": { "field": "reward_count_at_limit", "op": "eq", "value": true },
+          "level": "info",
+          "title": "Reward count approaches MAX_REWARD_COUNT (${max_reward_count})",
+          "description": "A Repository may reference up to MAX_REWARD_COUNT=${max_reward_count} Reward objects. Exceeding this limit aborts with E_MAX_REWARD_COUNT_EXCEEDED (19). Rewards incentivize data contribution; having many rewards is fine but increases accounting complexity.",
+          "scenario": "Caller adds 20 rewards to a Repository (at the limit)",
+          "mitigation": "Monitor reward count. If more incentives are needed, consolidate rewards or use a separate Repository.",
+          "evidence": "reward_count=${reward_count}, limit=${max_reward_count}",
+          "stakeholders": ["creator"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-REP-10",
+      "dimension": "knowledge",
+      "trigger": "constants drift from onchain-constants.ts / knowledge-layer gaps (sync reminder)",
+      "cases": [
+        {
+          "when": { "field": "constants_synced", "op": "falsy" },
+          "level": "info",
+          "title": "Knowledge layer & constant sync — RESOLVED",
+          "description": "All 6 Repository constants (MAX_POLICY_COUNT, MAX_POLICY_DESCRIPTION_LEN, MAX_POLICY_GUARD_COUNT, MAX_DATA_SIZE, MAX_ID_COUNT_ONCE, MAX_REWARD_COUNT) are now synced to onchain-constants.ts. The MCP Knowledge layer now includes repository-risk.ts, repository-confirm.ts, repository-translation.ts (R-D-4=A). The SDK hasSubmissionSettings helper now correctly checks both id_from_submission AND data_from_submission (P1-1). parseIdFrom is used in data/data_remove (P1-2). This risk rule is retained for historical audit and to detect future regressions.",
+          "scenario": "Future regression: someone removes a Repository constant from onchain-constants.ts",
+          "mitigation": "Run the onchain-constants sync test to detect drift.",
+          "evidence": "constants_synced=false",
+          "stakeholders": ["system"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-REP-11",
+      "dimension": "policy",
+      "trigger": "quote_guard set but not dependency-safe",
+      "cases": [
+        {
+          "when": { "all": [ { "field": "has_quote_guard", "op": "truthy" }, { "field": "quote_guard_is_depended", "op": "falsy" } ] },
+          "level": "high",
+          "title": "quote_guard must be dependency-safe (immutable + rep=true + no relies) — Move assert",
+          "description": "Repository policy's quote_guard must satisfy the dependency-safety requirement: immutable=true, relies empty, rep=true. This ensures the quote_guard is a stable, repository-querying guard that can be depended upon. Move aborts with E_NEED_DEPENDENT_GUARD if the guard is not dependency-safe. VERIFIED: passport.rs#L545-612 (check_repository_quote_guard enforces this at query time).",
+          "scenario": "Creator sets quote_guard to a Guard that is not dependency-safe (e.g., has relies or is mutable)",
+          "mitigation": "Ensure the quote_guard Guard object has: immutable=true, relies=empty, rep=true. Use pattern.repository_quote_guard_subscription as the design template.",
+          "evidence": "quote_guard set but not dependency-safe (immutable + rep=true + no relies)",
+          "stakeholders": ["creator", "reader"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-REP-12",
+      "dimension": "knowledge",
+      "trigger": "quote_guard subscription without Payment verification or owner_receive revenue",
+      "cases": [
+        {
+          "when": { "all": [ { "field": "has_quote_guard", "op": "truthy" }, { "field": "quote_guard_gap", "op": "truthy" } ] },
+          "level": "medium",
+          "title": "quote_guard data subscription design — verify Payment verification + owner_receive revenue",
+          "description": "When using quote_guard for data subscription (Repository+quote_guard+Payment pattern), ensure: (1) quote_guard verifies Payment fields (for_object matches Repository, amount meets price), (2) Repository has owner_receive<T> configured to accept Payment as subscription revenue. VERIFIED: passport.rs#L545-612. DESIGN: quote_guard is a RIGID verification requirement — any guard querying this Repository's data MUST satisfy the quote_guard (see R-X1-10 in guard-risk.ts).",
+          "scenario": "Creator sets quote_guard but does not configure Payment verification or owner_receive",
+          "mitigation": "1) Ensure quote_guard verifies Payment (for_object, amount); 2) Configure Repository owner_receive<T> to accept subscription Payment revenue; 3) Use pattern.repository_quote_guard_subscription (guard-design-patterns.ts) and tpl_repository_quote_guard_subscription (guard-templates.ts) as design templates.",
+          "evidence": "${quote_guard_gap}",
+          "stakeholders": ["creator", "reader", "verifier"]
+        }
+      ]
+    }
+  ]
+}

package/dist/knowledge/baselines/rules/resource.json.good

@@ -0,0 +1,117 @@
+{
+  "comment": "Resource rule pack (R-RESOURCE) — declarative form of the retired in-code Resource risk rules. Facts are produced by the kernel extractor (resource-risk.ts, bound to the on-chain tag limit); 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": {
+    "expects_resource_permission": "The caller relies on Resource enforcing its own permission checks (it associates none — access control is delegated to the calling module).",
+    "expects_tag_events": "The caller expects tag mutations to emit on-chain events (tag operations emit none — indexers must poll).",
+    "tags_count": "Raw tag count for a single object, passed through for evidence text.",
+    "tags_count_over_limit": "True when tags_count is provided and meets or exceeds the chain tag limit (the on-chain abort boundary).",
+    "is_destroy": "The caller is invoking the irreversible destroy operation.",
+    "tag_set_return_ignored": "The caller discards the bool result of the tag-set operation (the 'already exists' signal).",
+    "references_dead_switch": "The caller references the fully commented-out (dead) switch function of the Move layer.",
+    "max_tags_count": "KERNEL CONSTANT — maximum tag entries a single object's tag vector may hold (the on-chain abort boundary)."
+  },
+  "rules": [
+    {
+      "rule_id": "R-RESOURCE-01",
+      "dimension": "permission",
+      "trigger": "caller relies on Resource enforcing its own permission checks",
+      "cases": [
+        {
+          "when": { "field": "expects_resource_permission", "op": "eq", "value": true },
+          "level": "low",
+          "title": "Resource has no Permission — relies entirely on caller-side gating",
+          "description": "Resource does not associate with a Permission object. All functions are public(package) (new/destroy/transfer) or public (tag set/unset, object tag add/remove, object removal) — there is no on-chain permission check. Access control is delegated to the calling module (Personal, Entity). A caller that forgets to enforce its own permission check would let any address mutate tags.",
+          "scenario": "Personal/Entity forgets to gate object-tag additions behind its own permission check",
+          "mitigation": "Callers (Personal, Entity) MUST enforce their own permission checks before invoking Resource functions. Audit the call sites in Personal/Entity to confirm gating.",
+          "evidence": "expects_resource_permission=true (Resource has none)",
+          "stakeholders": ["owner", "caller"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-RESOURCE-02",
+      "dimension": "semantic",
+      "trigger": "caller expects tag mutations to emit events",
+      "cases": [
+        {
+          "when": { "field": "expects_tag_events", "op": "eq", "value": true },
+          "level": "medium",
+          "title": "Tag mutations emit no events — external indexers must poll",
+          "description": "Object-tag additions, object-tag removals, and whole-object removals do not emit events. External indexers cannot rely on an event stream to track tag changes; they must poll the ParentTable field. This complicates real-time notification and consistency.",
+          "scenario": "Indexer expects a TagAddedEvent but none is emitted; UI fails to refresh",
+          "mitigation": "External indexers should poll Resource.table on a cadence. Do not build critical UX on tag event streams until events are added in a future version.",
+          "evidence": "expects_tag_events=true (no events emitted)",
+          "stakeholders": ["owner", "caller"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-RESOURCE-03",
+      "dimension": "structural",
+      "trigger": "tag count meets or exceeds the chain tag limit",
+      "cases": [
+        {
+          "when": { "field": "tags_count_over_limit", "op": "eq", "value": true },
+          "level": "low",
+          "title": "MAX_TAGS_COUNT=${max_tags_count} permissive — storage cost",
+          "description": "A single object's AddressTag.tags vector may hold up to MAX_TAGS_COUNT=${max_tags_count} entries. The limit aborts with E_TAGS_COUNT_EXCEEDED (1) only at the boundary. 100 tags per object is generous; loading all tags on every read increases gas and storage cost.",
+          "scenario": "Caller adds 100 tags to a single object",
+          "mitigation": "Business layer should self-limit tag count well below 100. For heavy tagging, shard across multiple Resource objects or store bulk tags off-chain.",
+          "evidence": "tags_count=${tags_count}, limit=${max_tags_count}",
+          "stakeholders": ["owner"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-RESOURCE-04",
+      "dimension": "lifecycle",
+      "trigger": "destroy is being invoked",
+      "cases": [
+        {
+          "when": { "field": "is_destroy", "op": "eq", "value": true },
+          "level": "low",
+          "title": "destroy is irreversible — no recovery mechanism",
+          "description": "Resource.destroy(resource) deletes the object and its ParentTable in place. There is no archive, no event, and no rollback. Once destroyed, the object ID is permanently invalid and all tags are lost.",
+          "scenario": "Caller destroys a Resource that is still referenced by Personal/Entity",
+          "mitigation": "Confirm no live references exist before calling destroy. SDK should refuse to destroy a Resource whose owner address is still referenced by Personal.mark or Entity.resource.",
+          "evidence": "is_destroy=true (irreversible)",
+          "stakeholders": ["owner"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-RESOURCE-05",
+      "dimension": "semantic",
+      "trigger": "tag-set bool return value is ignored by the caller",
+      "cases": [
+        {
+          "when": { "field": "tag_set_return_ignored", "op": "eq", "value": true },
+          "level": "medium",
+          "title": "Setting a tag returns bool — SDK may ignore the 'already exists' signal",
+          "description": "Setting a tag on an object returns bool: true if a new tag was added, false if the tag already existed. If the SDK ignores the return value, callers cannot distinguish 'newly added' from 'duplicate silently skipped'. This masks intent and complicates idempotency reasoning.",
+          "scenario": "SDK treats the tag-set result as void; caller assumes tag was added when it was a duplicate",
+          "mitigation": "SDK should expose the tag-set bool return value to the caller. UI should show 'tag already existed' when false is returned.",
+          "evidence": "tag_set_return_ignored=true (duplicate not surfaced)",
+          "stakeholders": ["caller"]
+        }
+      ]
+    },
+    {
+      "rule_id": "R-RESOURCE-06",
+      "dimension": "semantic",
+      "trigger": "caller references the commented-out switch function",
+      "cases": [
+        {
+          "when": { "field": "references_dead_switch", "op": "eq", "value": true },
+          "level": "low",
+          "title": "Commented-out switch function — feature may be intended",
+          "description": "The module contains a switch function that is fully commented out. The intended behavior is unclear — it may be a planned feature (e.g. bulk tag operations) that was disabled. Referencing it as if it were live would silently fail.",
+          "scenario": "Developer reads the commented switch and assumes it is callable",
+          "mitigation": "Confirm with the package maintainers whether the switch should be enabled or removed. Do not reference it in SDK or MCP code.",
+          "evidence": "references_dead_switch=true (commented out in Move)",
+          "stakeholders": ["system"]
+        }
+      ]
+    }
+  ]
+}

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

@@ -430,7 +430,7 @@
     {
       "rule_id": "R-R-7-01",
       "dimension": "fund_recovery",
-      "trigger": "coin_add/receive (deposit) or guard_add without an owner fund-recovery escape guard",
+      "trigger": "coin_add/receive (deposit) or guard_add without an owner fund-recovery escape guard (advisory — recovery via withdraw 158 always exists once the no-guard window lapses)",
       "cases": [
         {
           "when": { "all": [
@@ -439,14 +439,14 @@
           ] },
           "level": "medium",
           "title": "No owner fund-recovery escape guard on this Reward",
-          "description": "claim() is the GUARD-FREE exit from the Reward's balance field, and none of the guards being configured is an owner escape hatch. withdraw (op 158) is the only OTHER exit — permission-gated and blocked while the no-guard window (guard_not_added_expiration_time) stands, and it routes the remainder to the pool owner as the commitment's disclosed reversal, not as a condition-gated escape guard; without either, any unclaimed remainder stays locked forever. Note: owner_receive (op 156) never touches balance — it only extracts objects the Reward RECEIVED via transfer (Receiving<CoinWrapper<K>> or NFT-like objects) to the Permission owner; receive (op 154) is what joins payments into balance. This is a configuration gap, not a contract defect.",
+          "description": "claim() is the GUARD-FREE buyer-facing exit from the Reward's balance field, and no configured guard carries the owner claim-side escape signature (Signer recipient + GuardU64Identifier amount). Fund recovery does NOT depend on that signature: withdraw (op 158, ETS-B) is the second exit — permission-gated and blocked ONLY while the no-guard window (guard_not_added_expiration_time) stands; once it lapses (or if it was never set) the owner recovers the full unclaimed remainder (guard_expiration_time_add can set/clear the window after it expires). An unclaimed remainder is therefore NEVER permanently locked. The escape guard is an OPTIONAL in-window recovery rail (owner reclaims via claim() behind a Clock lock) or a one-PTB alternative — its absence is an advisory configuration note, not a fund-safety defect. Note: owner_receive (op 156) never touches balance — it only extracts objects the Reward RECEIVED via transfer (Receiving<CoinWrapper<K>> or NFT-like objects) to the Permission owner; receive (op 154) is what joins payments into balance.",
           "scenario": "A marketing Reward is fully consumed by guards, the campaign ends with a residual balance, and the merchant has no guard that lets them reclaim it.",
-          "mitigation": "Add an escape guard alongside the other guards: (1) Guard: logic_and(logic_equal(query(1002 permission.owner [permission_address]), Signer), logic_greater_equal(Clock, <unlock_time>)) — verifies the tx sender is the live Permission owner, with the Clock comparison acting as the lock period (e.g. 30 days); (2) RewardGuard entry: recipient=Signer, amount=GuardU64Identifier(u8 submission mark), expiration_time=unlock_time + claim window (or None) — remember the contract asserts clock <= expiration_time, i.e. expiration is the last claimable moment, not the unlock moment; (3) after unlock the owner claims by submitting the full remaining balance to recover 100%.",
+          "mitigation": "PRIMARY (no guard needed): after guard_not_added_expiration_time lapses — or immediately if it was never set — call withdraw (op 158) / withdraw_and_unwrap to recover the unclaimed remainder in full (payment.receipt or same-PTB unwrap). OPTIONAL in-window escape guard: (1) Guard: logic_and(logic_equal(query(1002 permission.owner [permission_address]), Signer), logic_greater_equal(Clock, <unlock_time>)) — verifies the tx sender is the live Permission owner, with the Clock comparison acting as the lock period (e.g. 30 days); (2) RewardGuard entry: recipient=Signer, amount=GuardU64Identifier(u8 submission mark), expiration_time=unlock_time + claim window (or None) — remember the contract asserts clock <= expiration_time, i.e. expiration is the last claimable moment, not the unlock moment; (3) after unlock the owner claims by submitting the full remaining balance.",
           "evidence": "deposit=${has_deposit}, guard_add=${guard_add_count}, escape=false (no entry with Signer recipient + GuardU64Identifier amount)",
           "stakeholders": ["owner"],
           "exposure": {
             "loss_parties": [
-              { "role": "merchant", "basis": "Unclaimed reward remainder stays locked in the balance field forever — the merchant's deposited budget is unrecoverable." }
+              { "role": "merchant", "basis": "Residual budget stays committed (unwithdrawable) only until guard_not_added_expiration_time lapses; recoverable in full thereafter via withdraw (op 158). Advisory only: the escape guard adds IN-WINDOW owner recovery." }
             ],
             "gain_paths": []
           }
@@ -455,14 +455,14 @@
           "when": { "field": "recovery_gap_present", "op": "eq", "value": true },
           "level": "low",
           "title": "No owner fund-recovery escape guard on this Reward",
-          "description": "claim() is the GUARD-FREE exit from the Reward's balance field, and none of the guards being configured is an owner escape hatch. withdraw (op 158) is the only OTHER exit — permission-gated and blocked while the no-guard window (guard_not_added_expiration_time) stands, and it routes the remainder to the pool owner as the commitment's disclosed reversal, not as a condition-gated escape guard; without either, any unclaimed remainder stays locked forever. Note: owner_receive (op 156) never touches balance — it only extracts objects the Reward RECEIVED via transfer (Receiving<CoinWrapper<K>> or NFT-like objects) to the Permission owner; receive (op 154) is what joins payments into balance. This is a configuration gap, not a contract defect.",
+          "description": "claim() is the GUARD-FREE buyer-facing exit from the Reward's balance field, and no configured guard carries the owner claim-side escape signature (Signer recipient + GuardU64Identifier amount). Fund recovery does NOT depend on that signature: withdraw (op 158, ETS-B) is the second exit — permission-gated and blocked ONLY while the no-guard window (guard_not_added_expiration_time) stands; once it lapses (or if it was never set) the owner recovers the full unclaimed remainder (guard_expiration_time_add can set/clear the window after it expires). An unclaimed remainder is therefore NEVER permanently locked. The escape guard is an OPTIONAL in-window recovery rail (owner reclaims via claim() behind a Clock lock) or a one-PTB alternative — its absence is an advisory configuration note, not a fund-safety defect. Note: owner_receive (op 156) never touches balance — it only extracts objects the Reward RECEIVED via transfer (Receiving<CoinWrapper<K>> or NFT-like objects) to the Permission owner; receive (op 154) is what joins payments into balance.",
           "scenario": "A marketing Reward is fully consumed by guards, the campaign ends with a residual balance, and the merchant has no guard that lets them reclaim it.",
-          "mitigation": "Add an escape guard alongside the other guards: (1) Guard: logic_and(logic_equal(query(1002 permission.owner [permission_address]), Signer), logic_greater_equal(Clock, <unlock_time>)) — verifies the tx sender is the live Permission owner, with the Clock comparison acting as the lock period (e.g. 30 days); (2) RewardGuard entry: recipient=Signer, amount=GuardU64Identifier(u8 submission mark), expiration_time=unlock_time + claim window (or None) — remember the contract asserts clock <= expiration_time, i.e. expiration is the last claimable moment, not the unlock moment; (3) after unlock the owner claims by submitting the full remaining balance to recover 100%.",
+          "mitigation": "PRIMARY (no guard needed): after guard_not_added_expiration_time lapses — or immediately if it was never set — call withdraw (op 158) / withdraw_and_unwrap to recover the unclaimed remainder in full (payment.receipt or same-PTB unwrap). OPTIONAL in-window escape guard: (1) Guard: logic_and(logic_equal(query(1002 permission.owner [permission_address]), Signer), logic_greater_equal(Clock, <unlock_time>)) — verifies the tx sender is the live Permission owner, with the Clock comparison acting as the lock period (e.g. 30 days); (2) RewardGuard entry: recipient=Signer, amount=GuardU64Identifier(u8 submission mark), expiration_time=unlock_time + claim window (or None) — remember the contract asserts clock <= expiration_time, i.e. expiration is the last claimable moment, not the unlock moment; (3) after unlock the owner claims by submitting the full remaining balance.",
           "evidence": "deposit=${has_deposit}, guard_add=${guard_add_count}, escape=false (no entry with Signer recipient + GuardU64Identifier amount)",
           "stakeholders": ["owner"],
           "exposure": {
             "loss_parties": [
-              { "role": "merchant", "basis": "Unclaimed reward remainder stays locked in the balance field forever — the merchant's deposited budget is unrecoverable." }
+              { "role": "merchant", "basis": "Residual budget stays committed (unwithdrawable) only until guard_not_added_expiration_time lapses; recoverable in full thereafter via withdraw (op 158). Advisory only: the escape guard adds IN-WINDOW owner recovery." }
             ],
             "gain_paths": []
           }
@@ -481,7 +481,7 @@
           ] },
           "level": "medium",
           "title": "Compensation pool solvency: the pool is NOT per-order escrow — claims beyond the balance abort",
-          "description": "Experience compensation rides the Reward object (C-11): one pre-funded pool serves ALL buyers' claims, with no per-order isolation. A claim larger than the current balance aborts with E_INSUFFICIENT_BALANCE (6) — the buyer faces a failed claim, not a queued payout. Size coin_add to expected claims × worst tier and refill on schedule; the R-R-7-01 escape-guard advice keeps the residual recoverable.",
+          "description": "Experience compensation rides the Reward object (C-11): one pre-funded pool serves ALL buyers' claims, with no per-order isolation. A claim larger than the current balance aborts with E_INSUFFICIENT_BALANCE (6) — the buyer faces a failed claim, not a queued payout. Size coin_add to expected claims × worst tier and refill on schedule; the residual stays recoverable via withdraw (op 158) after the no-guard window lapses (R-R-7-01).",
           "scenario": "A late-delivery wave drains the compensation pool before the tail of the wave claims",
           "mitigation": "1) Fund upfront for the worst-case claim wave (expected claims × worst tier), refill periodically. 2) Keep tiers so a single claim cannot exceed a bounded share of the pool. 3) Monitor the balance against the open claim window — an exhausted pool turns the compensation promise into an unfunded one (must be disclosed, never silently left to abort).",
           "evidence": "compensation intent, guard_add=${guard_add_count}",
@@ -574,9 +574,9 @@
           ] },
           "level": "low",
           "title": "No clawback: compensation flows one way — out to claimers",
-          "description": "The Reward balance has no pull-back path: claim (guard-free) and withdraw (158) both move funds OUT; deposited compensation is recoverable only via the R-R-7-01 escape guard for the UNCLAIMED remainder. A paid claim is final even if the underlying incident is later reversed (e.g. the order is refunded after an overlapping-window compensation claim) — supplier recourse is a SEPARATE ledger (off-chain or a distinct on-chain arrangement), never a Reward-side reversal.",
+          "description": "The Reward balance has no pull-back path for PAID claims: claim (guard-free) and withdraw (158) both move funds OUT; the UNCLAIMED remainder is recoverable via withdraw (158) once the no-guard window (guard_not_added_expiration_time) lapses — or in-window via the R-R-7-01 escape guard. A paid claim is final even if the underlying incident is later reversed (e.g. the order is refunded after an overlapping-window compensation claim) — supplier recourse is a SEPARATE ledger (off-chain or a distinct on-chain arrangement), never a Reward-side reversal.",
           "scenario": "A buyer claims late-compensation and then also wins a refund; the merchant wants the compensation back",
-          "mitigation": "1) Prevent overlap structurally: the compensation guard accepts completed/settled terminals only (tbs7 F-04 claim-and-return precedent). 2) Treat paid compensation as sunk; recover from the supplier through the separate recourse arrangement. 3) Use the escape guard (R-R-7-01) for the unclaimed tail only.",
+          "mitigation": "1) Prevent overlap structurally: the compensation guard accepts completed/settled terminals only (tbs7 F-04 claim-and-return precedent). 2) Treat paid compensation as sunk; recover from the supplier through the separate recourse arrangement. 3) Recover the unclaimed tail via withdraw (158) after the no-guard window lapses; the escape guard (R-R-7-01) is the in-window alternative.",
           "evidence": "compensation intent, deposit=${has_deposit}",
           "stakeholders": ["owner", "service_provider"]
         }