PDD-08@v1Modeling

Canonical by construction

Every part of the system can use the same stored identifier without its own lookup or case fixes.

Why

Agents often store display names, old names, or case variants as references to the same object. They then add lookups and repairs everywhere that reads the data. Different parts of the system can disagree about which object a reference identifies.

Canonical means one agreed, exact form for a stored reference. By construction means the code that saves the data produces that form before storage. Later code matches the stored identifier exactly.

For example, an import accepts “Customer email” as a field label. Before saving the reference, it resolves that label to the field's exact identifier, customer_email. If the label is unknown or ambiguous, the import refuses the input.

Installation

Terminal

npx --yes @principle-driven/[email protected] add canonical-by-construction

The CLI uses your prefix, assigns the next local number, and updates your agent index. CLI installation guide ↗

The Markdown preview uses the catalog token. Your installed file uses its local token.

Download .md

# PDD-08 — Canonical by construction
Token: PDD-08
Version: v1

## Rule

Store each reference as the exact identifier of its target object.

Before storage, resolve supported labels and aliases to that identifier. Refuse unknown or ambiguous references.

Keep label, alias, and case rules in one input resolver.

Code that reads stored references must match their identifiers exactly, without label lookups, case conversion, or fallback searches.

Preserve external protocols' required case, spelling, and byte order at their boundary. Keep display names and original input separate from the stored reference.

Repair invalid stored references through an explicit migration. Define a removal condition for temporary compatibility code.

## Rationale

Several stored forms force each part of the system to repeat input rules. One exact stored identifier removes those repairs.

## History

- v1 (2026-10-05): Published to prevent repeated alias and case handling across readers.