atomadic-forge 0.3.2__py3-none-any.whl

atomadic_forge/__init__.py

@@ -0,0 +1,12 @@
+"""Atomadic Forge — absorb, enforce, emerge.
+
+A monadic-architecture engine for absorbing Python or JavaScript /
+TypeScript repositories into a verified 5-tier layout, enforcing layered
+import discipline, and surfacing emergent compositions across the
+resulting catalog.
+
+Public version surface only — every symbol lives in its tier package and
+is re-exported lazily by the CLI.
+"""
+
+__version__ = "0.3.2"

atomadic_forge/__main__.py

@@ -0,0 +1,5 @@
+"""Entry for ``python -m atomadic_forge``."""
+from .a4_sy_orchestration.cli import main
+
+if __name__ == "__main__":
+    main()

atomadic_forge/a0_qk_constants/__init__.py

@@ -0,0 +1 @@
+"""Tier a0 — constants, types, schema names. Zero logic."""

atomadic_forge/a0_qk_constants/agent_plan_schema.py

@@ -0,0 +1,120 @@
+"""Tier a0 — agent-plan/v1 wire-format schema.
+
+Direct response to Codex's follow-up directive after using earlier
+Forge releases:
+
+  > 'Make Forge output \"next best action cards.\" The active agent
+  >  then does what agents are good at: inspect files, edit
+  >  carefully, run tests, decide whether the suggestion was
+  >  actually good. Forge stays the architectural conscience and
+  >  candidate generator.'
+
+Where ``agent_summary/v1`` (prior commit) was a compact dashboard,
+``agent_plan/v1`` is the operational manifest the agent actually
+executes against. Each ``AgentActionCard`` is a bounded, named,
+applyable proposal: id, why, write_scope, validation commands,
+risk, and whether Forge itself can apply it via existing verbs.
+
+a0 invariant: this file holds only TypedDicts + constant strings.
+No logic. Imports limited to ``__future__`` and ``typing``.
+"""
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+SCHEMA_VERSION_AGENT_PLAN_V1 = "atomadic-forge.agent_plan/v1"
+SCHEMA_VERSION_AGENT_ACTION_V1 = "atomadic-forge.agent_action/v1"
+
+
+# Card kinds — pinned for downstream filtering. Adding a new kind is
+# additive; renaming or removing one is a major schema bump.
+ACTION_KINDS: tuple[str, ...] = (
+    "operational",      # CI / changelog / README / tests-present gaps
+    "architectural",    # wire violations, F-coded
+    "composition",      # emergent — symbol chains
+    "synthesis",        # synergy — feature-pair adapters
+    "release",          # final-mile (sign Receipt, gate certify ≥ N)
+)
+
+# Plan modes — the agent declares what it wants to do.
+PLAN_MODES: tuple[str, ...] = (
+    "improve",   # operate on the existing repo in-place
+    "absorb",    # take a flat repo and emit a new tier-organized package
+)
+
+# Risk levels — drives the agent's confirmation policy.
+RISK_LEVELS: tuple[str, ...] = ("low", "medium", "high")
+
+
+class AgentActionCard(TypedDict, total=False):
+    """One bounded proposal for the agent to inspect, edit, apply.
+
+    Required fields:
+      schema_version  — atomadic-forge.agent_action/v1
+      id              — stable slug (e.g. 'fix-wire-F0042-helper-py');
+                        the agent uses this in `auto step <id>`
+      kind            — one of ACTION_KINDS
+      title           — one-line human label
+      why             — 1-3 sentence justification (concrete, no fluff)
+      risk            — one of RISK_LEVELS
+      applyable       — true when Forge has a verb that can execute this
+                        unattended; false means hand to the agent
+
+    Optional but strongly encouraged:
+      write_scope     — list of file globs the action will touch
+      commands        — list of validation commands the agent should
+                        run AFTER applying (pytest, forge wire, etc.)
+      related_fcodes  — F-codes this action resolves
+      next_command    — the single shell command to execute the action
+      sample_path     — representative file (when applicable)
+      score_delta_estimate — expected certify score increase (heuristic)
+    """
+    schema_version: str
+    id: str
+    kind: str
+    title: str
+    why: str
+    risk: str
+    applyable: bool
+    write_scope: list[str]
+    commands: list[str]
+    related_fcodes: list[str]
+    next_command: str
+    sample_path: str | None
+    score_delta_estimate: int
+
+
+class AgentPlan(TypedDict, total=False):
+    """The plan envelope: ordered top-N actions + meta.
+
+    Required:
+      schema_version, generated_at_utc, verdict, goal, mode,
+      top_actions, project_root.
+    """
+    schema_version: str
+    generated_at_utc: str
+    verdict: Literal["PASS", "FAIL", "REFINE", "QUARANTINE"]
+    goal: str
+    mode: str                    # one of PLAN_MODES
+    project_root: str
+    top_actions: list[AgentActionCard]
+    action_count: int            # full count regardless of top_n cap
+    applyable_count: int
+    next_command: str
+    # Codex feedback: surface the certify score on the plan envelope
+    # so MCP _summary digests don't have to guess. None when no
+    # certify_report fed the plan.
+    score: float | None
+    # Provenance — what scans fed into this plan.
+    sources: dict[str, str]      # {source_name: schema_version}
+
+
+REQUIRED_PLAN_FIELDS: tuple[str, ...] = (
+    "schema_version",
+    "generated_at_utc",
+    "verdict",
+    "goal",
+    "mode",
+    "project_root",
+    "top_actions",
+)

