lockwire 0.2.0__py3-none-any.whl

lockwire/emit_ts.py

@@ -0,0 +1,150 @@
+"""Emit `app/src/shared/api.gen.ts` directly from the payload union (e1-d3).
+
+Plan v8 line 265, verbatim: *"There is no TypeScript generator in the list,
+deliberately: the mainstream generator's own documentation says a
+discriminated union like ours comes out in a shape TypeScript cannot narrow.
+The Python step that builds the union emits the TypeScript directly (about
+forty lines), and CI fails if the committed file is stale."*
+
+Measured 2026-09-08: the alternative (`api-schema`'s JSON Schema piped through
+the `openapi-typescript` npm package, per `packaging/generate-types.md`) does
+not run on this repo's toolchain today — `openapi-typescript@7.13.0` declares
+a peer on `typescript@^5.x` and crashes (`Cannot read properties of undefined
+(reading 'createKeywordTypeNode')`) against `app/package.json`'s already-pinned
+`typescript@7.0.2`. That is a second, independent reason (beyond v8 line 265)
+this box adds no npm dependency.
+
+this walks `api_payload.ALL_MEMBERS` and each model's own
+`model_json_schema()` — the same schema `api_payload.export_openapi` already
+assembles for `lockwire api-schema` — rather than re-enumerating fields or
+commands by hand. One walk, reused.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from lockwire import plugins
+from lockwire.api_payload import ALL_MEMBERS, MEMBERS
+from lockwire.report import VERDICT_EXIT_CODES, verdict_word
+
+#: Every consumer must see this before touching the file by hand.
+SENTINEL = (
+    "// GENERATED — do not edit by hand.\n"
+    "// `uv run lockwire api-types --out app/src/shared/api.gen.ts` regenerates this\n"
+    "// file from `src/lockwire/api_payload.py`. CI regenerates and diffs on every run;\n"
+    "// a stale committed file fails the build (packaging/generate-types.md).\n"
+)
+
+
+PLUGIN_SENTINEL = (
+    "// GENERATED — do not edit by hand.\n"
+    "// Written next to `api.gen.ts` by the same `lockwire api-types` run, from the payload\n"
+    "// members a plugin registers. A stale committed file fails the build.\n"
+)
+
+
+def _schemas(models: tuple[type, ...] = ALL_MEMBERS) -> dict[str, Any]:
+    """The same `{name: schema}` map `api_payload.export_openapi` builds — one
+    call per union member, `$defs` folded in beside it."""
+    schemas: dict[str, Any] = {}
+    for model in models:
+        schema = model.model_json_schema(ref_template="#/components/schemas/{model}")
+        schemas.update(schema.pop("$defs", {}))
+        schemas[model.__name__] = schema
+    return schemas
+
+
+def _ts_type(node: dict[str, Any]) -> str:
+    """One JSON-Schema node -> one TypeScript type expression."""
+    if "$ref" in node:
+        return node["$ref"].rsplit("/", 1)[-1]
+    if "const" in node:
+        return json.dumps(node["const"])
+    if "enum" in node:
+        return " | ".join(json.dumps(v) for v in node["enum"])
+    if "anyOf" in node:
+        return " | ".join(_ts_type(n) for n in node["anyOf"])
+    kind = node.get("type")
+    if kind == "string":
+        return "string"
+    if kind in ("integer", "number"):
+        return "number"
+    if kind == "boolean":
+        return "boolean"
+    if kind == "null":
+        return "null"
+    if kind == "array":
+        return f"({_ts_type(node['items'])})[]"
+    if kind == "object":
+        values = node.get("additionalProperties")
+        return f"Record<string, {_ts_type(values)}>" if isinstance(values, dict) else "Record<string, unknown>"
+    return "unknown"  # pragma: no cover — no union member emits an untyped leaf today
+
+
+def _interface(name: str, schema: dict[str, Any]) -> str:
+    required = set(schema.get("required", []))
+    lines = [f"export interface {name} {{"]
+    for field, node in schema.get("properties", {}).items():
+        optional = "" if field in required else "?"
+        lines.append(f"  {field}{optional}: {_ts_type(node)};")
+    lines.append("}")
+    return "\n".join(lines)
+
+
+def _declaration(name: str, schema: dict[str, Any]) -> str:
+    """Emit objects as interfaces and root schemas as named type aliases."""
+    if schema.get("type") == "object" or "properties" in schema:
+        return _interface(name, schema)
+    return f"export type {name} = {_ts_type(schema)};"
+
+
+def emit() -> str:
+    """The whole file, as text — every union member's interface plus the
+    discriminated `MachineDocument` alias TypeScript narrows on `artifact_type`."""
+    schemas = _schemas()
+    parts = [SENTINEL]
+    for name in sorted(schemas):
+        parts.append(_declaration(name, schemas[name]))
+    verdict_exit_codes = {
+        verdict_word(code): exit_code for code, exit_code in VERDICT_EXIT_CODES.items()
+    }
+    parts.append(
+        "export const VERDICT_EXIT_CODES = "
+        + json.dumps(verdict_exit_codes, indent=2)
+        + ' as const satisfies Record<CheckPayload["verdict"], number>;'
+    )
+    members = " | ".join(model.__name__ for model in MEMBERS.values())
+    parts.append(f"export type MachineDocument = {members};")
+    return "\n\n".join(parts) + "\n"
+
+
+def emit_plugin() -> str | None:
+    """The file for members a plugin registered (`plugins.PAYLOAD_*`), or None when
+    there are none. Types the free file already defines are imported from it."""
+    plugins.ensure()
+    models = (*plugins.PAYLOAD_MEMBERS.values(), *plugins.PAYLOAD_EXTRA)
+    if not models:
+        return None
+    free = _schemas()
+    own = {name: s for name, s in _schemas(models).items() if name not in free}
+    refs = set(re.findall(r'"\$ref": "#/components/schemas/(\w+)"', json.dumps(own)))
+    parts = [PLUGIN_SENTINEL]
+    if used := sorted(refs & set(free)):
+        parts.append("import type { " + ", ".join(used) + ' } from "../api.gen";')
+    parts += [_declaration(name, own[name]) for name in sorted(own)]
+    members = " | ".join(model.__name__ for model in plugins.PAYLOAD_MEMBERS.values())
+    parts.append(f"export type MachineDocumentPlugin = {members};")
+    return "\n\n".join(parts) + "\n"
+
+
+def write(path: Path | str) -> None:
+    """The free file at `path`; a plugin's members, if any, at `<dir>/pro/<name>`."""
+    Path(path).write_text(emit(), encoding="utf-8")
+    if (extra := emit_plugin()) is not None:
+        out = Path(path).parent / "pro" / Path(path).name
+        out.parent.mkdir(exist_ok=True)
+        out.write_text(extra, encoding="utf-8")

