factoryline-code-factory 0.5.1__py3-none-any.whl

factoryline/assembly.py

@@ -0,0 +1,263 @@
+"""factoryline.assembly — line the Lego pieces up.
+
+factoryline drives whichever modules are installed by shelling out to their CLIs.
+It hard-depends on none of them. A missing module is simply a stud with nothing
+plugged in — the chain reports it and continues with what's present. This is what
+makes the factory portable: any IDE/agent/OS that can run a subprocess can drive it.
+"""
+from __future__ import annotations
+import shutil
+import subprocess
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from .contract import MODULES, STAGES, ensure_layout, Receipt
+from .meter import MeterLog, StageTiming, stopwatch
+from .attribution import Attribution, FailureClass
+
+
+@dataclass
+class ModuleStatus:
+    name: str
+    cli: str
+    installed: bool
+    role: str
+
+
+def detect() -> list[ModuleStatus]:
+    """Which Lego pieces are plugged in on this machine."""
+    out = []
+    for name, meta in MODULES.items():
+        out.append(ModuleStatus(
+            name=name, cli=meta["cli"],
+            installed=shutil.which(meta["cli"]) is not None,
+            role=meta["role"]))
+    return out
+
+
+def _run_cli(cli: str, args: list[str], cwd: Path) -> tuple[bool, str]:
+    try:
+        proc = subprocess.run([cli, *args], cwd=str(cwd),
+                              capture_output=True, text=True, timeout=300)
+        # Parse structured evidence before truncating anything for the receipt.
+        return proc.returncode == 0, proc.stdout + proc.stderr
+    except FileNotFoundError:
+        return False, f"{cli} not installed"
+    except subprocess.TimeoutExpired:
+        return False, f"{cli} timed out"
+
+
+def _attribution_from_output(output: str) -> dict | None:
+    """Find a structured attribution block in a CLI's JSON output."""
+    decoder = __import__("json").JSONDecoder()
+    for offset, char in enumerate(output):
+        if char != "{":
+            continue
+        try:
+            payload, _ = decoder.raw_decode(output[offset:])
+        except ValueError:
+            continue
+        if isinstance(payload, dict):
+            raw = payload.get("attribution")
+            if isinstance(raw, dict):
+                Attribution.from_dict(raw)
+                return raw
+    return None
+
+
+# The default pipeline: (module, cli-args-template). {f} = feature.
+# Only stages whose module is installed run; UI stage runs only if smoke/<f>.ui exists.
+DEFAULT_CHAIN = [
+    ("specline",  ["strict", "{f}", "--json"]),
+    ("specline",  ["verify-validators", "{f}", "--json"]),
+    ("specline",  ["gate", "spec", "{f}"]),
+    ("specline",  ["tasks", "{f}"]),
+    ("specline",  ["gate", "plan", "{f}"]),
+    ("forgeline", ["architect", "{f}", "{f}.ssat.yaml"]),
+    ("forgeline", ["review", "{f}", "{f}.ssat.yaml"]),
+    ("forgeline", ["arch-gate", "{f}", "{f}.ssat.yaml"]),
+    ("forgeline", ["verify-tests", "{f}", "{f}.ssat.yaml"]),
+    ("forgeline", ["smoke", "{f}"]),
+    ("hsf",       ["compile", "specs/{f}.yaml"]),
+    ("forgeline", ["ship", "{f}"]),
+]
+
+
+def _stage_order(module: str, stage: str) -> tuple[int, str, str]:
+    """Return canonical pipeline order for a module stage.
+
+    Receipt rollups can arrive in display order, filesystem timestamp order, or
+    mixed legacy spellings. Failure diagnosis still follows pipeline order:
+    instrument verification precedes trusting runtime smoke output.
+    """
+    normalized = stage.replace("_", "-")
+    order = {
+        (mod, args[0].replace("_", "-")): index
+        for index, (mod, args) in enumerate(DEFAULT_CHAIN)
+    }
+    return (order.get((module, normalized), len(DEFAULT_CHAIN)), module, normalized)
+
+
+def assemble(root: Path, feature: str, chain=None, dry_run: bool = False) -> dict:
+    """Run the assembly line for a feature. Returns a per-stage report.
+    Missing modules are skipped with a clear note (Lego stud left open)."""
+    root = Path(root); ensure_layout(root)
+    chain = chain or DEFAULT_CHAIN
+    installed = {m.name: m for m in detect()}
+    meterlog = MeterLog(root)
+    report = {"feature": feature, "root": str(root), "stages": [], "dry_run": dry_run}
+
+    spec_path = root / "specs" / f"{feature}.md"
+    if not dry_run and not spec_path.exists() and installed["specline"].installed:
+        with stopwatch() as sw:
+            ok, out = _run_cli(MODULES["specline"]["cli"], ["new", feature], root)
+        Receipt(module="specline", stage="new", feature=feature, ok=ok,
+                outputs={"log_tail": out[-2000:]}).write(root)
+        report["stages"].append({"module": "specline", "stage": "new",
+                                 "status": "ok" if ok else "failed", "wall_ms": sw.wall_ms})
+        if not ok:
+            report["halted_at"] = "specline:new"
+        else:
+            report["paused_at"] = "author_spec"
+            report["next_command"] = f"edit specs/{feature}.md and plans/{feature}.md, then rerun factory assemble {feature}"
+        report["rollup"] = rollup_attributions(report["stages"])
+        return report
+
+    for module, args_tmpl in chain:
+        cli = MODULES[module]["cli"]
+        present = installed[module].installed
+        args = [a.replace("{f}", feature) for a in args_tmpl]
+        stage_name = args[0]
+        if not present:
+            report["stages"].append({"module": module, "stage": stage_name,
+                                     "status": "skipped", "reason": f"{cli} not installed"})
+            continue
+        if not dry_run and module == "forgeline" and stage_name == "architect":
+            ssat = root / f"{feature}.ssat.yaml"
+            state_path = root / ".forge" / feature / "state.json"
+            state = None
+            if state_path.exists():
+                try:
+                    state = json.loads(state_path.read_text(encoding="utf-8")).get("state")
+                except (OSError, ValueError):
+                    state = None
+            if not ssat.exists():
+                report["paused_at"] = "architecture_contract"
+                report["next_command"] = f"write {feature}.ssat.yaml, then run forge expand {feature}"
+                break
+            if state in {None, "intent"}:
+                ok, out = _run_cli(cli, ["expand", feature], root)
+                Receipt(module=module, stage="expand", feature=feature, ok=ok,
+                        outputs={"log_tail": out[-2000:]}).write(root)
+                report["stages"].append({"module": module, "stage": "expand", "status": "ok" if ok else "failed"})
+                report["paused_at"] = "architecture_approval"
+                report["next_command"] = f"forge gate architected {feature}"
+                break
+            if state == "expanded":
+                report["paused_at"] = "architecture_approval"
+                report["next_command"] = f"forge gate architected {feature}"
+                break
+        if not dry_run and module == "forgeline" and stage_name == "review":
+            state_path = root / ".forge" / feature / "state.json"
+            if state_path.exists():
+                state = json.loads(state_path.read_text(encoding="utf-8")).get("state")
+                if state == "scaffolded":
+                    report["paused_at"] = "implementation_fill"
+                    report["next_command"] = f"implement the scaffold, then run forge fill {feature} {feature}.ssat.yaml"
+                    break
+        if not dry_run and module == "hsf" and stage_name == "compile" and not (root / f"specs/{feature}.yaml").exists():
+            report["stages"].append({"module": module, "stage": stage_name,
+                                     "status": "skipped", "reason": "no deterministic decision spec"})
+            continue
+        if dry_run:
+            report["stages"].append({"module": module, "stage": stage_name,
+                                     "status": "would-run", "cmd": f"{cli} {' '.join(args)}"})
+            continue
+        with stopwatch() as sw:
+            ok, out = _run_cli(cli, args, root)
+        attribution_block = _attribution_from_output(out)
+        meterlog.record(StageTiming(module, stage_name, sw.wall_ms, 0, 0, 0, ok))
+        Receipt(module=module, stage=stage_name, feature=feature, ok=ok,
+                outputs={"log_tail": out[-2000:]},
+                attribution=attribution_block).write(root)
+        report["stages"].append({"module": module, "stage": stage_name,
+                                 "status": "ok" if ok else "failed",
+                                 "wall_ms": sw.wall_ms,
+                                 "attribution": attribution_block})
+        if not ok:
+            report["halted_at"] = f"{module}:{stage_name}"
+            break
+    report["rollup"] = rollup_attributions(report["stages"])
+    return report
+
+
+def rollup_receipts(root: Path, feature: str) -> dict:
+    """Load compatible factory receipts and roll up the latest stage records."""
+    receipt_dir = Path(root) / "receipts"
+    latest: dict[tuple[str, str], tuple[float, dict]] = {}
+    for path in receipt_dir.glob(f"*-{feature}-*.json"):
+        try:
+            payload = __import__("json").loads(path.read_text(encoding="utf-8"))
+            receipt = Receipt.from_dict(payload)
+        except (ValueError, TypeError, OSError):
+            continue
+        latest[(receipt.module, receipt.stage)] = (
+            path.stat().st_mtime,
+            {
+                "module": receipt.module,
+                "stage": receipt.stage,
+                "status": "ok" if receipt.ok else "failed",
+                "attribution": receipt.attribution,
+            },
+        )
+    stages = [item[1] for item in sorted(latest.values(), key=lambda item: item[0])]
+    return rollup_attributions(stages)
+
+
+def rollup_attributions(stages: list[dict]) -> dict:
+    """Aggregate module attribution with canonical pipeline failure priority.
+
+    Older receipts without attribution remain visible but do not crash the line.
+    The recommendation is always the earliest failing stage, never the worst rate.
+    """
+    rows = []
+    for stage in stages:
+        raw = stage.get("attribution")
+        if not raw:
+            rows.append({
+                **stage,
+                "order": _stage_order(stage["module"], stage["stage"])[0],
+                "rate": None,
+                "dominant_failure_class": None,
+            })
+            continue
+        attr = Attribution.from_dict(raw)
+        dominant = attr.dominant_failure_class()
+        rows.append({
+            **stage,
+            "order": _stage_order(stage["module"], stage["stage"])[0],
+            "rate": attr.rate,
+            "n_checked": attr.n_checked,
+            "n_passed": attr.n_passed,
+            "dominant_failure_class": dominant.value if dominant else None,
+        })
+    failures = [
+        row for row in rows
+        if row.get("status") == "failed" or (row["rate"] is not None and row["rate"] < 1.0)
+    ]
+    first = min(
+        failures,
+        key=lambda row: _stage_order(row["module"], row["stage"]),
+        default=None,
+    )
+    return {
+        "stages": rows,
+        "earliest_failing_stage": (
+            f"{first['module']}:{first['stage']}" if first else None
+        ),
+        "recommended_edit_class": (
+            "structural" if first and first["dominant_failure_class"] else
+            "inspect_stage_output" if first else None
+        ),
+    }