atomadic_forge/a0_qk_constants/commandsmith_types.py

@@ -0,0 +1,49 @@
+"""Tier a0 — types for the Commandsmith CLI command-management phase.
+
+Commandsmith discovers Python modules that expose CLI commands (existing
+or freshly assimilated) and emits:
+
+  1. A registry manifest (JSON) describing every known command.
+  2. An auto-wired Python registry module that registers all commands on a
+     Typer app (replacing the hand-maintained ``register_commands`` shim).
+  3. Per-command Markdown docs and an INDEX.
+
+These TypedDicts are the wire format for that pipeline.  No logic here —
+only data shapes.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+CommandSurface = Literal["typer_app", "register_fn", "wrapped_class"]
+
+
+class CommandSignatureCard(TypedDict):
+    """One sub-command's parameter signature as a small dict-of-strings."""
+
+    name: str
+    parameters: list[str]   # e.g. ["repo: Path", "--tier (a0|a1|...): str"]
+    return_type: str        # e.g. "ReconReport"
+    docstring: str
+
+
+class RegisteredCommandCard(TypedDict):
+    """Static description of one CLI command discovered by Commandsmith."""
+
+    name: str                       # CLI verb (e.g. "cherry-pick")
+    module: str                     # Python module path
+    surface: CommandSurface         # how the module exposes commands
+    help_text: str                  # one-line description
+    hidden: bool
+    sub_commands: list[CommandSignatureCard]
+    source_root: str                # which root contributed it ("atomadic_forge_seed", "atomadic_v2", ...)
+
+
+class RegistryManifestCard(TypedDict):
+    """Persistent registry of every command Commandsmith has wired."""
+
+    schema_version: str            # "atomadic-forge.commandsmith.registry/v1"
+    generated_at_utc: str
+    commands: list[RegisteredCommandCard]
+    smoke_results: dict[str, bool]  # cmd-name -> --help exit 0?

atomadic_forge/a0_qk_constants/config_defaults.py

@@ -0,0 +1,38 @@
+"""Tier a0 — config defaults and file-location constants for Atomadic Forge."""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class ForgeConfig(TypedDict, total=False):
+    provider: str
+    ollama_url: str
+    ollama_model: str
+    gemini_key: str | None
+    anthropic_key: str | None
+    openai_key: str | None
+    default_target_score: float
+    auto_apply: bool
+    output_dir: str
+    sources_dir: str
+    package_prefix: str
+
+
+DEFAULT_CONFIG: ForgeConfig = {
+    "provider": "auto",
+    "ollama_url": "http://localhost:11434",
+    "ollama_model": "mistral:7b-instruct",
+    "gemini_key": None,
+    "anthropic_key": None,
+    "openai_key": None,
+    "default_target_score": 75.0,
+    "auto_apply": False,
+    "output_dir": "./forged",
+    "sources_dir": "./sources",
+    "package_prefix": "forged",
+}
+
+CONFIG_FILE_NAME = "config.json"
+GLOBAL_CONFIG_DIR = "~/.atomadic-forge"
+LOCAL_CONFIG_DIR = ".atomadic-forge"