lockwire/export_mhs.py

@@ -0,0 +1,115 @@
+"""The MHS bridge, outward only.
+
+Renders each declared device into the converging device-manifest shape five independent
+third-party designs settled on (``device_id``, ``capabilities[]``, ``safety_limits[]`` with
+``min``/``max``): what it measures, what it adjusts, what it refuses. ``min``/``max`` are
+aliased straight from ``Band.lo``/``Band.hi`` — nothing here is invented, predicted or guessed.
+Read-only, derived from the contract, never the truth.
+
+Import of a third-party manifest into a contract is refused elsewhere (``lockwire import``): the inbound direction is refused until
+an open standard is published, because import is where lock-in happens. This module
+builds the outward direction only — no reader for the inbound shape lives here.
+"""
+
+from __future__ import annotations
+
+from lockwire.checks import power_rollup
+from lockwire.describe import _role
+from lockwire.schema import Contract, DeviceInstance, Provenance
+
+# ponytail: the schema's witness enum (`Provenance.witness`, schema.py:191) is
+# "w0..w6 | live | human" — no literal "fixture"/"sim" value exists yet. "human"
+# (author-asserted, not measured off real hardware or a bag) is the closest proxy for
+# "this number is a stand-in, not a real measurement". Revisit if a real witness value
+# for fixture/sim data lands.
+_SIMULATED_WITNESSES = {"human"}
+
+
+def _provenance_fields(provenance: Provenance | None) -> dict[str, object]:
+    if provenance is None:
+        return {"witness": None, "simulated": False}
+    return {
+        "witness": provenance.witness,
+        "simulated": provenance.witness in _SIMULATED_WITNESSES,
+    }
+
+
+def _safety_limits(instance: DeviceInstance, model) -> list[dict[str, object]]:
+    """Every band this device declares, each tagged with where it came from.
+
+    A datasheet rating (``model.hard_limits``) never reads the same as a fitted band
+    (statistically evidenced, ``envelope.fitted_bands``) or an inferred one (observed,
+    no fit evidence) — collapsing the three into one field is a loss this module refuses.
+    """
+    limits: list[dict[str, object]] = []
+    if model is not None and model.hard_limits:
+        prov = _provenance_fields(model.provenance)
+        for channel, band in sorted(model.hard_limits.items()):
+            limits.append(
+                {
+                    "channel": channel,
+                    "min": band.lo,
+                    "max": band.hi,
+                    "unit": band.unit,
+                    "kind": "datasheet",
+                    **prov,
+                }
+            )
+    for envelope in instance.envelopes:
+        prov = _provenance_fields(envelope.provenance)
+        for name, signal in sorted(envelope.signals.items()):
+            kind = "fitted" if f"signals/{name}" in envelope.fitted_bands else "inferred"
+            limits.append(
+                {
+                    "channel": f"{envelope.context}/{name}",
+                    "min": signal.band.lo,
+                    "max": signal.band.hi,
+                    "unit": signal.band.unit,
+                    "kind": kind,
+                    **prov,
+                }
+            )
+    return limits
+
+
+def _capabilities(model, instance: DeviceInstance) -> list[str]:
+    role = _role(model, instance)  # reuse describe.py's walk rather than re-derive it
+    if role == "measures and adjusts":
+        return ["measures", "adjusts"]
+    if role in ("measures", "adjusts"):
+        return [role]
+    return []
+
+
+def render_device(contract: Contract, instance: DeviceInstance) -> dict[str, object]:
+    """One device's converging-manifest entry."""
+    model = contract.device_model(instance.model)
+    prov = _provenance_fields(instance.provenance)
+    return {
+        "device_id": instance.id,
+        "capabilities": _capabilities(model, instance),
+        "safety_limits": _safety_limits(instance, model),
+        **prov,
+    }
+
+
+def _loss_report(contract: Contract) -> list[str]:
+    """What a per-device manifest cannot carry, named rather than generic."""
+    rail_totals, *_ = power_rollup(contract, "nominal")
+    rails = ", ".join(sorted(rail_totals)) if rail_totals else "none declared"
+    return [
+        f"shared-rail power budgets are not carried: this contract rolls up {rails}; "
+        "a per-device manifest has no field for a rail's capacity or headroom.",
+        "frame references are not carried: joint/link membership and the URDF frame tree "
+        "(mount frames, drives_joint pairings) have no place in a per-device manifest.",
+        "provenance/enforcement metadata beyond witness/simulated is not carried: bag "
+        "hashes, lock dates, and the write-layer verdicts are dropped.",
+    ]
+
+
+def export_mhs(contract: Contract) -> dict[str, object]:
+    """Render the whole contract into the converging device-manifest shape. Outward only."""
+    return {
+        "devices": [render_device(contract, device) for device in contract.devices],
+        "loss_report": _loss_report(contract),
+    }