factoryline/attribution.py

@@ -0,0 +1,113 @@
+"""Deterministic, build-time failure attribution shared by factory modules."""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from enum import Enum
+from typing import Iterable
+
+
+class FailureClass(str, Enum):
+    AMBIGUOUS_REQUIREMENT = "ambiguous_requirement"
+    UNTYPED_INPUT = "untyped_input"
+    SCOPE_ESCAPE = "scope_escape"
+    INVENTED_PARAM = "invented_param"
+    SIGNATURE_DRIFT = "signature_drift"
+    STUB_UNFILLED = "stub_unfilled"
+    COMPLEXITY_EXCEEDED = "complexity_exceeded"
+    INCONSISTENT_LOGIC = "inconsistent_logic"
+    RUNTIME_CRASH = "runtime_crash"
+    RUNTIME_TIMEOUT = "runtime_timeout"
+    WRONG_OUTPUT = "wrong_output"
+    HOLLOW_TEST = "hollow_test"
+    HOLLOW_MANIFEST = "hollow_manifest"
+    HOLLOW_VALIDATOR = "hollow_validator"
+    HOLLOW_COVERAGE = "hollow_coverage"
+    ACCURACY_REGRESSION = "accuracy_regression"
+    NONDETERMINISM = "nondeterminism"
+    SECURITY_FINDING = "security_finding"
+
+
+@dataclass(frozen=True)
+class UnitResult:
+    unit: str
+    stage: str
+    passed: bool
+    evidence: str
+    failure_class: FailureClass | None = None
+
+    def __post_init__(self) -> None:
+        if not self.unit.strip() or not self.stage.strip():
+            raise ValueError("unit and stage are required")
+        if not self.passed and self.failure_class is None:
+            raise ValueError("failed units require a failure_class")
+        if not self.passed and not self.evidence.strip():
+            raise ValueError("failed units require concrete evidence")
+        if self.passed and self.failure_class is not None:
+            raise ValueError("passed units cannot carry a failure_class")
+
+
+@dataclass
+class Attribution:
+    stage: str
+    n_checked: int
+    n_passed: int
+    units: list[UnitResult]
+
+    def __post_init__(self) -> None:
+        if self.n_checked != len(self.units):
+            raise ValueError("n_checked must equal the number of units")
+        actual_passed = sum(unit.passed for unit in self.units)
+        if self.n_passed != actual_passed:
+            raise ValueError("n_passed must equal the number of passing units")
+
+    @property
+    def rate(self) -> float:
+        return self.n_passed / self.n_checked if self.n_checked else 0.0
+
+    @property
+    def failures(self) -> list[UnitResult]:
+        return [unit for unit in self.units if not unit.passed]
+
+    def dominant_failure_class(self) -> FailureClass | None:
+        counts = {failure_class: 0 for failure_class in FailureClass}
+        for unit in self.failures:
+            counts[unit.failure_class] += 1
+        maximum = max(counts.values(), default=0)
+        if maximum == 0:
+            return None
+        return next(kind for kind in FailureClass if counts[kind] == maximum)
+
+    def to_dict(self) -> dict:
+        payload = asdict(self)
+        payload["rate"] = self.rate
+        dominant = self.dominant_failure_class()
+        payload["dominant_failure_class"] = dominant.value if dominant else None
+        return payload
+
+    @classmethod
+    def from_dict(cls, payload: dict) -> "Attribution":
+        units = [
+            UnitResult(
+                unit=item["unit"],
+                stage=item.get("stage", payload["stage"]),
+                passed=item["passed"],
+                evidence=item.get("evidence", ""),
+                failure_class=(
+                    FailureClass(item["failure_class"])
+                    if item.get("failure_class")
+                    else None
+                ),
+            )
+            for item in payload.get("units", [])
+        ]
+        return cls(
+            stage=payload["stage"],
+            n_checked=payload.get("n_checked", len(units)),
+            n_passed=payload.get("n_passed", sum(unit.passed for unit in units)),
+            units=units,
+        )
+
+
+def attribution(stage: str, units: Iterable[UnitResult]) -> Attribution:
+    materialized = list(units)
+    return Attribution(stage, len(materialized), sum(unit.passed for unit in materialized), materialized)