atomadic_forge/a0_qk_constants/emergent_types.py

@@ -0,0 +1,77 @@
+"""Tier a0 — types for the Emergent Behaviors Scan.
+
+Emergent Scan reads the existing tier-organized catalog and synthesizes
+*new* features by composing components that nobody wired together yet.
+
+Pipeline:
+
+  symbols → signatures (a1) → composition graph (a1) → candidates (a1)
+                                                         ↓
+                                       optional synthesis (a1) → a3 feature
+
+These TypedDicts are the wire format between those steps.  No logic here.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+Tier = Literal[
+    "a0_qk_constants",
+    "a1_at_functions",
+    "a2_mo_composites",
+    "a3_og_features",
+    "a4_sy_orchestration",
+]
+
+
+class SymbolSignatureCard(TypedDict):
+    """One callable's typed surface, tier, and domain tag."""
+
+    name: str                     # bare function/class name (e.g. ``infer_tier``)
+    qualname: str                 # module-qualified (e.g. ``atomadic_forge.a1_at_functions.foo.bar``)
+    module: str                   # importable module path
+    tier: str                     # one of Tier
+    domain: str                   # heuristic group (``kg``, ``swarm``, ``cherry`` …)
+    inputs: list[tuple[str, str]] # [(param_name, type_annotation_text), …]
+    output: str                   # return annotation text (or "Any")
+    is_pure: bool                 # heuristic: no obvious I/O / mutable state
+    docstring: str                # one-line
+
+
+class CompositionChain(TypedDict):
+    """An ordered chain of symbols where each output feeds the next."""
+
+    chain: list[str]              # qualnames in execution order
+    bridges: list[str]            # type-text describing each consumed-output edge
+    tiers: list[str]              # tier of each step
+    domains: list[str]            # domain tag of each step
+    crosses_domains: int          # number of distinct domains involved
+    crosses_tiers: int            # number of distinct tiers involved
+    final_output_type: str
+    pure: bool                    # all steps inferred pure
+
+
+class EmergentCandidateCard(TypedDict):
+    """A scored synthesis candidate ready for review or materialisation."""
+
+    candidate_id: str             # short hash identifier
+    name: str                     # heuristic kebab-case name
+    summary: str                  # 1-line description
+    chain: CompositionChain
+    score: float                  # 0..100
+    score_breakdown: dict[str, float]
+    suggested_tier: str
+    novelty_signals: list[str]    # why this is "emergent"
+
+
+class EmergentScanReport(TypedDict):
+    """Top-level wire format produced by ``atomadic-forge emergent scan --json``."""
+
+    schema_version: str           # "atomadic-forge.emergent.scan/v1"
+    generated_at_utc: str
+    catalog_size: int
+    chain_count_considered: int
+    candidates: list[EmergentCandidateCard]
+    domain_inventory: dict[str, int]
+    tier_inventory: dict[str, int]

atomadic_forge/a0_qk_constants/error_codes.py

