atomadic-forge 0.3.2__py3-none-any.whl

atomadic_forge/a0_qk_constants/gen_language.py

@@ -0,0 +1,116 @@
+"""Tier a0 — generation language constants for forge iterate / evolve.
+
+Forge's generator loop (``forge iterate``, ``forge evolve``) emits source
+code in a target language.  The default has always been Python; this module
+adds JavaScript and TypeScript as first-class targets so an LLM can produce
+Cloudflare-Worker-shaped or Node-shaped tier scaffolds with the same loop.
+
+Pure data.  Determines:
+  * ``PKG_ROOT_TEMPLATE`` — where Forge writes the generated package
+    (Python uses ``output/src/<pkg>/`` for pip-install compatibility;
+    JS/TS use ``output/<pkg>/`` because there's no ``src/`` PEP).
+  * ``ALLOWED_FILE_EXTS`` — what file suffixes ``_safe_path`` accepts.
+    Forge rejects any other suffix to prevent the LLM from emitting
+    polyglot junk into a single-language tree.
+  * ``MAIN_EXT`` — the canonical primary extension (``.py`` / ``.js`` /
+    ``.ts``) used in scaffolded tier file names.
+  * ``EMITS_INIT_FILES`` — whether Forge generates ``__init__.py``-style
+    package indices (Python only).
+  * ``EMITS_PYPROJECT`` — whether Forge writes ``pyproject.toml`` (Python
+    only).  JS/TS scaffolds get a minimal ``package.json`` instead.
+
+This is intentionally small.  More language-specific knobs (e.g. tsconfig
+generation, vitest vs node:test) belong in scaffold helpers, not here.
+"""
+
+from __future__ import annotations
+
+from typing import Final, Literal
+
+Language = Literal["python", "javascript", "typescript"]
+
+LANGUAGES: Final[tuple[Language, ...]] = ("python", "javascript", "typescript")
+
+DEFAULT_LANGUAGE: Final[Language] = "python"
+
+
+# Package-root templates.  The keys are language names; values are
+# format strings with a single ``{package}`` substitution that gets
+# joined to the user's ``output`` directory.
+PKG_ROOT_TEMPLATE: Final[dict[Language, str]] = {
+    "python":     "src/{package}",
+    "javascript": "{package}",
+    "typescript": "{package}",
+}
+
+
+# File suffixes Forge will accept from an LLM emit, per language.  Every
+# other suffix is silently dropped by ``_safe_path``.  Note all languages
+# allow ``.md`` (READMEs / per-file documentation) and the relevant config
+# file (``.toml`` for Python, ``.json`` for JS/TS).
+ALLOWED_FILE_EXTS: Final[dict[Language, frozenset[str]]] = {
+    "python":     frozenset({".py", ".md", ".toml"}),
+    "javascript": frozenset({".js", ".mjs", ".cjs", ".jsx",
+                              ".json", ".md"}),
+    "typescript": frozenset({".ts", ".tsx", ".js", ".mjs",
+                              ".json", ".md"}),
+}
+
+
+# Canonical primary extension used when Forge scaffolds tier files.
+MAIN_EXT: Final[dict[Language, str]] = {
+    "python":     ".py",
+    "javascript": ".js",
+    "typescript": ".ts",
+}
+
+
+# Whether Forge emits Python-style package indices (``__init__.py``).
+# JS/TS use ES module exports directly — no per-directory index file
+# is required for imports to resolve.
+EMITS_INIT_FILES: Final[dict[Language, bool]] = {
+    "python":     True,
+    "javascript": False,
+    "typescript": False,
+}
+
+
+# Whether Forge writes a ``pyproject.toml`` at the output root.
+# JS/TS scaffolds get a minimal ``package.json`` from a different helper.
+EMITS_PYPROJECT: Final[dict[Language, bool]] = {
+    "python":     True,
+    "javascript": False,
+    "typescript": False,
+}
+
+
+def normalize_language(value: str | None) -> Language:
+    """Coerce a user-supplied language string into the canonical Language.
+
+    Accepts ``"python" | "javascript" | "js" | "typescript" | "ts"`` (and
+    common aliases).  Returns the canonical Language literal.  Raises
+    ``ValueError`` if the input is not recognised.
+
+    ``None`` returns the default language (``"python"``) so callers can
+    pass through optional CLI flags without branching.
+    """
+    if value is None:
+        return DEFAULT_LANGUAGE
+    v = value.strip().lower()
+    if v in ("python", "py"):
+        return "python"
+    if v in ("javascript", "js", "node"):
+        return "javascript"
+    if v in ("typescript", "ts"):
+        return "typescript"
+    raise ValueError(
+        f"unknown language: {value!r} — expected one of {list(LANGUAGES)}"
+    )
+
+
+def pkg_root_for(language: Language, package: str) -> str:
+    """Return the package-root path *relative to the output directory*.
+
+    Pure: no I/O.  Caller joins this against their output ``Path``.
+    """
+    return PKG_ROOT_TEMPLATE[language].format(package=package)

