atomadic-forge 0.3.2__py3-none-any.whl

atomadic_forge/a1_at_functions/scout_walk.py

@@ -0,0 +1,309 @@
+"""Tier a1 — pure repo walker + symbol harvester for the scout phase.
+
+Walks Python AND JavaScript / TypeScript. Each file is classified into a
+monadic tier and reduced to a list of ``symbols`` with the same shape across
+languages so downstream stages (cherry, finalize, certify) work polyglot.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Callable, Iterable
+from pathlib import Path
+
+from ..a0_qk_constants.lang_extensions import (
+    ALL_SOURCE_EXTS,
+    IGNORED_DIRS,
+    JAVASCRIPT_EXTS,
+    PYTHON_EXTS,
+    TYPESCRIPT_EXTS,
+    file_class_for_path,
+    path_parts_contain_ignored_dir,
+)
+from .body_extractor import _detect_state_markers
+from .classify_tier import classify_tier, detect_effects
+from .js_parser import classify_js_tier, detect_js_effects, parse_surface
+
+# Backwards-compatible alias — keep _SKIP_DIRS available for any third-party
+# code that imports it.  The canonical list lives in lang_extensions.IGNORED_DIRS.
+_SKIP_DIRS = IGNORED_DIRS
+
+
+def _under_skip_dir(rel_parts: tuple[str, ...]) -> bool:
+    """Return True if any segment of the path is an ignored directory.
+
+    A leading-dot segment is only treated as ignored when it matches an
+    entry in IGNORED_DIRS (e.g. ``.github``, ``.venv``).  Application
+    folders that legitimately start with a dot (none today, but keeping
+    the door open) won't be skipped just for the leading dot — only for
+    being on the explicit list.
+    """
+    return path_parts_contain_ignored_dir(rel_parts)
+
+
+def iter_python_files(root: Path) -> Iterable[Path]:
+    root = root.resolve()
+    for p in root.rglob("*.py"):
+        if _under_skip_dir(p.relative_to(root).parts):
+            continue
+        if p.name.startswith("_"):
+            continue
+        yield p
+
+
+def iter_source_files(root: Path) -> Iterable[Path]:
+    """Yield every Python / JS / TS file under ``root`` we want to classify.
+
+    Filters out vendored / build / cache directories. Hidden filenames
+    starting with ``_`` (Python convention) are skipped, but JS files
+    starting with ``_`` are kept — the underscore is meaningless in JS.
+    """
+    root = root.resolve()
+    for p in root.rglob("*"):
+        if not p.is_file():
+            continue
+        suffix = p.suffix.lower()
+        if suffix not in ALL_SOURCE_EXTS:
+            continue
+        rel_parts = p.relative_to(root).parts
+        if _under_skip_dir(rel_parts):
+            continue
+        if suffix in PYTHON_EXTS and p.name.startswith("_"):
+            continue
+        yield p
+
+
+def _harvest_python_file(f: Path, rel: str, *, symbols: list[dict],
+                          tier_dist: dict[str, int],
+                          effect_dist: dict[str, int]) -> None:
+    try:
+        text = f.read_text(encoding="utf-8", errors="replace")
+        tree = ast.parse(text, filename=str(f))
+    except (SyntaxError, OSError):
+        return
+    for node in tree.body:
+        if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+            _collect_symbol(symbols, node, rel, kind="function",
+                            qualname=node.name, tier_dist=tier_dist,
+                            effect_dist=effect_dist)
+        elif isinstance(node, ast.ClassDef) and not node.name.startswith("_"):
+            self_assign, class_collect = _detect_state_markers(node)
+            _collect_symbol(symbols, node, rel, kind="class",
+                            qualname=node.name, tier_dist=tier_dist,
+                            effect_dist=effect_dist,
+                            body_signals={
+                                "has_self_assign": self_assign,
+                                "has_class_attr_collections": class_collect,
+                            })
+            for sub in node.body:
+                if isinstance(sub, ast.FunctionDef | ast.AsyncFunctionDef):
+                    if sub.name.startswith("_") and sub.name != "__init__":
+                        continue
+                    _collect_symbol(symbols, sub, rel, kind="method",
+                                    qualname=f"{node.name}.{sub.name}",
+                                    tier_dist=tier_dist,
+                                    effect_dist=effect_dist)
+
+
+def _harvest_js_file(f: Path, rel: str, language: str, *, symbols: list[dict],
+                      tier_dist: dict[str, int],
+                      effect_dist: dict[str, int]) -> None:
+    try:
+        text = f.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return
+    surface = parse_surface(text)
+    file_tier = classify_js_tier(path=rel, surface=surface)
+    file_effects = detect_js_effects(text)
+
+    # Track the file itself as a symbol so even an empty-export module
+    # (e.g. an HTML-glue static page) shows up in scout output.
+    file_record = {
+        "name": f.name,
+        "qualname": f.stem,
+        "kind": "module",
+        "file": rel,
+        "lineno": 1,
+        "tier_guess": file_tier,
+        "suggested_tier": file_tier,
+        "effects": file_effects,
+        "complexity": surface.statement_count,
+        "has_self_assign": False,
+        "language": language,
+        "exports": surface.all_exports,
+        "imports": surface.imports,
+    }
+    symbols.append(file_record)
+    tier_dist[file_tier] = tier_dist.get(file_tier, 0) + 1
+    for e in file_effects:
+        if e in effect_dist:
+            effect_dist[e] += 1
+
+    # Also surface each named export as its own symbol so cherry-pick + emergent
+    # treat JS like Python: pick by qualname.
+    for name in surface.exported_functions:
+        _push_js_symbol(symbols, name, "function", rel, file_tier,
+                         language, ["pure"], tier_dist, effect_dist)
+    for name in surface.exported_classes:
+        _push_js_symbol(symbols, name, "class", rel, file_tier,
+                         language, ["state"], tier_dist, effect_dist)
+    for name in surface.exported_consts:
+        _push_js_symbol(symbols, name, "const", rel, file_tier,
+                         language, ["pure"], tier_dist, effect_dist)
+
+
+def _push_js_symbol(symbols: list[dict], name: str, kind: str, rel: str,
+                     tier: str, language: str, effects: list[str],
+                     tier_dist: dict[str, int],
+                     effect_dist: dict[str, int]) -> None:
+    rec = {
+        "name": name,
+        "qualname": name,
+        "kind": kind,
+        "file": rel,
+        "lineno": 0,
+        "tier_guess": tier,
+        "suggested_tier": tier,
+        "effects": effects,
+        "complexity": 0,
+        "has_self_assign": False,
+        "language": language,
+    }
+    symbols.append(rec)
+    tier_dist[tier] = tier_dist.get(tier, 0) + 1
+    for e in effects:
+        if e in effect_dist:
+            effect_dist[e] += 1
+
+
+def _file_class_counts(root: Path) -> dict[str, int]:
+    """Count every file under ``root`` by class (source / docs / config /
+    asset / other), respecting IGNORED_DIRS.  Used by harvest_repo and
+    by certify so non-source files don't harsh the layout score."""
+    counts = {"source": 0, "documentation": 0, "config": 0, "asset": 0, "other": 0}
+    for p in root.rglob("*"):
+        if not p.is_file():
+            continue
+        rel_parts = p.relative_to(root).parts
+        if _under_skip_dir(rel_parts):
+            continue
+        cls = file_class_for_path(p.as_posix())
+        counts[cls] = counts.get(cls, 0) + 1
+    return counts
+
+
+def harvest_repo(
+    root: Path,
+    *,
+    progress: Callable[[int, int, str], None] | None = None,
+) -> dict:
+    """Walk a repo, classify every public symbol, return a scout-shaped dict.
+
+    ``progress`` (optional): a callback invoked once per source file as
+    ``progress(processed_count, total_count, relative_path)``. Pure
+    function — no I/O of its own. The CLI layer wires this to a stderr
+    reporter; tests can pass a list-appender.
+    """
+    root = Path(root).resolve()
+    src_files = list(iter_source_files(root))
+    total = len(src_files)
+    file_class_counts = _file_class_counts(root)
+    symbols: list[dict] = []
+    tier_dist: dict[str, int] = {}
+    effect_dist: dict[str, int] = {"pure": 0, "state": 0, "io": 0}
+
+    py_count = 0
+    js_count = 0
+    ts_count = 0
+
+    for idx, f in enumerate(src_files, start=1):
+        rel = f.relative_to(root).as_posix()
+        suffix = f.suffix.lower()
+        if suffix in PYTHON_EXTS:
+            py_count += 1
+            _harvest_python_file(f, rel, symbols=symbols,
+                                  tier_dist=tier_dist,
+                                  effect_dist=effect_dist)
+        elif suffix in JAVASCRIPT_EXTS:
+            js_count += 1
+            _harvest_js_file(f, rel, "javascript", symbols=symbols,
+                              tier_dist=tier_dist,
+                              effect_dist=effect_dist)
+        elif suffix in TYPESCRIPT_EXTS:
+            ts_count += 1
+            _harvest_js_file(f, rel, "typescript", symbols=symbols,
+                              tier_dist=tier_dist,
+                              effect_dist=effect_dist)
+        if progress is not None:
+            progress(idx, total, rel)
+
+    languages = {
+        "python": py_count,
+        "javascript": js_count,
+        "typescript": ts_count,
+    }
+    primary = max(languages, key=lambda k: languages[k]) if any(languages.values()) else "python"
+
+    recommendations: list[str] = []
+    if tier_dist.get("a4_sy_orchestration", 0) > tier_dist.get("a1_at_functions", 0):
+        recommendations.append("Top-heavy at a4 — extract pure helpers into a1.")
+    total = sum(effect_dist.values()) or 1
+    if effect_dist["io"] / total > 0.3:
+        recommendations.append("High I/O ratio — consider pushing I/O to a4 boundaries.")
+    if tier_dist.get("a1_at_functions", 0) == 0 and symbols:
+        recommendations.append("No pure functions detected — extract validators/parsers.")
+    if js_count + ts_count > 0 and not any(
+        f"/{t}/" in s["file"] or s["file"].startswith(f"{t}/")
+        for s in symbols if s.get("language") in ("javascript", "typescript")
+        for t in ("a0_qk_constants", "a1_at_functions", "a2_mo_composites",
+                   "a3_og_features", "a4_sy_orchestration")
+    ):
+        recommendations.append(
+            "JS/TS files are not yet split into aN_* tier directories — "
+            "see suggested_tier per file in symbols[]."
+        )
+
+    return {
+        "schema_version": "atomadic-forge.scout/v1",
+        "repo": str(root),
+        # `file_count` is the raw rglob walk (legacy) — matches v1 callers.
+        "file_count": len(list(root.rglob("*"))),
+        # `file_class_counts` excludes IGNORED_DIRS and breaks files into
+        # source / documentation / config / asset / other.  Tier-layout
+        # scoring should use this, not the raw walk.
+        "file_class_counts": file_class_counts,
+        "python_file_count": py_count,
+        "javascript_file_count": js_count,
+        "typescript_file_count": ts_count,
+        "language_distribution": languages,
+        "primary_language": primary,
+        "symbol_count": len(symbols),
+        "tier_distribution": tier_dist,
+        "effect_distribution": effect_dist,
+        "symbols": symbols,
+        "recommendations": recommendations,
+    }
+
+
+def _collect_symbol(symbols: list, node, rel_path: str, *, kind: str,
+                     qualname: str, tier_dist: dict, effect_dist: dict,
+                     body_signals: dict | None = None) -> None:
+    effects = detect_effects(node) if not isinstance(node, ast.ClassDef) else ["pure"]
+    tier = classify_tier(name=qualname, kind=kind, path=rel_path,
+                         body_signals=body_signals)
+    rec = {
+        "name": getattr(node, "name", qualname),
+        "qualname": qualname,
+        "kind": kind,
+        "file": rel_path,
+        "lineno": getattr(node, "lineno", 0),
+        "tier_guess": tier,
+        "effects": effects,
+        "complexity": len(ast.dump(node)),
+        "has_self_assign": bool(body_signals and body_signals.get("has_self_assign")),
+    }
+    symbols.append(rec)
+    tier_dist[tier] = tier_dist.get(tier, 0) + 1
+    for e in effects:
+        if e in effect_dist:
+            effect_dist[e] += 1