@@ -0,0 +1,296 @@
+"""Tier a0 — F-code registry: stable, citeable error codes.
+
+Golden Path Lane A W5 deliverable. Every error Forge surfaces (wire
+violations, certify failures, scout misclassifications, …) carries an
+``F-code`` of the form ``F0042``: a 4-digit, zero-padded, fixed
+integer that is **never reused or renumbered**. Once an F-code is
+assigned to a class of error, that mapping is part of the schema
+contract — the same way ``schema_version`` is.
+
+Why F-codes:
+  * Linker-style citeability — a CI report can say "F0042 occurred 3
+    times" without leaking the underlying message string, which
+    reviewers and tooling can grep / pivot / dashboards on.
+  * Machine-applicable ``--fix`` — Lane A W6's ``forge enforce``
+    routes by F-code: F0042 has a known mechanical fix (move the
+    importing file up to the higher tier), F0050 (no README) has
+    another, etc.
+  * Forward-compat — adding an F-code is additive. Removing or
+    renumbering an F-code is a major schema bump.
+  * Internationalization-ready — the message string can change per
+    locale; the F-code stays.
+
+Registry convention:
+  F0001..F0009  — scout / classification (info)
+  F0010..F0019  — cherry-pick (warn)
+  F0040..F0049  — wire / upward-import violations  ← W5 seeds these
+  F0050..F0059  — certify axis failures            ← W5 seeds these
+  F0060..F0069  — stub detection
+  F0070..F0079  — import-repair
+  F0080..F0089  — assimilate conflicts
+  F0090..F0099  — receipt / signing
+
+Pure data: this module imports only ``__future__`` and ``typing``.
+The lookup helpers are pure.
+"""
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+FCodeSeverity = Literal["info", "warn", "error"]
+
+
+class FCode(TypedDict):
+    """One entry in the F-code registry.
+
+    Fields:
+      code              — 'F' + 4 zero-padded digits (e.g. 'F0042')
+      name              — short kebab-case slug (stable; never renamed)
+      severity          — info | warn | error
+      title             — one-line human label (may be localized)
+      hint_key          — name of an a1.error_hints template; '' for none
+      auto_fixable      — when True, Lane A W6 'forge enforce' has a
+                          mechanical fix path
+      doc_anchor        — section anchor in docs/F_CODES.md (forthcoming)
+    """
+    code: str
+    name: str
+    severity: FCodeSeverity
+    title: str
+    hint_key: str
+    auto_fixable: bool
+    doc_anchor: str
+
+
+F_CODE_REGISTRY: dict[str, FCode] = {
+    # ---- Wire / upward-import violations (F0040-F0049) ----
+    "F0040": FCode(
+        code="F0040",
+        name="a0-cannot-import-anything",
+        severity="error",
+        title="a0_qk_constants must not import any other tier (a0 holds zero logic).",
+        hint_key="wire_fail_with_violations",
+        auto_fixable=False,
+        doc_anchor="f0040-a0-cannot-import-anything",
+    ),
+    "F0041": FCode(
+        code="F0041",
+        name="a1-imports-a2",
+        severity="error",
+        title="a1_at_functions imports from a2_mo_composites (upward).",
+        hint_key="wire_fail_with_violations",
+        auto_fixable=True,
+        doc_anchor="f0041-a1-imports-a2",
+    ),
+    "F0042": FCode(
+        code="F0042",
+        name="a1-imports-a3",
+        severity="error",
+        title="a1_at_functions imports from a3_og_features (upward).",
+        hint_key="wire_fail_with_violations",
+        auto_fixable=True,
+        doc_anchor="f0042-a1-imports-a3",
+    ),
+    "F0043": FCode(
+        code="F0043",
+        name="a1-imports-a4",
+        severity="error",
+        title="a1_at_functions imports from a4_sy_orchestration (upward).",
+        hint_key="wire_fail_with_violations",
+        auto_fixable=True,
+        doc_anchor="f0043-a1-imports-a4",
+    ),
+    "F0044": FCode(
+        code="F0044",
+        name="a2-imports-a3",
+        severity="error",
+        title="a2_mo_composites imports from a3_og_features (upward).",
+        hint_key="wire_fail_with_violations",
+        auto_fixable=True,
+        doc_anchor="f0044-a2-imports-a3",
+    ),
+    "F0045": FCode(
+        code="F0045",
+        name="a2-imports-a4",
+        severity="error",
+        title="a2_mo_composites imports from a4_sy_orchestration (upward).",
+        hint_key="wire_fail_with_violations",
+        auto_fixable=True,
+        doc_anchor="f0045-a2-imports-a4",
+    ),
+    "F0046": FCode(
+        code="F0046",
+        name="a3-imports-a4",
+        severity="error",
+        title="a3_og_features imports from a4_sy_orchestration (upward).",
+        hint_key="wire_fail_with_violations",
+        auto_fixable=True,
+        doc_anchor="f0046-a3-imports-a4",
+    ),
+    "F0049": FCode(
+        code="F0049",
+        name="unknown-tier-violation",
+        severity="error",
+        title="Upward import detected but tier shape is non-canonical; review manually.",
+        hint_key="wire_fail_with_violations",
+        auto_fixable=False,
+        doc_anchor="f0049-unknown-tier-violation",
+    ),
+    # ---- Certify axis failures (F0050-F0059) ----
+    "F0050": FCode(
+        code="F0050",
+        name="documentation-missing",
+        severity="error",
+        title="Documentation axis FAIL: no README.md and < 2 docs/*.md files.",
+        hint_key="certify_below_threshold",
+        auto_fixable=True,
+        doc_anchor="f0050-documentation-missing",
+    ),
+    "F0051": FCode(
+        code="F0051",
+        name="tests-missing",
+        severity="error",
+        title="Tests axis FAIL: no tests/test_*.py or tests/*_test.py present.",
+        hint_key="certify_below_threshold",
+        auto_fixable=False,
+        doc_anchor="f0051-tests-missing",
+    ),
+    "F0052": FCode(
+        code="F0052",
+        name="tier-layout-incomplete",
+        severity="error",
+        title="Tier-layout axis FAIL: fewer than 3 tier directories present.",
+        hint_key="no_tier_dirs",
+        auto_fixable=False,
+        doc_anchor="f0052-tier-layout-incomplete",
+    ),
+    "F0053": FCode(
+        code="F0053",
+        name="upward-imports-present",
+        severity="error",
+        title="Import-discipline axis FAIL: at least one wire violation present.",
+        hint_key="wire_fail_with_violations",
+        auto_fixable=True,
+        doc_anchor="f0053-upward-imports-present",
+    ),
+    # ---- Sidecar drift (F0100-F0109; Lane D W8/W11) ----
+    "F0100": FCode(
+        code="F0100",
+        name="sidecar-source-unparseable",
+        severity="error",
+        title="Sidecar present but the source file did not parse.",
+        hint_key="",
+        auto_fixable=False,
+        doc_anchor="f0100-sidecar-source-unparseable",
+    ),
+    "F0101": FCode(
+        code="F0101",
+        name="sidecar-declares-missing-symbol",
+        severity="error",
+        title="Sidecar declares a symbol the source file doesn't have.",
+        hint_key="",
+        auto_fixable=False,
+        doc_anchor="f0101-sidecar-declares-missing-symbol",
+    ),
+    "F0102": FCode(
+        code="F0102",
+        name="sidecar-coverage-incomplete",
+        severity="warn",
+        title="Source has a public symbol the sidecar didn't declare (advisory).",
+        hint_key="",
+        auto_fixable=False,
+        doc_anchor="f0102-sidecar-coverage-incomplete",
+    ),
+    "F0103": FCode(
+        code="F0103",
+        name="sidecar-pure-violates-purity",
+        severity="error",
+        title="Sidecar declares Pure but source uses I/O / network / non-deterministic input.",
+        hint_key="",
+        auto_fixable=False,
+        doc_anchor="f0103-sidecar-pure-violates-purity",
+    ),
+    "F0106": FCode(
+        code="F0106",
+        name="sidecar-tier-mismatch",
+        severity="warn",
+        title="Sidecar declares a tier different from the source file's actual path tier.",
+        hint_key="",
+        auto_fixable=False,
+        doc_anchor="f0106-sidecar-tier-mismatch",
+    ),
+}
+
+
+# Sidecar S-code → F-code mapping. Exposed so the validator (a1) can
+# promote local drift labels into the global F-code namespace
+# without re-importing this whole registry.
+SIDECAR_S_TO_F: dict[str, str] = {
+    "S0000": "F0100",
+    "S0001": "F0101",
+    "S0002": "F0102",
+    "S0003": "F0103",
+    "S0006": "F0106",
+}
+"""Canonical F-code registry. Adding a new code is additive; renaming
+or renumbering is a major schema bump (and requires updating every
+test and consumer). See the H1 pre-audit smoke for the drift sentinel.
+"""
+
+
+_TIER_PAIR_TO_FCODE: dict[tuple[str, str], str] = {
+    # (from_tier, to_tier) → F-code. a0 is special-cased below.
+    ("a1_at_functions", "a2_mo_composites"):    "F0041",
+    ("a1_at_functions", "a3_og_features"):      "F0042",
+    ("a1_at_functions", "a4_sy_orchestration"): "F0043",
+    ("a2_mo_composites", "a3_og_features"):     "F0044",
+    ("a2_mo_composites", "a4_sy_orchestration"): "F0045",
+    ("a3_og_features", "a4_sy_orchestration"):   "F0046",
+}
+
+
+def fcode_for_tier_violation(from_tier: str, to_tier: str) -> str:
+    """Map a (from, to) tier pair to its registered F-code.
+
+    Returns:
+      'F0040' when from_tier is a0 (a0 may not import anything)
+      one of F0041..F0046 for the canonical upward-import pairs
+      'F0049' for any other shape (non-canonical tier, mixed-language)
+
+    Pure: O(1) lookup.
+    """
+    if from_tier == "a0_qk_constants":
+        return "F0040"
+    return _TIER_PAIR_TO_FCODE.get((from_tier, to_tier), "F0049")
+
+
+def fcode_for_certify_axis(axis: str) -> str:
+    """Map a certify axis name to its F-code.
+
+    Recognised axis names match the CertifyResult booleans:
+      'documentation_complete'  → F0050
+      'tests_present'           → F0051
+      'tier_layout_present'     → F0052
+      'no_upward_imports'       → F0053
+    Unknown axes return '' (no F-code assigned).
+    """
+    return {
+        "documentation_complete": "F0050",
+        "tests_present":          "F0051",
+        "tier_layout_present":    "F0052",
+        "no_upward_imports":      "F0053",
+    }.get(axis, "")
+
+
+def get_fcode(code: str) -> FCode | None:
+    """Return the registry entry for ``code`` or None if unregistered."""
+    return F_CODE_REGISTRY.get(code)
+
+
+def all_auto_fixable_fcodes() -> tuple[str, ...]:
+    """Return the codes Lane A W6 'forge enforce' has a path for.
+
+    Sorted ascending so consumers get a stable iteration order.
+    """
+    return tuple(sorted(c for c, e in F_CODE_REGISTRY.items()
+                         if e["auto_fixable"]))

