Appendix C — Product patterns

Appendix C - 17. Per-mutator attribution stamps

The Structure of Per-mutator attribution stamps — its shape at a glance:

Each mutator writes its stamp through the one sanctioned stamp-writer for its format; the stamp is embedded in the artifact. Debug stamps are stripped before delivery; preserved stamps ship.

flowchart LR
  Verb[Mutator verb] -->|write_stamp| Writer["Stamp-writer (per format)"]
  Writer -->|embed at mutation site| Art[(Artifact)]
  Art -->|strip debug stamps| Deliver([delivered output])

Accessible description: a mutator verb writes its attribution stamp through the one stamp-writer for its format, which embeds the stamp in the artifact. Before delivery a strip step removes debug-visibility stamps, leaving preserved ones in the shipped output.

Projected from the catalogue entry provenance-and-attribution / Per-mutator attribution stamps.

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

Intent

Intent — Every remediation verb that mutates a document emits an attribution stamp embedded in the artifact through one sanctioned stamp-writer per format, so every change is durably attributable and the mutation history is reconstructable after the fact (our instances: a single PDF stamp-writer held as the sole surface by a ban-lint, and an append-only OOXML attribution registry).

Motivation

When a remediated document comes out wrong, you need to know which pass made which change; otherwise RCA is guesswork across many passes and four formats. Without attribution, a mutation is anonymous: you can see the output is wrong but not who wrote it or why. The failure is unattributable mutations → un-debuggable output, and it recurs on every mutation.

Applicability

Structure

The Structure diagram appears at the top of this page.

Sample Code

A stamp is a small record embedded at the mutation site: which pass, what it changed, and a visibility flag. One writer per format is the sole surface, so stamps are uniform. Visibility keeps delivery honest — debug stamps default on for reconstruction and are stripped before the document ships; a user-visible pass opts its stamp into "preserved."

from dataclasses import dataclass

@dataclass(frozen=True)
class Stamp:
    pass_name: str
    target: str
    visibility: str = "debug"    # "debug" is stripped before delivery; "preserved" ships

class StampWriter:
    """The sole stamp surface for one format. Embedding at the mutation site means
    the history travels with the artifact, not in logs that scroll away."""

    def __init__(self, artifact):
        self._artifact = artifact
        self._order = 0

    def write_stamp(self, stamp: Stamp) -> None:
        self._order += 1
        self._artifact.embed_metadata({"order": self._order, **stamp.__dict__})

def strip_for_delivery(artifact) -> None:
    # remove scaffolding before the document reaches the user
    artifact.drop_metadata(where=lambda m: m.get("visibility") == "debug")

Consequences

Example use within DocAble

Contents
⇐ Beginning of this partNext part ⇒Next chapter ›⇤ BeginningEnd ⇥Index
© James C. Davis, 2026–present