lockwire/factdiff.py

@@ -0,0 +1,254 @@
+"""The fact diff: what changed in the facts, not in the text.
+
+Two loaded contracts in, a diff document out. Nothing here reads git (that is
+``gitref.py``) and nothing here prints (``cli.py`` does that) — this module
+only compares.
+
+The comparison is over the *validated* contract, not the YAML text, so a
+reordered device list, a re-indented block or a rewritten comment is not a
+change. Every declared scalar is flattened to a ``/``-separated path
+(``topology/rails/rail.5v/capacity/value``), list rows keyed by their own
+``id``/``name``/``context`` rather than by position.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import Any
+
+from lockwire.checks import run_record_checks
+from lockwire.schema import Contract, load_contract
+
+# Path segments whose value *is* a declared ceiling. A number growing under one
+# of these is a limit being raised — the edit that makes a finding go away
+# without the robot changing, so it is called out rather than listed as one
+# more field change.
+LIMIT_SEGMENTS = frozenset(
+    {
+        "capacity",
+        "limit",
+        "hard_limits",
+        "current_limit",
+        "effort",
+        "velocity",
+        "torque_peak",
+        "torque_continuous",
+        "fade_margin_required",
+        "position_tracking_max_error",
+        "feedback_deadline_max",
+        "feedback_loss_max",
+        "clock_alignment_max_error",
+        "prediction_position_rmse_max",
+        "prediction_position_peak_max",
+    }
+)
+
+# The entity collections a person thinks in. An added or removed row here is
+# reported once, by id — not as forty field changes underneath it.
+ENTITY_KINDS = (
+    "devices",
+    "device_models",
+    "families",
+    "budgets",
+    "assumptions",
+    "rails",
+    "buses",
+    "wires",
+    "links",
+    "actuator_cases",
+)
+
+
+@dataclass(frozen=True)
+class FieldChange:
+    path: str
+    old: Any  # None when the field was not declared before
+    new: Any  # None when the field is no longer declared
+    witness: str | None = None
+    source: str | None = None
+    limit_raised: bool = False
+
+
+@dataclass(frozen=True)
+class EntityChange:
+    kind: str  # one of ENTITY_KINDS
+    id: str
+
+
+@dataclass(frozen=True)
+class FindingRef:
+    severity: str
+    quantity: str
+
+
+@dataclass
+class FactDiff:
+    changes: list[FieldChange] = field(default_factory=list)
+    added: list[EntityChange] = field(default_factory=list)
+    removed: list[EntityChange] = field(default_factory=list)
+    findings_new: list[FindingRef] = field(default_factory=list)
+    findings_gone: list[FindingRef] = field(default_factory=list)
+
+    @property
+    def changed(self) -> bool:
+        return bool(self.changes or self.added or self.removed)
+
+    def as_json(self) -> dict[str, Any]:
+        return {
+            "changed": self.changed,
+            "changes": [
+                {
+                    "path": c.path,
+                    "old": c.old,
+                    "new": c.new,
+                    "witness": c.witness,
+                    "source": c.source,
+                    "limit_raised": c.limit_raised,
+                }
+                for c in self.changes
+            ],
+            "added": [{"kind": e.kind, "id": e.id} for e in self.added],
+            "removed": [{"kind": e.kind, "id": e.id} for e in self.removed],
+            "findings_new": [
+                {"severity": f.severity, "quantity": f.quantity} for f in self.findings_new
+            ],
+            "findings_gone": [
+                {"severity": f.severity, "quantity": f.quantity} for f in self.findings_gone
+            ],
+        }
+
+
+def _key_for(row: Any, index: int) -> str:
+    if isinstance(row, dict):
+        for field_name in ("id", "name", "context"):
+            value = row.get(field_name)
+            if isinstance(value, str) and value:
+                return value
+    return str(index)
+
+
+def _flatten(node: Any, prefix: str, out: dict[str, Any]) -> None:
+    if isinstance(node, dict):
+        for key, value in node.items():
+            _flatten(value, f"{prefix}/{key}" if prefix else str(key), out)
+    elif isinstance(node, list):
+        for index, row in enumerate(node):
+            _flatten(row, f"{prefix}/{_key_for(row, index)}", out)
+    else:
+        out[prefix] = node
+
+
+def flatten(contract: Contract) -> dict[str, Any]:
+    """Every declared scalar in the contract, by path."""
+    out: dict[str, Any] = {}
+    _flatten(contract.model_dump(mode="json", exclude_none=True), "", out)
+    return out
+
+
+def _entities(contract: Contract) -> dict[str, set[str]]:
+    topology = contract.topology
+    model = contract.model
+    return {
+        "devices": {row.id for row in contract.devices},
+        "device_models": {row.id for row in contract.device_models},
+        "families": {row.id for row in contract.families},
+        "budgets": {row.id for row in contract.budgets},
+        "assumptions": {row.id for row in contract.assumptions},
+        "rails": {row.id for row in topology.rails} if topology else set(),
+        "buses": {row.id for row in topology.buses} if topology else set(),
+        "wires": {row.id for row in topology.wires} if topology else set(),
+        "links": {row.name for row in model.links} if model else set(),
+        "actuator_cases": {row.id for row in contract.actuator_cases},
+    }
+
+
+def _limit_raised(path: str, old: Any, new: Any) -> bool:
+    segments = path.split("/")
+    if segments[-1] == "lo":  # raising a floor narrows the band, it does not relax it
+        return False
+    if not LIMIT_SEGMENTS.intersection(segments):
+        return False
+    if not isinstance(old, (int, float)) or not isinstance(new, (int, float)):
+        return False
+    return bool(new > old)
+
+
+def _provenance_for(path: str, flat: dict[str, Any]) -> tuple[str | None, str | None]:
+    """Witness and source of the nearest enclosing entry that declares provenance."""
+    segments = path.split("/")
+    for cut in range(len(segments) - 1, 0, -1):
+        stem = "/".join(segments[:cut])
+        witness = flat.get(f"{stem}/provenance/witness")
+        if witness is not None:
+            return witness, flat.get(f"{stem}/provenance/source")
+    return None, None
+
+
+def _findings(contract: Contract) -> set[FindingRef]:
+    return {FindingRef(f.severity, f.quantity) for f in run_record_checks(contract)}
+
+
+def fact_diff(before: Contract, after: Contract) -> FactDiff:
+    """Compare two contracts: declared values, entries, and the verdict delta."""
+    diff = FactDiff()
+
+    old_entities, new_entities = _entities(before), _entities(after)
+    touched: set[str] = set()
+    for kind in ENTITY_KINDS:
+        for entity_id in sorted(new_entities[kind] - old_entities[kind]):
+            diff.added.append(EntityChange(kind, entity_id))
+            touched.add(entity_id)
+        for entity_id in sorted(old_entities[kind] - new_entities[kind]):
+            diff.removed.append(EntityChange(kind, entity_id))
+            touched.add(entity_id)
+
+    flat_old, flat_new = flatten(before), flatten(after)
+    for path in sorted(set(flat_old) | set(flat_new)):
+        old, new = flat_old.get(path), flat_new.get(path)
+        if old == new:
+            continue
+        if touched.intersection(path.split("/")):
+            continue  # already reported once, as an added/removed entry
+        witness, source = _provenance_for(path, flat_new if new is not None else flat_old)
+        diff.changes.append(
+            FieldChange(path, old, new, witness, source, _limit_raised(path, old, new))
+        )
+
+    old_findings, new_findings = _findings(before), _findings(after)
+    key = lambda finding: (finding.severity, finding.quantity)  # noqa: E731
+    diff.findings_new = sorted(new_findings - old_findings, key=key)
+    diff.findings_gone = sorted(old_findings - new_findings, key=key)
+    return diff
+
+
+def render_lines(diff: FactDiff) -> list[str]:
+    """The fact diff as plain lines, in the order a person reads them."""
+    if not diff.changed and not diff.findings_new and not diff.findings_gone:
+        return ["no fact changes"]
+    lines: list[str] = []
+    for change in diff.changes:
+        provenance = ""
+        if change.witness or change.source:
+            provenance = f"  [{change.witness or '?'} · {change.source or '?'}]"
+        flag = "  limit raised" if change.limit_raised else ""
+        lines.append(f"~ {change.path}: {change.old} -> {change.new}{provenance}{flag}")
+    for entry in diff.added:
+        lines.append(f"+ {entry.kind}/{entry.id}")
+    for entry in diff.removed:
+        lines.append(f"- {entry.kind}/{entry.id}")
+    for finding in diff.findings_new:
+        lines.append(f"! new {finding.severity}: {finding.quantity}")
+    for finding in diff.findings_gone:
+        lines.append(f"o gone {finding.severity}: {finding.quantity}")
+    return lines
+
+
+def load_contract_text(text: str) -> Contract:
+    """Load a contract held in memory (the version git handed back)."""
+    with NamedTemporaryFile("w", suffix=".yaml", encoding="utf-8", delete=False) as handle:
+        handle.write(text)
+        temp = Path(handle.name)
+    try:
+        return load_contract(temp)
+    finally:
+        temp.unlink(missing_ok=True)