factoryline/boundary.py

@@ -0,0 +1,23 @@
+"""Guards that keep build-time learning state out of deterministic artifacts."""
+from pathlib import Path
+
+BUILD_TIME_ONLY = {"attribution", "refine", "rejection_ledger", "edit_selection"}
+
+
+def assert_no_attribution_in_artifact(artifact_path: Path) -> None:
+    source = Path(artifact_path).read_text(encoding="utf-8")
+    leaked = sorted(symbol for symbol in BUILD_TIME_ONLY if symbol in source)
+    if leaked:
+        raise ValueError(f"build-time symbols leaked into artifact: {', '.join(leaked)}")
+
+
+def assert_build_metadata_locations(root: Path) -> None:
+    registry = Path(root) / "registry"
+    if not registry.exists():
+        return
+    offenders = [
+        path for path in registry.rglob("*")
+        if path.is_file() and any(token in path.name for token in BUILD_TIME_ONLY)
+    ]
+    if offenders:
+        raise ValueError(f"build metadata found in registry: {offenders}")

factoryline/challenge.py

@@ -0,0 +1,53 @@
+"""Counterfactual integrity challenge for Factoryline proof verification."""
+from __future__ import annotations
+
+from copy import deepcopy
+from pathlib import Path
+import json
+import tempfile
+
+from .proof import load_trace, verify_trace
+
+
+def challenge_trace(trace_path: Path, root: Path | None = None) -> dict:
+    trace_path = Path(trace_path)
+    trace = load_trace(trace_path)
+    baseline = verify_trace(trace_path, root=root)
+    mutations = []
+    variants = []
+
+    empty = deepcopy(trace)
+    empty["nodes"] = []
+    variants.append(("empty_trace", empty))
+
+    bad_hash = deepcopy(trace)
+    if bad_hash.get("nodes"):
+        bad_hash["nodes"][0]["receipt_sha256"] = "0" * 64
+    variants.append(("receipt_hash_tamper", bad_hash))
+
+    if len(trace.get("nodes", [])) > 1:
+        reordered = deepcopy(trace)
+        reordered["nodes"] = list(reversed(reordered["nodes"]))
+        variants.append(("stage_reorder", reordered))
+
+    with tempfile.TemporaryDirectory(prefix="factory-challenge-") as temp:
+        for name, variant in variants:
+            path = Path(temp) / f"{name}.json"
+            path.write_text(json.dumps(variant, indent=2), encoding="utf-8")
+            result = verify_trace(path, root=root)
+            mutations.append({
+                "unit": name,
+                "killed": not result["valid"],
+                "evidence": "; ".join(result["errors"]) if result["errors"] else "mutant incorrectly verified",
+            })
+    killed = sum(bool(item["killed"]) for item in mutations)
+    return {
+        "schema": "factory.challenge.v1",
+        "brick": "factoryline",
+        "feature": trace.get("feature"),
+        "stage": "proof_integrity_counterfactual",
+        "passed": baseline["valid"] and killed == len(mutations),
+        "mutants_total": len(mutations),
+        "mutants_killed": killed,
+        "mutations": mutations,
+    }