# zero-amount-unguarded-map-debit-review

> Review an amount-zero successful numeric Map debit whose exact lookup has unknown prior membership.

Canonical: https://nightshade.dicksonwu.xyz/rules/zero-amount-unguarded-map-debit-review.html
Release: Nightshade 0.1.1 (v0.1.1)

| Field | Value |
| --- | --- |
| Rule ID | `zero-amount-unguarded-map-debit-review` |
| Severity | info |
| Confidence | high |
| Maturity | experimental |
| Selection | Opt-in |
| Policy intent | not required |
| Default enabled | no |
| Category | Other active opt-ins / Token, coin and value transfers |
| Engine facts used | entry-zero-history, exact-map-lookup, numeric-subtraction, ordered-writes |
| Release | v0.1.1 |

## Selection and scope

Not selected by default. Select it with `--detectors` or the `detectors` list in nightshade.json. Either one replaces profile selection, so list every rule you want.

```sh
./.nightshade/node_modules/.bin/nightshade ./contracts --detectors zero-amount-unguarded-map-debit-review
./.nightshade/node_modules/.bin/nightshade detector show zero-amount-unguarded-map-debit-review
```

The first command runs only this rule; `--detectors` takes a comma-separated list. The second prints the rule's metadata from your installed version.

Severity is review priority. It does not express exploitability or impact. Confidence is detector metadata, not a probability. All built-in rules are experimental.

Compiler scope: the engine supports the pinned profiles 0.28.0, 0.29.0, 0.30.0, 0.31.1, 0.33.0-rc.2, 0.34.0, 0.35.0-rc.1 and 0.35.0, with ZKIR2 by default. Support for this rule can be narrower; the rule documentation below states any narrower scope.

## Corpus checks

Synthetic corpus checks for this rule in the 0.1.1 proof run. A check counts only with compiler acceptance and complete analysis.

| Positive detected | Corrected quiet | Lookalike quiet | Other negative quiet | Incomplete |
| ---: | ---: | ---: | ---: | ---: |
| 2/2 | 2/2 | 2/2 | 0/0 | 0 |

No deviations were recorded for this rule.

These are behavior checks on synthetic fixtures, not a precision or recall estimate. See [evaluation](https://nightshade.dicksonwu.xyz/evaluation.md#synthetic-corpus).

## Rule documentation

From https://github.com/DicksonWu654/nightshade/blob/v0.1.1/docs/detectors/zero-amount-unguarded-map-debit-review.md at v0.1.1.

Availability: **opt-in**, no policy required. Severity: **info**. Confidence:
**high** for the supported static source relationship.

Select with `--detectors zero-amount-unguarded-map-debit-review`. The observer
selects actual debit operands from an ordinary successful invocation, then fixes
an unchanged numeric entry parameter to zero. Literal-zero APIs use ordinary
histories. It reports a numeric Map lookup whose exact immutable result is the
minuend of that subtraction and is written to the same exact entry, without an
intervening overlapping mutation, when membership was unknown before the lookup.
Each lookup retains its own occurrence identity and helper arguments retain
their actual values. One complete qualifying history suffices.

Same-entry guards and exact prior insertions are quiet. Parent-only or different
key membership does not establish the selected inner entry. A later guard does
not establish membership before an earlier lookup. Positive-only APIs,
addition, unrelated amounts, transformed debit parameters, different write
keys and intervening may-alias writes do not qualify. An earlier successful
same-entry lookup can establish membership, making a later debit read quiet.

Unknown membership is not missing membership. The rule does not establish
intended zero semantics, initial absence, runtime lookup failure, transaction
feasibility or impact. Initial storage remains unknown; cross-invocation
application invariants are not inferred. Intentional zero APIs can match.

The dedicated observer retains explicit empty operation sequences. Missing
lookup origins, operands, ordered writes or invocation evidence, reached
checkpoints and exhausted budgets produce diagnostics. Ordinary analysis and
the existing zero-membership policy remain unchanged.

Incomplete and rejected inputs provide no absence guarantee.

## Suppress a match

If a match is intentional, suppress it on the line before with the exact rule ID and a reason of at least eight characters:

```compact
// nightshade-disable-next-line zero-amount-unguarded-map-debit-review -- Reason this match is intentional
```

Diagnostics cannot be suppressed, and an unmatched directive for a selected rule makes analysis incomplete. See [configuration](https://nightshade.dicksonwu.xyz/configuration.md#suppress-an-intentional-match) for fingerprint suppressions and baselines.

## References

- [Rule source document at v0.1.1](https://github.com/DicksonWu654/nightshade/blob/v0.1.1/docs/detectors/zero-amount-unguarded-map-debit-review.md)
- [Catalog entry in rules.json](https://nightshade.dicksonwu.xyz/rules.json)
- [All rules](https://nightshade.dicksonwu.xyz/rules.md#token-coin-and-value-transfers)
- [Limitations](https://nightshade.dicksonwu.xyz/limitations.md)