Appendix C - 16. F10 mutator-stamp-wiring lint

The Structure of F10 mutator-stamp-wiring lint — its shape at a glance:

The lint enumerates every mutator verb in the primitive layer and checks each for the stamp-wiring call. A wired verb passes; an unwired one fails the build.

flowchart TD
  Scan[Scan primitive layer] --> Verbs{Each mutator verb}
  Verbs -->|stamp wiring present| Pass([verb OK])
  Verbs -->|no stamp wiring| Fail([build blocked])

Accessible description: the lint scans the primitive layer, enumerates every mutator verb, and checks each for a stamp-wiring call. A verb with wiring passes; a verb missing it fails the build, so no unwired mutator can land.

Projected from the catalogue entry provenance-and-attribution / F10 mutator-stamp-wiring lint.

On this page: Intent · Motivation · Applicability · Structure · Sample Code · Consequences · Example use within DocAble · Related Patterns

Intent

Intent — A lint that fails the build if any mutator verb in the Model Primitives lacks stamp wiring, so a new mutator cannot land producing unattributable mutations.

Motivation

Attribution stamps only work if every mutator stamps. Add one new verb without wiring and it silently produces unattributable mutations, a hole in the audit trail that no one sees until an RCA hits it and finds no stamp. The failure is an unstamped mutator (an attribution gap), and it recurs when a new verb is added — usually under time pressure, when "remember to stamp" is most likely to be forgotten.

Applicability

• A detectable "mutator verb" pattern in the Primitives layer.
• A detectable stamp-wiring call so the lint can tell wired from unwired.
• A lint over the Primitives directories run in the gates.

Structure

The Structure diagram appears at the top of this page.

Sample Code

The lint is a completeness check: enumerate the members of a set, and assert each satisfies a required predicate. Here the members are the mutating methods in the primitive layer, and the predicate is "calls the stamp writer somewhere in its body." The value is that it catches an absence — the stamp that isn't there — which review reliably misses.

import ast, sys

STAMP_CALL = "write_stamp"          # the wiring every mutator must invoke

def _calls_stamp(fn: ast.FunctionDef) -> bool:
    return any(isinstance(n, ast.Call) and isinstance(n.func, ast.Attribute)
               and n.func.attr == STAMP_CALL for n in ast.walk(fn))

def _is_mutator(fn: ast.FunctionDef) -> bool:
    # a mutator verb: named for a document change and not a private helper
    return fn.name.startswith(("set_", "add_", "insert_", "remove_")) and not fn.name.startswith("_")

def lint(path: str, source: str) -> list[str]:
    return [f"{path}:{fn.lineno}: mutator '{fn.name}' has no stamp wiring"
            for fn in ast.walk(ast.parse(source))
            if isinstance(fn, ast.FunctionDef) and _is_mutator(fn) and not _calls_stamp(fn)]

if __name__ == "__main__":
    hits = [f for p in sys.argv[1:] for f in lint(p, open(p).read())]
    print("\n".join(hits)); sys.exit(1 if hits else 0)

Consequences

• The verb-detection heuristic is the weak point. Miss a verb shape and a real gap passes; over-match and legitimate code fails.
• Coupled to the Primitives structure. A reorganization of the mutator layer needs the lint updated in step.

Example use within DocAble

• The mutator-stamp wiring lint (F10, BLOCKING, 0 open gaps).

Related Patterns

• Counterpart — of mutator-stamps: the stamps are the construction (the audit record), this lint is the counted sensor that guarantees they're complete. The canonical construction-held-by-detection pairing on the product side.
• See also (sibling) — semantic-lints: the F10 lint is a member of that fleet doing a completeness-over-verbs job.
• Instance of — semantic-level-enforcement: pitching the guarantee at "was the call made" rather than "was the work correct" is one case of the general move — place a mechanism at the semantic level where its property is legible and cheap to check.