atomadic_forge/a1_at_functions/sidecar_parser.py

@@ -0,0 +1,161 @@
+"""Tier a1 — pure .forge sidecar parser (Lane D W8).
+
+Reads a YAML sidecar file and returns a structured ``SidecarFile``
+dict. Validates required fields + effect-kind enum membership.
+Pure: one bounded read; never raises on unknown fields (preserved
+in ``extra``).
+
+Lane D W11 will add the cross-validator (compares the sidecar's
+declared effects against the source AST). Lane D W20 will dispatch
+the ``proves:`` clauses through the Lean4 obligation discharger.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TypedDict
+
+import yaml
+
+from ..a0_qk_constants.sidecar_schema import (
+    REQUIRED_SIDECAR_FIELDS,
+    REQUIRED_SYMBOL_FIELDS,
+    SCHEMA_VERSION_SIDECAR_V1,
+    VALID_EFFECTS,
+    SidecarFile,
+    SidecarSymbol,
+)
+
+
+class SidecarParseError(ValueError):
+    """Raised when a sidecar file is malformed beyond soft recovery."""
+
+
+class ParseResult(TypedDict, total=False):
+    schema_version: str
+    sidecar: SidecarFile | None
+    errors: list[str]
+    warnings: list[str]
+
+
+def parse_sidecar_text(text: str, *, source: str = "<inline>") -> ParseResult:
+    """Parse a YAML sidecar string and return a structured result.
+
+    Returns a ParseResult with sidecar=None + populated errors when
+    the document is unrecoverable; otherwise sidecar is the typed
+    dict and warnings list any soft issues (unknown effect kinds
+    are downgraded to warnings, not errors).
+    """
+    out: ParseResult = {
+        "schema_version": SCHEMA_VERSION_SIDECAR_V1,
+        "sidecar": None,
+        "errors": [],
+        "warnings": [],
+    }
+    try:
+        data = yaml.safe_load(text) or {}
+    except yaml.YAMLError as exc:
+        out["errors"].append(f"YAML parse error in {source}: {exc}")
+        return out
+    if not isinstance(data, dict):
+        out["errors"].append(
+            f"{source}: top-level must be a mapping, got "
+            f"{type(data).__name__}"
+        )
+        return out
+    for f in REQUIRED_SIDECAR_FIELDS:
+        if f not in data:
+            out["errors"].append(f"{source}: missing required field {f!r}")
+    declared_schema = data.get("schema_version", "")
+    if declared_schema and declared_schema != SCHEMA_VERSION_SIDECAR_V1:
+        out["warnings"].append(
+            f"{source}: declares schema_version={declared_schema!r}; "
+            f"expected {SCHEMA_VERSION_SIDECAR_V1!r}"
+        )
+    if out["errors"]:
+        return out
+
+    raw_symbols = data.get("symbols") or []
+    if not isinstance(raw_symbols, list):
+        out["errors"].append(
+            f"{source}: 'symbols' must be a list, got "
+            f"{type(raw_symbols).__name__}"
+        )
+        return out
+    parsed_symbols: list[SidecarSymbol] = []
+    for i, raw in enumerate(raw_symbols):
+        if not isinstance(raw, dict):
+            out["errors"].append(
+                f"{source}: symbols[{i}] must be a mapping"
+            )
+            continue
+        for f in REQUIRED_SYMBOL_FIELDS:
+            if f not in raw:
+                out["errors"].append(
+                    f"{source}: symbols[{i}] missing required {f!r}"
+                )
+        if not isinstance(raw.get("name", ""), str):
+            out["errors"].append(
+                f"{source}: symbols[{i}].name must be a string"
+            )
+            continue
+        effect = str(raw.get("effect", ""))
+        if effect and effect not in VALID_EFFECTS:
+            out["warnings"].append(
+                f"{source}: symbols[{i}] effect={effect!r} not in "
+                f"VALID_EFFECTS — preserved as-is for forward-compat"
+            )
+        sym = SidecarSymbol(name=str(raw["name"]),
+                              effect=effect)  # type: ignore[typeddict-item]
+        if isinstance(raw.get("compose_with"), list):
+            sym["compose_with"] = [str(s) for s in raw["compose_with"]]
+        if isinstance(raw.get("proves"), list):
+            sym["proves"] = [str(s) for s in raw["proves"]]
+        if isinstance(raw.get("tier"), str):
+            sym["tier"] = raw["tier"]
+        if isinstance(raw.get("notes"), list):
+            sym["notes"] = [str(s) for s in raw["notes"]]
+        parsed_symbols.append(sym)
+
+    if out["errors"]:
+        return out
+
+    sidecar: SidecarFile = SidecarFile(
+        schema_version=SCHEMA_VERSION_SIDECAR_V1,
+        target=str(data["target"]),
+        symbols=parsed_symbols,
+    )
+    # Forward-compat: stash any unrecognised top-level keys.
+    known = set(REQUIRED_SIDECAR_FIELDS)
+    extra = {k: v for k, v in data.items() if k not in known}
+    if extra:
+        sidecar["extra"] = extra
+    out["sidecar"] = sidecar
+    return out
+
+
+def parse_sidecar_file(path: Path) -> ParseResult:
+    """Read a sidecar file from disk and parse it."""
+    path = Path(path)
+    if not path.exists():
+        return {
+            "schema_version": SCHEMA_VERSION_SIDECAR_V1,
+            "sidecar": None,
+            "errors": [f"sidecar file not found: {path}"],
+            "warnings": [],
+        }
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        return {
+            "schema_version": SCHEMA_VERSION_SIDECAR_V1,
+            "sidecar": None,
+            "errors": [f"could not read {path}: {exc}"],
+            "warnings": [],
+        }
+    return parse_sidecar_text(text, source=str(path))
+
+
+def find_sidecar_for(source_file: Path) -> Path:
+    """Convention: ``users/auth.py`` → ``users/auth.py.forge``."""
+    p = Path(source_file)
+    return p.with_suffix(p.suffix + ".forge")

atomadic_forge/a1_at_functions/sidecar_validator.py

@@ -0,0 +1,202 @@
+"""Tier a1 — pure .forge sidecar cross-validator (Lane D W11).
+
+Compares a parsed SidecarFile against the source file's AST and
+returns a structured report of mismatches. Catches the seven
+classes of drift the Golden Path names:
+
+  1. sidecar declares a symbol the source doesn't have
+  2. source has a public symbol the sidecar didn't declare
+  3. effect=Pure declared but source uses obvious I/O / network
+  4. effect=Pure declared but source has Mutation patterns
+  5. compose_with names a symbol that doesn't exist in any imported
+     module (best-effort lexical check; not a full resolver)
+  6. tier declared but source path lives in a different tier
+  7. proves clauses naming lemmas with no entry in the local Lean4
+     manifest (W20 — soft-skipped today)
+
+Pure: walks AST + the sidecar dict; no execution, no LLM, no
+network. Soft on parse failures (returns 'failed_to_parse_source').
+"""
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import TypedDict
+
+from ..a0_qk_constants.error_codes import SIDECAR_S_TO_F
+from ..a0_qk_constants.sidecar_schema import SidecarFile
+
+SCHEMA_VERSION_VALIDATE_V1 = "atomadic-forge.sidecar.validate/v1"
+
+
+class ValidationFinding(TypedDict, total=False):
+    code: str          # Drift class label (S0001..S0007) — local
+    f_code: str        # Global F-code (F0100..F0109) — registered
+    severity: str      # 'error' | 'warn' | 'info'
+    symbol: str
+    message: str
+
+
+class ValidationReport(TypedDict, total=False):
+    schema_version: str
+    target: str
+    finding_count: int
+    findings: list[ValidationFinding]
+    verdict: str       # 'PASS' | 'FAIL' | 'unparseable'
+
+
+# Heuristic patterns. Conservative — false positives downgraded to
+# 'warn' rather than 'error' so the validator never blocks merges
+# on its own; F-codes do that.
+_IO_HINTS = ("open(", "read(", "write(", "Path(", ".write_text",
+              ".read_text", "subprocess.", "os.system")
+_NET_HINTS = ("requests.", "urllib.", "http.client", "socket.",
+               "urlopen(", ".post(", ".get(")
+_RANDOM_HINTS = ("random.", "secrets.", "uuid.", "datetime.now(",
+                  "time.time(")
+
+
+def _collect_top_level_symbols(tree: ast.AST) -> dict[str, ast.AST]:
+    """Map name -> AST node for every top-level def / class."""
+    out: dict[str, ast.AST] = {}
+    for node in tree.body if hasattr(tree, "body") else []:  # type: ignore[attr-defined]
+        if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef):
+            if not node.name.startswith("_"):
+                out[node.name] = node
+    return out
+
+
+def _node_source_text(source: str, node: ast.AST) -> str:
+    try:
+        return ast.unparse(node)
+    except Exception:  # noqa: BLE001
+        # Fall back to raw line span when ast.unparse fails.
+        start = (getattr(node, "lineno", 1) or 1) - 1
+        end = (getattr(node, "end_lineno", start + 1) or start + 1)
+        return "\n".join(source.splitlines()[start:end])
+
+
+def _check_pure_against_source(node_text: str) -> list[str]:
+    """Return drift-hint strings if a Pure-declared symbol does
+    obviously-non-pure things in its body."""
+    hits: list[str] = []
+    if any(h in node_text for h in _NET_HINTS):
+        hits.append("network call detected")
+    if any(h in node_text for h in _IO_HINTS):
+        hits.append("filesystem / IO call detected")
+    if any(h in node_text for h in _RANDOM_HINTS):
+        hits.append("non-deterministic input detected")
+    return hits
+
+
+def _detect_tier(path: str) -> str | None:
+    parts = Path(path).parts
+    for p in parts:
+        if p in ("a0_qk_constants", "a1_at_functions",
+                  "a2_mo_composites", "a3_og_features",
+                  "a4_sy_orchestration"):
+            return p
+    return None
+
+
+def validate_sidecar(
+    sidecar: SidecarFile,
+    *,
+    source_text: str,
+    source_path: Path | str | None = None,
+) -> ValidationReport:
+    """Cross-check ``sidecar`` against the actual source.
+
+    Pure: parses ``source_text`` once + walks both inputs. Returns
+    a structured report; never raises.
+    """
+    findings: list[ValidationFinding] = []
+    target = sidecar.get("target", "<unknown>")
+
+    try:
+        tree = ast.parse(source_text)
+    except SyntaxError as exc:
+        return ValidationReport(
+            schema_version=SCHEMA_VERSION_VALIDATE_V1,
+            target=target,
+            finding_count=1,
+            findings=[ValidationFinding(
+                code="S0000",
+                severity="error",
+                symbol="(file)",
+                message=f"source did not parse: {exc}",
+            )],
+            verdict="unparseable",
+        )
+
+    symbols = _collect_top_level_symbols(tree)
+    declared = {s.get("name", ""): s for s in sidecar.get("symbols") or []}
+
+    # S0001 — sidecar declares a symbol the source doesn't have.
+    for name in declared:
+        if name and name not in symbols:
+            findings.append(ValidationFinding(
+                code="S0001", severity="error", symbol=name,
+                message=f"sidecar declares {name!r} but source has no "
+                         "top-level public symbol with that name",
+            ))
+
+    # S0002 — source has a public symbol the sidecar didn't declare.
+    for name in symbols:
+        if name not in declared:
+            findings.append(ValidationFinding(
+                code="S0002", severity="warn", symbol=name,
+                message=f"source has public symbol {name!r} not declared "
+                         "in sidecar (gradual coverage is OK; this is "
+                         "advisory)",
+            ))
+
+    # S0003 + S0004 — Pure declared but source does I/O / non-determinism.
+    for name, decl in declared.items():
+        if name not in symbols:
+            continue
+        if decl.get("effect") != "Pure":
+            continue
+        node_text = _node_source_text(source_text, symbols[name])
+        hits = _check_pure_against_source(node_text)
+        for h in hits:
+            findings.append(ValidationFinding(
+                code="S0003", severity="error", symbol=name,
+                message=f"Pure-declared symbol {name!r} appears to "
+                         f"violate purity: {h}",
+            ))
+
+    # S0006 — declared tier vs detected path tier.
+    if source_path is not None:
+        path_tier = _detect_tier(str(source_path))
+        for name, decl in declared.items():
+            declared_tier = decl.get("tier")
+            if declared_tier and path_tier and declared_tier != path_tier:
+                findings.append(ValidationFinding(
+                    code="S0006", severity="warn", symbol=name,
+                    message=f"sidecar declares tier={declared_tier!r} "
+                             f"but source lives in tier {path_tier!r}",
+                ))
+
+    # S0005 / S0007 — compose_with name resolution + Lean4 proves
+    # discharge are reserved for Lane D W20 (Bao-Rompf checker).
+    # Today we record but don't enforce.
+
+    # Promote each S-code to its registered F-code so downstream
+    # tools (forge audit / agent_summary / score_patch) can address
+    # sidecar drift in the same namespace as wire violations.
+    for f in findings:
+        s_code = f.get("code", "")
+        if s_code in SIDECAR_S_TO_F:
+            f["f_code"] = SIDECAR_S_TO_F[s_code]
+
+    error_count = sum(1 for f in findings if f.get("severity") == "error")
+    verdict = "PASS" if error_count == 0 else "FAIL"
+
+    return ValidationReport(
+        schema_version=SCHEMA_VERSION_VALIDATE_V1,
+        target=target,
+        finding_count=len(findings),
+        findings=findings,
+        verdict=verdict,
+    )