# Shared Language

Use this page to keep the repository's ubiquitous language stable.
It is the project-wide glossary for terms that should mean one thing everywhere in design artifacts, code, tests, and reviews.

## Why this exists

Naming inconsistency creates design inconsistency.
When the same concept is called three different things, reviewers and LLMs start inventing distinctions that are not real.
A stable shared language improves design quality, review quality, and implementation consistency.

This file is for **project-wide terms**.
Feature-specific naming choices should also be recorded in the relevant design artifact.

## How to use it

- Add terms that appear across multiple features or modules.
- Prefer short domain definitions over implementation detail.
- Record preferred terms and rejected synonyms.
- Update this file when the team decides one name should win.
- Keep the grammar consistent with the naming rules in `../explanation/naming-for-domain-modeling.md`.

## Core grammar

- **Commands**: imperative intents such as `LoadPackage`
- **Events**: past-tense facts such as `PackageLoaded`
- **States / Objects**: domain nouns such as `LoadingTruck`
- **Workflows**: verb-noun names such as `loadPackage`
- **Policies**: decision-oriented names such as `decideLoadEligibility`

## Project-wide glossary template

| Term | Meaning | Use this, not that | Notes |
| :--- | :--- | :--- | :--- |
| `Recovery Pipeline` | Release-oriented workflow that turns one upstream snapshot into a buildable, browsable recovered tree and release artifacts | `Recovery Pipeline` not `deobfuscation script chain` | Feature-level umbrella term used across contexts. |
| `Recovered Tree` | Canonical editable source tree emitted at repo root for review and modification | `Recovered Tree` not `original repo layout` | The tree is reconstructed for usability, not historical fidelity. |
| `Build-first` | Acceptance rule that preserves buildability even when readability improvements are still incomplete | `Build-first` not `runtime complete` | Current hard success invariant for the feature. |
| `Review-needed Artifact` | Machine-readable report plus concise human summary that surfaces uncertainty, failure, or conflict | `Review-needed Artifact` not `warning log` | Explicit inspection seam rather than hidden failure. |
| `Maintained Transform` | Durable replayable local change stored outside the numbered upstream-processing phases | `Maintained Transform` not `manual patch` | Reused by replay and release contexts. |
| `Naming Memory` | Small reviewable history of accepted recovered names reused in later relabel iterations | `Naming Memory` not `rename cache` | Shared iterative-naming term with reviewer-facing meaning. |

## Review questions

- Would a domain expert recognize these terms?
- Are the same concepts named consistently across story, events, model, code, and tests?
- Are we accidentally using programmer words where domain words should exist?
- Have we documented which synonym is preferred when multiple names are plausible?