rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/interfaces/layout.py

@@ -0,0 +1,410 @@
+"""Folder-schema parser + validator (LAYOUT-SCHEMA).
+
+Checks a tree against layout_schema.yaml, derives and verifies
+.gitignore from tracked flags, and refuses newer-than-known version
+stamps loudly instead of misreading. Policy files use the
+zero-silent-defaults rule: template ships defaults, required entries
+must be present and non-empty.
+"""
+
+import copy
+import re
+from pathlib import Path
+
+from ruamel.yaml import YAML
+
+from .errors import ContractError
+
+SCHEMA_VERSION = 1
+
+_SCHEMA_PATH = Path(__file__).parent / "layout_schema.yaml"
+_VERSION_FILENAME = "layout.version"
+_GITIGNORE_HEADER = (
+    "# Engine exhaust (derived from layout_schema.yaml v1; do not edit by hand)."
+)
+
+
+class LayoutError(ContractError):
+    """Layout-schema violation with a stable machine code.
+
+    Args:
+        code: Stable machine-readable error code.
+        message: Human-readable detail.
+        fields: Itemized fields, when the error names any.
+    """
+
+
+def _yaml():
+    return YAML(typ="safe")
+
+
+def _load_yaml_file(path):
+    try:
+        return _yaml().load(Path(path).read_text())
+    except LayoutError:
+        raise
+    except Exception as exc:
+        raise LayoutError(
+            "invalid_yaml", f"Cannot parse {path}: {exc}."
+        ) from exc
+
+
+def _check_entry_struct(entry, where):
+    for field in (
+        "name", "type", "match", "required", "tracked",
+        "created_by", "mutable", "description",
+    ):
+        if field not in entry:
+            raise LayoutError(
+                "invalid_schema", f"Entry at {where} misses field: {field}."
+            )
+    if entry["type"] not in ("dir", "file"):
+        raise LayoutError(
+            "invalid_schema", f"Entry at {where} has bad type: {entry['type']!r}."
+        )
+    if entry["match"] not in ("exact", "pattern"):
+        raise LayoutError(
+            "invalid_schema", f"Entry at {where} has bad match: {entry['match']!r}."
+        )
+    if entry["match"] == "pattern" and not entry.get("pattern"):
+        raise LayoutError(
+            "invalid_schema", f"Pattern entry at {where} needs a pattern."
+        )
+    if entry["type"] == "dir":
+        for child in entry.get("children", []) or []:
+            _check_entry_struct(child, f"{where}/{entry['name']}")
+    else:
+        if not entry.get("format"):
+            raise LayoutError(
+                "invalid_schema", f"File entry at {where} needs a format."
+            )
+
+
+def load_schema(path=None):
+    """Load and structurally validate the folder schema.
+
+    Args:
+        path: Schema YAML path; the bundled schema when omitted.
+
+    Returns:
+        Validated schema mapping.
+
+    Raises:
+        LayoutError: invalid_schema for an unloadable file, a wrong
+            schema_version, a missing section, a malformed entry,
+            or a bad policy_template.
+    """
+    schema_path = Path(path) if path is not None else _SCHEMA_PATH
+    try:
+        data = _yaml().load(schema_path.read_text())
+    except Exception as exc:
+        raise LayoutError(
+            "invalid_schema", f"Cannot load schema {schema_path}: {exc}."
+        ) from exc
+    if not isinstance(data, dict) or data.get("schema_version") != SCHEMA_VERSION:
+        raise LayoutError(
+            "invalid_schema",
+            f"Schema {schema_path} must carry schema_version {SCHEMA_VERSION}.",
+        )
+    for section in ("engine_root", "linked_project"):
+        entries = data.get(section)
+        if not isinstance(entries, list):
+            raise LayoutError(
+                "invalid_schema", f"Schema section missing: {section}."
+            )
+        for entry in entries:
+            _check_entry_struct(entry, section)
+    template = data.get("policy_template") or {}
+    if not isinstance(template.get("required"), list) or not isinstance(
+        template.get("defaults"), dict
+    ):
+        raise LayoutError("invalid_schema", "policy_template needs required + defaults.")
+    return data
+
+
+def _is_empty(value):
+    if value is None:
+        return True
+    if isinstance(value, str):
+        return value.strip() == ""
+    if isinstance(value, (list, tuple, dict)):
+        return len(value) == 0
+    return False
+
+
+def template_defaults(schema=None):
+    """Return a copy of the policy template defaults.
+
+    Args:
+        schema: Schema mapping; loaded when omitted.
+
+    Returns:
+        Deep copy of the policy template defaults.
+    """
+    data = schema if schema is not None else load_schema()
+    return copy.deepcopy(data["policy_template"]["defaults"])
+
+
+def validate_policy(policy, schema=None):
+    """Enforce present + non-empty on every template-required key.
+
+    Zero-silent-defaults: required entries must be present and
+    non-empty; dict defaults recurse one level.
+
+    Args:
+        policy: Policy mapping to validate.
+        schema: Schema mapping; loaded when omitted.
+
+    Returns:
+        Ok mapping when every required key passes.
+
+    Raises:
+        LayoutError: invalid_policy for a non-mapping policy,
+            missing_policy/empty_policy naming the failed key.
+    """
+    data = schema if schema is not None else load_schema()
+    template = data["policy_template"]
+    if not isinstance(policy, dict):
+        raise LayoutError("invalid_policy", "Policy must be a mapping.")
+    defaults = template["defaults"]
+    for key in template["required"]:
+        if key not in policy:
+            raise LayoutError(
+                "missing_policy", f"Missing required policy entry: {key}.",
+                fields=[key],
+            )
+        if _is_empty(policy[key]):
+            raise LayoutError(
+                "empty_policy",
+                f"Required policy entry is empty: {key}.",
+                fields=[key],
+            )
+        default = defaults.get(key)
+        value = policy[key]
+        if isinstance(default, dict) and isinstance(value, dict):
+            for sub in default:
+                if sub not in value:
+                    raise LayoutError(
+                        "missing_policy",
+                        f"Missing required policy entry: {key}.{sub}.",
+                        fields=[f"{key}.{sub}"],
+                    )
+                if _is_empty(value[sub]):
+                    raise LayoutError(
+                        "empty_policy",
+                        f"Required policy entry is empty: {key}.{sub}.",
+                        fields=[f"{key}.{sub}"],
+                    )
+    return {"ok": True}
+
+
+def _stamp_path(root, kind):
+    root = Path(root)
+    if kind == "engine_root":
+        return root / _VERSION_FILENAME
+    return root / ".rocket" / _VERSION_FILENAME
+
+
+def _read_folder_version(stamp):
+    try:
+        text = stamp.read_text()
+    except FileNotFoundError:
+        raise LayoutError(
+            "missing_entry", f"Missing required entry: {stamp}."
+        ) from None
+    if text.strip() == "":
+        raise LayoutError(
+            "empty_entry", f"Required entry is empty: {stamp}."
+        )
+    try:
+        data = _yaml().load(text)
+    except Exception as exc:
+        raise LayoutError(
+            "invalid_version", f"Bad version stamp {stamp}: {exc}."
+        ) from exc
+    version = data.get("schema_version") if isinstance(data, dict) else None
+    if not isinstance(version, int) or isinstance(version, bool):
+        raise LayoutError(
+            "invalid_version",
+            f"Bad version stamp {stamp}: need schema_version int.",
+        )
+    return version
+
+
+def _check_file(target, entry):
+    if target.is_dir():
+        raise LayoutError(
+            "type_mismatch", f"Entry must be a file, found dir: {target}."
+        )
+    if target.stat().st_size == 0:
+        raise LayoutError("empty_entry", f"Required entry is empty: {target}.")
+    if entry.get("format") == "policy":
+        data = _load_yaml_file(target)
+        if data is None:
+            raise LayoutError(
+                "empty_entry", f"Required entry is empty: {target}."
+            )
+        try:
+            validate_policy(data)
+        except LayoutError as exc:
+            raise LayoutError(
+                exc.code, f"{exc} ({target})", fields=exc.fields
+            ) from None
+
+
+def _check_entries(base, entries):
+    for entry in entries:
+        if entry["match"] == "exact":
+            target = Path(base) / entry["name"]
+            if not target.exists():
+                if entry["required"]:
+                    raise LayoutError(
+                        "missing_entry", f"Missing required entry: {target}."
+                    )
+                continue
+            if entry["type"] == "dir":
+                if not target.is_dir():
+                    raise LayoutError(
+                        "type_mismatch",
+                        f"Entry must be a dir, found file: {target}.",
+                    )
+                _check_entries(target, entry.get("children", []) or [])
+            else:
+                _check_file(target, entry)
+        else:
+            regex = re.compile(entry["pattern"])
+            names = []
+            if Path(base).is_dir():
+                names = sorted(
+                    p.name for p in Path(base).iterdir() if regex.match(p.name)
+                )
+            if entry["required"] and not names:
+                raise LayoutError(
+                    "missing_entry",
+                    f"Missing required entry matching {entry['pattern']}: {base}.",
+                )
+            for name in names:
+                target = Path(base) / name
+                if entry["type"] == "dir":
+                    if not target.is_dir():
+                        raise LayoutError(
+                            "type_mismatch",
+                            f"Entry must be a dir, found file: {target}.",
+                        )
+                    _check_entries(target, entry.get("children", []) or [])
+                else:
+                    _check_file(target, entry)
+
+
+def validate_tree(root, kind="engine_root", schema=None):
+    """Check a tree against the schema; refuse newer stamps first.
+
+    Args:
+        root: Tree root to check.
+        kind: Tree kind (engine_root or linked_project).
+        schema: Schema mapping; loaded when omitted.
+
+    Returns:
+        Ok mapping with kind, supported schema_version, and folder
+            version.
+
+    Raises:
+        LayoutError: invalid_kind for an unknown kind,
+            unsupported_version for a newer-than-known stamp,
+            missing_entry/empty_entry/type_mismatch for failed
+            entries, policy codes for a bad policy file.
+    """
+    if kind not in ("engine_root", "linked_project"):
+        raise LayoutError("invalid_kind", f"Unknown tree kind: {kind}.")
+    data = schema if schema is not None else load_schema()
+    base = Path(root)
+    if not base.is_dir():
+        raise LayoutError(
+            "missing_entry", f"Root not found or not a dir: {root}."
+        )
+    stamp = _stamp_path(base, kind)
+    folder_version = _read_folder_version(stamp)
+    if folder_version > SCHEMA_VERSION:
+        raise LayoutError(
+            "unsupported_version",
+            f"Folder schema version {folder_version} is newer than "
+            f"supported {SCHEMA_VERSION}; upgrade the engine, refusing "
+            f"to misread {stamp}.",
+        )
+    _check_entries(base, data[kind])
+    return {
+        "ok": True,
+        "kind": kind,
+        "schema_version": SCHEMA_VERSION,
+        "folder_version": folder_version,
+    }
+
+
+def _gitignore_patterns(entries, prefix=""):
+    patterns = []
+    for entry in entries:
+        segment = "*" if entry["match"] == "pattern" else entry["name"]
+        path = f"{prefix}{segment}"
+        if not entry["tracked"]:
+            patterns.append(f"{path}/" if entry["type"] == "dir" else path)
+            continue
+        if entry["type"] == "dir":
+            patterns.extend(
+                _gitignore_patterns(entry.get("children", []) or [], f"{path}/")
+            )
+    return patterns
+
+
+def derive_gitignore(kind=None, schema=None):
+    """Derive canonical gitignore lines from tracked=False entries.
+
+    Args:
+        kind: Tree kind to derive for; both kinds when omitted.
+        schema: Schema mapping; loaded when omitted.
+
+    Returns:
+        Canonical gitignore text with the derived header.
+
+    Raises:
+        LayoutError: invalid_kind for an unknown kind.
+    """
+    data = schema if schema is not None else load_schema()
+    if kind is not None and kind not in ("engine_root", "linked_project"):
+        raise LayoutError("invalid_kind", f"Unknown tree kind: {kind}.")
+    sections = [kind] if kind is not None else ["engine_root", "linked_project"]
+    patterns = []
+    for section in sections:
+        patterns.extend(_gitignore_patterns(data[section]))
+    lines = [_GITIGNORE_HEADER, *sorted(set(patterns))]
+    return "\n".join(lines) + "\n"
+
+
+def verify_gitignore(text, kind=None, schema=None):
+    """Verify a gitignore covers every derived pattern (extras allowed).
+
+    Args:
+        text: Gitignore text to verify.
+        kind: Tree kind to verify for; both kinds when omitted.
+        schema: Schema mapping; loaded when omitted.
+
+    Returns:
+        Ok mapping when every derived pattern is covered.
+
+    Raises:
+        LayoutError: invalid_kind for an unknown kind,
+            gitignore_mismatch naming the missing patterns.
+    """
+    expected = derive_gitignore(kind=kind, schema=schema)
+    want = [line for line in expected.splitlines() if line and not line.startswith("#")]
+    have = {
+        line.strip()
+        for line in (text or "").splitlines()
+        if line.strip() and not line.strip().startswith("#")
+    }
+    missing = [line for line in want if line not in have]
+    if missing:
+        raise LayoutError(
+            "gitignore_mismatch",
+            f"Gitignore misses derived patterns: {', '.join(missing)}.",
+        )
+    return {"ok": True}