atomadic_forge/a0_qk_constants/forge_types.py

@@ -0,0 +1,89 @@
+"""Tier a0 — Forge-specific report shapes.
+
+Wire formats for scout / cherry-pick / wire / certify / assimilate output.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+SymbolKind = Literal["function", "class", "method"]
+
+
+class SymbolRecord(TypedDict):
+    """One callable discovered in a target repo."""
+
+    name: str
+    qualname: str            # e.g. "Counter.incr"
+    kind: SymbolKind
+    file: str                # repo-relative path
+    lineno: int
+    tier_guess: str          # one of TIER_NAMES
+    effects: list[str]       # ["pure"], ["io"], etc.
+    complexity: int          # ast.dump length (cheap proxy)
+    has_self_assign: bool
+
+
+class ScoutReport(TypedDict):
+    schema_version: str       # "atomadic-forge.scout/v1"
+    repo: str
+    file_count: int
+    python_file_count: int
+    symbol_count: int
+    tier_distribution: dict[str, int]
+    effect_distribution: dict[str, int]
+    symbols: list[SymbolRecord]
+    recommendations: list[str]
+
+
+class CherryPickItem(TypedDict):
+    qualname: str
+    target_tier: str
+    confidence: float
+    reasons: list[str]
+
+
+class CherryPickManifest(TypedDict):
+    schema_version: str       # "atomadic-forge.cherry/v1"
+    source_repo: str
+    items: list[CherryPickItem]
+
+
+class WireViolation(TypedDict):
+    file: str
+    from_tier: str
+    to_tier: str
+    imported: str
+    proposed_fix: str         # rewritten import line, or "" if no fix found
+
+
+class WireReport(TypedDict):
+    schema_version: str       # "atomadic-forge.wire/v1"
+    source_dir: str
+    violation_count: int
+    auto_fixable: int
+    violations: list[WireViolation]
+    verdict: Literal["PASS", "FAIL"]
+
+
+class CertifyResult(TypedDict):
+    schema_version: str       # "atomadic-forge.certify/v1"
+    project: str
+    timestamp: str
+    documentation_complete: bool
+    tests_present: bool
+    tier_layout_present: bool
+    no_upward_imports: bool
+    score: float              # 0..100
+    issues: list[str]
+    recommendations: list[str]
+
+
+class AssimilateReport(TypedDict):
+    schema_version: str       # "atomadic-forge.assimilate/v1"
+    target_root: str
+    source_repos: list[str]
+    components_emitted: int
+    tier_distribution: dict[str, int]
+    files_repaired: int
+    digest: str