atomadic_forge/a0_qk_constants/lang_extensions.py

@@ -0,0 +1,150 @@
+"""Tier a0 — language extensions and ignore lists Forge recognises.
+
+Pure data. Determines which files Forge's recon, wire, and certify passes
+include in their walks. Adding a language is a one-line change here.
+
+Files Forge classifies into three buckets:
+  * **source**       — code that participates in tier classification, wire
+                       checks, and import-graph analysis.
+  * **documentation** / **config** / **asset** — files that contribute to
+                       repo *signals* (a README.md flips ``has_readme``,
+                       a docs/ARCHITECTURE.md flips ``has_docs``) but are
+                       NEVER counted as "untiered code" — they have no
+                       tier identity and harshing the layout score on
+                       their position would be wrong.
+
+Plus an ignore list of directories Forge never recurses into (VCS internals,
+package caches, build outputs, AI-tooling worktrees, etc.).
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+# Extensions Forge classifies as Python source.
+PYTHON_EXTS: Final[frozenset[str]] = frozenset({".py"})
+
+# Extensions Forge classifies as JavaScript source.
+JAVASCRIPT_EXTS: Final[frozenset[str]] = frozenset({".js", ".mjs", ".cjs", ".jsx"})
+
+# Extensions Forge classifies as TypeScript source.
+TYPESCRIPT_EXTS: Final[frozenset[str]] = frozenset({".ts", ".tsx"})
+
+# All source extensions Forge walks. Order matters only for stable iteration.
+ALL_SOURCE_EXTS: Final[frozenset[str]] = (
+    PYTHON_EXTS | JAVASCRIPT_EXTS | TYPESCRIPT_EXTS
+)
+
+# Documentation: contributes positively to the docs signal; never tier-classified.
+DOC_EXTS: Final[frozenset[str]] = frozenset({
+    ".md", ".markdown", ".mdx", ".rst", ".txt", ".adoc", ".asciidoc",
+})
+
+# Config / data files: present-but-not-code.  Never count toward tier layout.
+CONFIG_EXTS: Final[frozenset[str]] = frozenset({
+    ".json", ".yaml", ".yml", ".toml", ".ini", ".cfg",
+    ".env", ".lock", ".gitignore", ".editorconfig",
+})
+
+# Page / image / binary assets.  Same treatment as docs/config.
+ASSET_EXTS: Final[frozenset[str]] = frozenset({
+    ".html", ".htm", ".css", ".scss", ".sass", ".less",
+    ".svg", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".ico", ".bmp",
+    ".pdf", ".docx", ".pptx", ".xlsx",
+    ".woff", ".woff2", ".ttf", ".otf",
+    ".mp3", ".mp4", ".wav", ".webm",
+})
+
+# Map a file extension to a canonical language label.
+LANG_OF_EXT: Final[dict[str, str]] = {
+    **{e: "python" for e in PYTHON_EXTS},
+    **{e: "javascript" for e in JAVASCRIPT_EXTS},
+    **{e: "typescript" for e in TYPESCRIPT_EXTS},
+}
+
+# Directories Forge never recurses into.  These hold tooling, caches, build
+# outputs, agent worktrees, and dependencies — none of it is Atomadic's code.
+IGNORED_DIRS: Final[frozenset[str]] = frozenset({
+    # Version control
+    ".git", ".hg", ".svn",
+    # Package / language caches
+    "node_modules", "__pycache__", ".pytest_cache", ".ruff_cache",
+    ".mypy_cache", ".tox", ".nox", ".cache",
+    # Build outputs
+    "dist", "build", "out", "target", ".next", ".nuxt", ".svelte-kit",
+    "coverage", ".coverage", "htmlcov",
+    # Virtualenvs
+    ".venv", "venv", "env", ".env",
+    # IDE / AI tooling
+    ".vscode", ".idea", ".cursor", ".codeium", ".aider",
+    ".claude", ".github",
+    # Agent / worktree clutter
+    "worktrees", ".worktrees",
+    # Cloudflare / wrangler
+    ".wrangler", ".wrangler-cache",
+    # Atomadic-Forge's own scratch dir
+    ".atomadic-forge",
+})
+
+
+def is_ignored_dir_name(name: str) -> bool:
+    """Return True for directory names Forge should never recurse into."""
+    return name in IGNORED_DIRS or name.startswith(".pytest_tmp")
+
+
+def path_parts_contain_ignored_dir(parts: tuple[str, ...]) -> bool:
+    """Return True when any path segment is an ignored directory name."""
+    return any(is_ignored_dir_name(part) for part in parts)
+
+
+def lang_for_path(path: str) -> str | None:
+    """Return ``"python"`` / ``"javascript"`` / ``"typescript"`` or ``None``.
+
+    Pure: only the suffix is consulted, never the file content.
+    """
+    s = path.lower()
+    for ext, lang in LANG_OF_EXT.items():
+        if s.endswith(ext):
+            return lang
+    return None
+
+
+def file_class_for_path(path: str) -> str:
+    """Return ``"source"`` / ``"documentation"`` / ``"config"`` / ``"asset"``
+    / ``"other"`` — the broad class Forge treats this file as.
+
+    Pure: only the path is consulted.  Used by certify to decide whether a
+    file's location should affect tier-layout scoring (only ``source`` does).
+    """
+    p = path.lower()
+    # Filename-based dotfile matches (no extension)
+    base = p.rsplit("/", 1)[-1].rsplit("\\", 1)[-1]
+    if base in {".gitignore", ".editorconfig", ".env"}:
+        return "config"
+    if base.startswith(".env."):
+        return "config"
+    if base in {"license", "license.md", "license.txt", "readme", "readme.md", "readme.rst"}:
+        return "documentation"
+    # Extension-based
+    for ext in ALL_SOURCE_EXTS:
+        if p.endswith(ext):
+            return "source"
+    for ext in DOC_EXTS:
+        if p.endswith(ext):
+            return "documentation"
+    for ext in CONFIG_EXTS:
+        if p.endswith(ext):
+            return "config"
+    for ext in ASSET_EXTS:
+        if p.endswith(ext):
+            return "asset"
+    return "other"
+
+
+def is_ignored_segment(segment: str) -> bool:
+    """Return True if a path segment matches an ignored directory name.
+
+    Kept for callers that still ask about one segment at a time; delegates
+    to the same predicate used by full-path ignore checks.
+    """
+    return is_ignored_dir_name(segment)

atomadic_forge/a0_qk_constants/policy_schema.py

@@ -0,0 +1,48 @@
+"""Tier a0 — atomadic-forge.policy/v1 schema.
+
+Codex #10: 'Let repos declare their own agent rules.'
+
+  > [tool.forge.agent]
+  > protected_files = ["pyproject.toml", "docs/PAPER_v2.md"]
+  > release_gate = ["ruff", "pytest", "build", "forge certify"]
+  > max_files_per_patch = 8
+  > require_human_review_for = ["license", "security", "public_api"]
+
+This module declares the v1 policy shape. The reader (a1) parses
+pyproject.toml's [tool.forge.agent] section into this dict. The
+preflight + patch_scorer modules consume it.
+
+a0 invariant: imports limited to __future__ + typing.
+"""
+from __future__ import annotations
+
+from typing import TypedDict
+
+SCHEMA_VERSION_POLICY_V1 = "atomadic-forge.policy/v1"
+
+
+# Default values when no policy is declared. Lenient — Forge does
+# not block on the absence of a policy file.
+DEFAULT_PROTECTED_FILES: tuple[str, ...] = ()
+DEFAULT_RELEASE_GATE: tuple[str, ...] = (
+    "python -m ruff check .",
+    "python -m pytest",
+    "forge wire src --fail-on-violations",
+    "forge certify . --fail-under 75",
+)
+DEFAULT_MAX_FILES_PER_PATCH: int = 8
+DEFAULT_REQUIRE_HUMAN_REVIEW_FOR: tuple[str, ...] = (
+    "license", "security", "public_api",
+)
+
+
+class AgentPolicy(TypedDict, total=False):
+    """v1 policy shape — every field optional; reader fills defaults."""
+    schema_version: str
+    protected_files: list[str]
+    release_gate: list[str]
+    max_files_per_patch: int
+    require_human_review_for: list[str]
+    # Forward-compat: future versions may add fields. Consumers MUST
+    # tolerate unknown keys.
+    extra: dict[str, object]

atomadic_forge/a0_qk_constants/receipt_schema.py

@@ -0,0 +1,311 @@
+"""Tier a0 — Forge Receipt JSON v1 schema.
+
+The Receipt is the canonical wire format Forge emits for every
+``forge auto`` / ``forge certify`` / ``forge enforce`` run. It bundles
+the certify breakdown, wire scan summary, scout digest, optional
+assimilate output, AAAA-Nexus signature placeholder, and Lean4
+attestation citation into one signed-or-signable artifact.
+
+Golden Path Lane A W0 deliverable. Lane A W1 fills in
+``a1_at_functions/receipt_emitter.py`` (the pure transformer that
+turns a CertifyResult + WireReport + ScoutReport into a Receipt) and
+``a1_at_functions/card_renderer.py`` (the 60×24 box-drawing renderer
+used by ``forge auto`` and the "62 → 5" viral demo). Lane A W2 fills
+in ``a2_mo_composites/receipt_signer.py`` which calls AAAA-Nexus
+``/v1/verify/forge-receipt`` to obtain a Sigstore Rekor uuid +
+log_index + AAAA-Nexus signature.
+
+Schema versioning:
+  * v1.0 (this file)            — base schema; all signing / lineage /
+                                  attestation fields are optional and
+                                  default to None so unsigned Receipts
+                                  are valid.
+  * v1.1 (Golden Path W8)       — adds ``polyglot_breakdown`` (per-
+                                  language certify score split).
+  * v1.2 (Golden Path W12)      — adds ``slsa_attestation`` (a
+                                  Sigstore-bundle-compatible
+                                  ``slsa-provenance-ai/v1`` predicate).
+  * v2.0 (Golden Path W24)      — adds ``bao_rompf_witnesses`` (full
+                                  categorical effect signatures per
+                                  public symbol).
+
+Forward-compat rule: every optional field defaults to ``None`` (or
+``[]`` / ``{}`` for collections). Consumers must accept and ignore
+unknown fields. Producers MUST emit ``schema_version`` and SHOULD
+emit every required field; everything else is optional.
+
+Wire-format note: ``schema_version`` always matches the regex
+``^atomadic-forge\\.receipt/v\\d+(?:\\.\\d+)?$`` so a single dispatcher
+can route any future Receipt version.
+
+This module is pure data shape — no logic, no imports beyond
+``typing``. Keeps a0 invariant under the Atomadic monadic law.
+"""
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+SCHEMA_VERSION_V1 = "atomadic-forge.receipt/v1"
+SCHEMA_VERSION_V1_1 = "atomadic-forge.receipt/v1.1"
+SCHEMA_VERSION_V1_2 = "atomadic-forge.receipt/v1.2"
+SCHEMA_VERSION_V2 = "atomadic-forge.receipt/v2"
+
+ReceiptVerdict = Literal["PASS", "FAIL", "REFINE", "QUARANTINE"]
+
+
+class ReceiptVCS(TypedDict, total=False):
+    """Version-control metadata for the project under Receipt.
+
+    All optional. ``dirty`` is True when the working tree had
+    uncommitted changes at Receipt-emission time. ``head_sha`` is the
+    full commit SHA, ``branch`` the symbolic ref. Receipts emitted on
+    detached HEAD report ``branch=None``.
+    """
+    head_sha: str
+    short_sha: str
+    branch: str | None
+    remote_url: str
+    dirty: bool
+
+
+class ReceiptProject(TypedDict, total=False):
+    """Identifies the project this Receipt covers."""
+    name: str
+    root: str                       # absolute path at emission time
+    package: str | None             # python package name (if applicable)
+    language: str                   # primary_language from scout
+    languages: dict[str, int]       # per-language file counts
+    vcs: ReceiptVCS
+
+
+class ReceiptCertifyAxes(TypedDict):
+    """Per-axis pass/fail flags from CertifyResult.
+
+    The structural axes (always present in v1):
+      * documentation_complete   — README.md OR ≥2 docs/*.md
+      * tests_present            — tests/test_*.py OR tests/*_test.py
+      * tier_layout_present      — ≥3 tier directories
+      * no_upward_imports        — wire scan PASS
+    """
+    documentation_complete: bool
+    tests_present: bool
+    tier_layout_present: bool
+    no_upward_imports: bool
+
+
+class ReceiptCertify(TypedDict):
+    """Compact certify summary embedded in the Receipt.
+
+    Mirrors CertifyResult's score + axes; full details remain in
+    ``.atomadic-forge/certify.json`` (referenced by ``artifacts``).
+    """
+    score: float                    # 0..100
+    axes: ReceiptCertifyAxes
+    issues: list[str]
+
+
+class ReceiptWire(TypedDict):
+    """Compact wire summary embedded in the Receipt.
+
+    Mirrors WireReport's verdict + counts; the full violation list and
+    repair suggestions remain in ``.atomadic-forge/wire.json``.
+    """
+    verdict: Literal["PASS", "FAIL"]
+    violation_count: int
+    auto_fixable: int               # populated only when --suggest-repairs
+
+
+class ReceiptScout(TypedDict):
+    """Compact scout summary embedded in the Receipt."""
+    symbol_count: int
+    tier_distribution: dict[str, int]
+    effect_distribution: dict[str, int]
+    primary_language: str
+
+
+class ReceiptArtifact(TypedDict):
+    """Pointer to an evidence file under .atomadic-forge/.
+
+    A consuming verifier can re-hash the file at ``path`` and compare
+    against ``sha256`` to confirm the Receipt references the exact
+    artifact at issue. Hashing is the consumer's responsibility; the
+    emitter populates the field when it can.
+    """
+    name: str                       # e.g. "scout", "wire", "certify"
+    path: str                       # relative to project root
+    sha256: str | None              # None when not computed (cheap mode)
+
+
+class ReceiptSigstoreSignature(TypedDict, total=False):
+    """Sigstore Rekor entry for the Receipt (Lane A W2)."""
+    rekor_uuid: str
+    log_index: int
+    bundle_path: str                # path to the sigstore bundle file
+
+
+class ReceiptAAAANexusSignature(TypedDict, total=False):
+    """AAAA-Nexus signature attached via /v1/verify/forge-receipt (Lane A W2)."""
+    signature: str                  # base64-encoded
+    key_id: str
+    issuer: str                     # e.g. "aaaa-nexus.atomadic.tech"
+    issued_at_utc: str
+    verify_endpoint: str            # e.g. "/v1/verify/forge-receipt"
+
+
+class ReceiptLocalSignSignature(TypedDict, total=False):
+    """Ed25519 local signing block (Lane G W5).
+
+    Populated by ``a1_at_functions.local_signer.sign_receipt_local`` when
+    the caller passes ``--local-sign``. The signature covers the canonical
+    receipt hash (same content-addressed bytes used by the lineage chain),
+    so re-signing after a notes append does not change the signed payload.
+    """
+    alg: str            # always "Ed25519"
+    signature: str      # base64-encoded 64-byte Ed25519 signature
+    public_key: str     # base64-encoded 32-byte raw public key
+    key_id: str         # first 16 hex chars of SHA-256(raw_public_key)
+    signed_at_utc: str  # YYYY-MM-DDTHH:MM:SSZ
+
+
+class ReceiptSignatures(TypedDict, total=False):
+    """All signature claims attached to this Receipt.
+
+    Receipts can ship unsigned (all fields ``None``) — ``--emit-receipt``
+    without ``--sign`` produces a structurally-valid but unattested
+    Receipt suitable for local development. Lane A W2's signer fills
+    ``sigstore`` and ``aaaa_nexus``; Lane G W5's local signer fills
+    ``local_sign``.
+    """
+    sigstore: ReceiptSigstoreSignature | None
+    aaaa_nexus: ReceiptAAAANexusSignature | None
+    local_sign: ReceiptLocalSignSignature | None  # Lane G W5
+
+
+class ReceiptLean4Corpus(TypedDict, total=False):
+    """One Lean4 corpus citation. Multiple per Receipt.
+
+    Cites a machine-checked theorem corpus that backs a claim made by
+    this Receipt. The Golden Path threads two corpora through every
+    Receipt: ``aethel-nexus-proofs`` (29 theorems, 0 sorry, 0 axioms)
+    and ``mhed-toe-codex-v22`` (538 theorems, 0 sorry).
+    """
+    name: str                       # e.g. "aethel-nexus-proofs"
+    repo_url: str
+    ref_sha: str                    # commit SHA the Receipt cites
+    theorem_count: int
+    sorry_count: int                # MUST be 0 for an attesting Receipt
+    axiom_count: int                # SHOULD be 0; record exceptions
+
+
+class ReceiptLean4Attestation(TypedDict, total=False):
+    """Lean4 attestation block (Lane A; cited in CS-1 at Lane F W16)."""
+    corpora: list[ReceiptLean4Corpus]
+    total_theorems: int             # sum across corpora — denormalized for ergonomics
+    summary: str                    # human-readable one-liner
+
+
+class ReceiptLineage(TypedDict, total=False):
+    """Pointer to the Vanguard structural-change ledger entry (Lane A W4).
+
+    ``lineage_path`` is opaque to the Receipt — Vanguard owns the
+    schema. A consumer can dereference it via the AAAA-Nexus
+    ``/v1/forge/lineage`` endpoint to fetch the full chain.
+    """
+    lineage_path: str               # opaque ledger path / URL
+    parent_receipt_hash: str | None # SHA-256 of the immediately prior Receipt
+    chain_depth: int                # 1 for first Receipt; n+1 for each successor
+
+
+class ReceiptPolyglotBreakdown(TypedDict, total=False):
+    """v1.1 — per-language file + symbol counts (Lane A W8 seed).
+
+    Forward-compat: v0.4+ will add per-language certify scores; today
+    we only ship the file + symbol breakdown so consumers can render
+    'this repo is 80% Python, 15% TypeScript' badges from the Receipt
+    alone (no separate scout call needed).
+    """
+    file_count: int
+    languages: dict[str, int]            # {lang: file_count}
+    symbol_count: int
+    symbols_by_language: dict[str, int]  # {lang: symbol_count}
+    primary_language: str
+
+
+class ForgeReceiptV1(TypedDict, total=False):
+    """The Forge Receipt v1.0 wire format.
+
+    Required fields (every emitter MUST populate):
+      * schema_version
+      * generated_at_utc
+      * forge_version
+      * verdict
+      * project
+      * certify
+      * wire
+      * scout
+
+    Optional fields (filled in by W2+ infrastructure or omitted in
+    cheap-mode emission):
+      * assimilate           — present only on --apply runs
+      * artifacts            — pointers to .atomadic-forge/*.json files
+      * signatures           — Sigstore + AAAA-Nexus claims
+      * lean4_attestation    — corpus citations
+      * lineage              — Vanguard ledger pointer (W4)
+      * compliance_mappings  — populated at Lane F W18
+      * extra                — escape hatch for forward-compat fields
+
+    Reserved (will be required in future minor versions):
+      * polyglot_breakdown   — v1.1 (Lane A W8)
+      * slsa_attestation     — v1.2 (Lane A W12)
+      * bao_rompf_witnesses  — v2.0 (Lane A W24)
+    """
+    # ---- required (v1.0) ----
+    schema_version: str
+    generated_at_utc: str           # YYYY-MM-DDTHH:MM:SSZ
+    forge_version: str
+    verdict: ReceiptVerdict
+    project: ReceiptProject
+    certify: ReceiptCertify
+    wire: ReceiptWire
+    scout: ReceiptScout
+    # ---- optional (v1.0) ----
+    assimilate_digest: str | None
+    artifacts: list[ReceiptArtifact]
+    signatures: ReceiptSignatures
+    lean4_attestation: ReceiptLean4Attestation
+    lineage: ReceiptLineage
+    compliance_mappings: dict[str, str]    # mapping_name → status
+    notes: list[str]                       # free-form human-facing notes
+    extra: dict[str, object]               # forward-compat escape hatch
+    # v1.1 (Lane A W8) — optional in v1.0, required in v1.1+:
+    polyglot_breakdown: ReceiptPolyglotBreakdown
+
+
+REQUIRED_RECEIPT_V1_FIELDS: tuple[str, ...] = (
+    "schema_version",
+    "generated_at_utc",
+    "forge_version",
+    "verdict",
+    "project",
+    "certify",
+    "wire",
+    "scout",
+)
+"""The minimum field set every v1 Receipt MUST populate.
+
+Used by ``a1_at_functions/receipt_emitter.py`` to short-circuit
+emission and by tests to guard against silent drift. The list itself
+is part of the schema contract — adding a required field is a major
+version bump.
+"""
+
+
+VALID_VERDICTS: tuple[str, ...] = ("PASS", "FAIL", "REFINE", "QUARANTINE")
+"""The four UEP v20 verdict values. Every Receipt's ``verdict`` must
+be exactly one of these strings.
+
+PASS         — wire PASS AND certify ≥ threshold
+FAIL         — at least one structural gate failed
+REFINE       — incomplete; re-plan and re-emit
+QUARANTINE   — pause; needs human audit
+"""