rocket_engine/interfaces/layout_schema.yaml

@@ -0,0 +1,278 @@
+# LAYOUT-SCHEMA v1: machine-readable ENGINE_ROOT + linked-project layout.
+# Source of truth for dir/file names (ADR-001 consequences), validator
+# input, and migration baseline. Normative prose: docs/storage-policy.md.
+schema_version: 1
+description: >-
+  Engine-root and linked-project folder schema. pdks/ is the sole shared
+  store; cache/ is disposable derivations (not a store); managed projects
+  live at projects/<id>/ with co-located runs/; linked projects keep
+  engine state only under .rocket/ (gitignored exhaust).
+engine_root:
+  - name: layout.version
+    type: file
+    match: exact
+    required: true
+    tracked: true
+    created_by: engine
+    mutable: false
+    format: version
+    description: >-
+      Version stamp (YAML with schema_version int). Checked first;
+      newer-than-known refuses loudly, never misreads.
+  - name: policy.yaml
+    type: file
+    match: exact
+    required: true
+    tracked: true
+    created_by: engine
+    mutable: true
+    format: policy
+    description: >-
+      Global defaults (timeouts, threads, flags, deck/tool fallbacks,
+      seeds). KiCad-style base; project policy overrides beside runs.
+  - name: pdks
+    type: dir
+    match: exact
+    required: true
+    tracked: true
+    created_by: engine
+    mutable: false
+    description: >-
+      SOLE shared store: verified PDK copies + manifest. Immutable once
+      verified; re-fetch re-verifies instead of duplicating.
+    children:
+      - name: <id>
+        type: dir
+        match: pattern
+        pattern: ^[a-z0-9][a-z0-9_.-]*$
+        required: false
+        tracked: true
+        created_by: engine
+        mutable: false
+        description: One PDK id (e.g. sky130A lowercased by PATH-GUARD slug).
+        children:
+          - name: <revision>
+            type: dir
+            match: pattern
+            pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]*$
+            required: false
+            tracked: true
+            created_by: engine
+            mutable: false
+            description: One PDK revision; manifest pins identity (I28).
+            children:
+              - name: manifest.yaml
+                type: file
+                match: exact
+                required: true
+                tracked: true
+                created_by: engine
+                mutable: false
+                format: manifest
+                description: >-
+                  PDK manifest (hashes, source, date). Format owned by
+                  PDK-STORE; presence + non-empty enforced here.
+  - name: cache
+    type: dir
+    match: exact
+    required: true
+    tracked: false
+    created_by: engine
+    mutable: true
+    children: []
+    description: >-
+      Disposable derivations only. Not a store: nothing trusted is read
+      from it; deleting it costs only rebuild time.
+  - name: projects
+    type: dir
+    match: exact
+    required: true
+    tracked: true
+    created_by: engine
+    mutable: true
+    description: Default home for engine-managed projects.
+    children:
+      - name: <id>
+        type: dir
+        match: pattern
+        pattern: ^[a-z0-9][a-z0-9_.-]*$
+        required: false
+        tracked: true
+        created_by: engine
+        mutable: true
+        description: One managed project; runs co-located under runs/.
+        children:
+          - name: policy.yaml
+            type: file
+            match: exact
+            required: false
+            tracked: true
+            created_by: engine
+            mutable: true
+            format: policy
+            description: >-
+              Optional project-level override beside runs (KiCad-style:
+              wins over global, loses to explicit run args).
+          - name: events.yaml
+            type: file
+            match: exact
+            required: false
+            tracked: true
+            created_by: engine
+            mutable: true
+            format: events
+            description: >-
+              Durable ordered event ledger (LEDGER-DURABLE/I30):
+              seq-ordered actor-attributed events (job_queued,
+              run_completed, run_failed). Absent until the first
+              engine-mediated mutation; trimmed oldest-first by the
+              retention bound, never edited by hand.
+          - name: ledger.yaml
+            type: file
+            match: exact
+            required: false
+            tracked: true
+            created_by: engine
+            mutable: true
+            format: ledger
+            description: >-
+              Ledger head (LEDGER-DURABLE/I30): current revision plus
+              admitted-request identity for idempotent replay and
+              run_job lookup. Absent until the first accepted
+              mutation; rewritten atomically on every mutation.
+          - name: snapshots
+            type: dir
+            match: exact
+            required: false
+            tracked: true
+            created_by: engine
+            mutable: true
+            description: >-
+              Restorable per-revision snapshots (REWIND): byte copies
+              of managed documents at each revision, restored by
+              rewind. Absent until the first snapshotted mutation;
+              never hand-edited.
+            children:
+              - name: <revision>
+                type: dir
+                match: pattern
+                pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]*$
+                required: false
+                tracked: true
+                created_by: engine
+                mutable: false
+                children: []
+                description: >-
+                  One revision snapshot with the managed bytes as
+                  restored by rewind. Immutable once written.
+          - name: runs
+            type: dir
+            match: exact
+            required: true
+            tracked: false
+            created_by: engine
+            mutable: true
+            description: >-
+              Co-located run evidence (native outputs, findings,
+              verdicts). Gitignored exhaust; travels via CI artifacts.
+            children:
+              - name: <run_id>
+                type: dir
+                match: pattern
+                pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]*$
+                required: false
+                tracked: false
+                created_by: engine
+                mutable: false
+                children: []
+                description: >-
+                  One run record with I28 ingredient closure (project
+                  revision, PDK id+rev+hash, deck, solver, seeds,
+                  config). Immutable once written.
+linked_project:
+  - name: .rocket
+    type: dir
+    match: exact
+    required: true
+    tracked: false
+    created_by: engine
+    mutable: true
+    description: >-
+      Single carve-out: the engine writes into a caller tree only here,
+      never beside sources. Gitignored exhaust. Caller sources outside
+      are untouched and unvalidated.
+    children:
+      - name: layout.version
+        type: file
+        match: exact
+        required: true
+        tracked: false
+        created_by: engine
+        mutable: false
+        format: version
+        description: Version stamp for the carve-out (same refuse-newer rule).
+      - name: policy.yaml
+        type: file
+        match: exact
+        required: false
+        tracked: false
+        created_by: engine
+        mutable: true
+        format: policy
+        description: Optional project-level override (local, gitignored).
+      - name: runs
+        type: dir
+        match: exact
+        required: true
+        tracked: false
+        created_by: engine
+        mutable: true
+        description: Co-located run evidence (same I28 closure as managed).
+        children:
+          - name: <run_id>
+            type: dir
+            match: pattern
+            pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]*$
+            required: false
+            tracked: false
+            created_by: engine
+            mutable: false
+            children: []
+            description: One run record, immutable once written.
+policy_template:
+  description: >-
+    Zero-silent-defaults: the template ships every default explicitly;
+    anything required must be present and non-empty somewhere in the
+    chain (run args > project policy > global policy) or startup fails
+    loudly. Per-tool audit (2026-10-29) below pins each default's source.
+  required:
+    - timeout_s
+    - preflight_timeout_s
+    - threads
+    - slang_flags
+    - tools
+    - decks
+    - seeds
+  defaults:
+    timeout_s: 120
+    preflight_timeout_s: 30
+    threads: 4
+    slang_flags:
+      - -Wextra
+    tools:
+      run_drc: magic
+      run_hdl_test: icarus
+      run_optical: sax
+      run_syntax: slang
+    decks:
+      run_drc: sky130A
+    seeds:
+      - 0
+  audit:
+    timeout_s: All five solver adapters (_TIMEOUT_S=120) plus BwrapRunner.run default (120).
+    preflight_timeout_s: BwrapRunner.preflight default (30).
+    threads: No existing knob; new canonical name (default 4) for solver/worker parallelism.
+    slang_flags: SyntaxAdapter _DEFAULT_FLAGS (["-Wextra"]); other solvers use fixed argv.
+    tools: Engine deck.tool fallbacks — run_drc first-registered magic (klayout alt), run_hdl_test icarus, run_optical sax, run_syntax slang.
+    decks: Template-owned (PDK-STORE resolves id+rev to manifest-hashed paths); sky130A is the MVP demo PDK.
+    seeds: No existing knob; new canonical name (engine-api seeds[]); [0] is the deterministic default.