obaaf 0.1.0__py3-none-any.whl

obaaf/__init__.py

@@ -0,0 +1,6 @@
+"""Open Build and Agent Assurance Framework (OBAAF) tools.
+
+Version 0.x is a draft. Nothing in this package has been piloted yet.
+"""
+
+__version__ = "0.1.0"

obaaf/__main__.py

@@ -0,0 +1,3 @@
+from obaaf.cli import main
+
+raise SystemExit(main())

obaaf/assess.py

@@ -0,0 +1,344 @@
+"""Score an OBAAF self-assessment and rank the fixes (FR2).
+
+Scoring follows Paper 2, design requirement DR6: a studio reaches a tier when
+every item at that tier and below is answered yes. An item may be marked not
+applicable only when its condition is absent, and then counts as satisfied.
+
+Fixes are ranked lowest tier first, then lowest effort, then by the number of
+documented compromises for which the item is a deciding control (Paper 2,
+Table 7). See DECISIONS.md, D-006.
+
+Everything here runs locally. Nothing is sent over the network (NFR5).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+from obaaf import __version__, yamlutil
+from obaaf.catalog import Catalog, load
+
+ANSWER_FORMAT = "obaaf-assessment/v0.1"
+VALID = {"yes", "no", "na", "unanswered"}
+ALIASES = {
+    "y": "yes", "true": "yes", "n": "no", "false": "no", "n/a": "na", "not applicable": "na",
+    "": "unanswered", "?": "unanswered", "unknown": "unanswered", "unsure": "unanswered",
+}
+
+
+class AnswerError(ValueError):
+    """The answer file cannot be scored as written."""
+
+
+@dataclass
+class Answer:
+    value: str
+    evidence: str = ""
+    note: str = ""
+
+
+@dataclass
+class AnswerSet:
+    answers: dict[str, Answer]
+    studio: str = ""
+    respondent: str = ""
+    date: str = ""
+
+
+@dataclass
+class Fix:
+    rank: int
+    item: dict
+    answer: str
+    prevents: list[dict]
+    limits: list[dict]
+
+
+@dataclass
+class Result:
+    tier: int
+    tier_name: str
+    per_tier: dict[int, dict[str, int]]
+    fixes: list[Fix]
+    answers: AnswerSet
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def next_tier(self) -> int | None:
+        return self.tier + 1 if self.tier < 4 else None
+
+
+def _normalize(raw: Any, iid: str) -> Answer:
+    evidence = note = ""
+    if isinstance(raw, dict):
+        evidence = str(raw.get("evidence") or "")
+        note = str(raw.get("note") or "")
+        raw = raw.get("answer")
+    if raw is True:
+        raw = "yes"
+    elif raw is False:
+        raw = "no"
+    elif raw is None:
+        raw = "unanswered"
+    value = str(raw).strip().lower()
+    value = ALIASES.get(value, value)
+    if value not in VALID:
+        raise AnswerError(f"item {iid}: answer {raw!r} is not one of yes, no, na or unanswered")
+    return Answer(value=value, evidence=evidence, note=note)
+
+
+def parse_answers(data: Any, catalog: Catalog | None = None) -> AnswerSet:
+    catalog = catalog or load()
+    if not isinstance(data, dict) or "answers" not in data:
+        raise AnswerError("the file must be a mapping with an 'answers' key (run 'obaaf assess init' for a template)")
+    fmt = data.get("format", ANSWER_FORMAT)
+    if fmt != ANSWER_FORMAT:
+        raise AnswerError(f"unsupported answer format {fmt!r}; expected {ANSWER_FORMAT}")
+    raw_answers = data["answers"]
+    if isinstance(raw_answers, list):
+        pairs = []
+        for entry in raw_answers:
+            if not isinstance(entry, dict) or "item" not in entry:
+                raise AnswerError("each entry in a list of answers needs an 'item' key")
+            pairs.append((entry["item"], entry))
+    elif isinstance(raw_answers, dict):
+        pairs = list(raw_answers.items())
+    else:
+        raise AnswerError("'answers' must be a mapping or a list")
+
+    answers: dict[str, Answer] = {}
+    for key, raw in pairs:
+        if not isinstance(key, str):
+            raise AnswerError(
+                f"item ID {key!r} must be quoted (write \"2.10\", not 2.10, or YAML reads it as the number 2.1)"
+            )
+        iid = key.strip()
+        if iid not in catalog.items:
+            raise AnswerError(f"unknown item {iid!r}")
+        if iid in answers:
+            raise AnswerError(f"item {iid} is answered twice")
+        answer = _normalize(raw, iid)
+        if answer.value == "na" and not catalog.items[iid].get("na_when"):
+            raise AnswerError(
+                f"item {iid} cannot be marked not applicable; only items whose condition can be absent can "
+                "(Paper 2, DR6). Answer yes or no."
+            )
+        answers[iid] = answer
+    for iid in catalog.items:
+        answers.setdefault(iid, Answer(value="unanswered"))
+    return AnswerSet(
+        answers=answers,
+        studio=str(data.get("studio") or ""),
+        respondent=str(data.get("respondent") or ""),
+        date=str(data.get("date") or ""),
+    )
+
+
+def load_answers(path: str | Path, catalog: Catalog | None = None) -> AnswerSet:
+    text = Path(path).read_text(encoding="utf-8")
+    if str(path).endswith(".json"):
+        data = json.loads(text)
+    else:
+        try:
+            data = yamlutil.load(text)
+        except yamlutil.DuplicateKeyError as exc:
+            raise AnswerError(str(exc)) from exc
+    return parse_answers(data, catalog)
+
+
+def _item_order(iid: str) -> tuple[int, int]:
+    tier, num = iid.split(".")
+    return int(tier), int(num)
+
+
+def score(answers: AnswerSet, catalog: Catalog | None = None) -> Result:
+    catalog = catalog or load()
+    per_tier: dict[int, dict[str, int]] = {}
+    for tier in sorted(catalog.tiers):
+        counts = {"items": 0, "yes": 0, "na": 0, "no": 0, "unanswered": 0}
+        for iid, item in catalog.items.items():
+            if item["tier"] == tier:
+                counts["items"] += 1
+                counts[answers.answers[iid].value] += 1
+        per_tier[tier] = counts
+
+    reached = 0
+    for tier in sorted(per_tier):
+        counts = per_tier[tier]
+        if counts["yes"] + counts["na"] == counts["items"]:
+            reached = tier
+        else:
+            break
+
+    effort_rank = {k: v["rank"] for k, v in catalog.assessment["effort"].items()}
+    open_items = [
+        (iid, item) for iid, item in catalog.items.items()
+        if answers.answers[iid].value in ("no", "unanswered")
+    ]
+
+    def key(entry: tuple[str, dict]) -> tuple:
+        iid, item = entry
+        cases = catalog.item_cases(iid)
+        return (item["tier"], effort_rank[item["effort"]], -len(cases["prevent"]), -len(cases["limit"]), _item_order(iid))
+
+    fixes = []
+    for rank, (iid, item) in enumerate(sorted(open_items, key=key), start=1):
+        cases = catalog.item_cases(iid)
+        fixes.append(Fix(rank=rank, item=item, answer=answers.answers[iid].value,
+                         prevents=cases["prevent"], limits=cases["limit"]))
+
+    warnings = []
+    unanswered = [iid for iid, a in answers.answers.items() if a.value == "unanswered"]
+    if unanswered:
+        warnings.append(
+            f"{len(unanswered)} item(s) unanswered; they count as 'no' until answered: "
+            + ", ".join(sorted(unanswered, key=_item_order))
+        )
+    tier_name = catalog.tiers[reached]["name"] if reached else "Not yet Accounted"
+    return Result(tier=reached, tier_name=tier_name, per_tier=per_tier, fixes=fixes, answers=answers, warnings=warnings)
+
+
+# ---------------------------------------------------------------------- output
+def template(catalog: Catalog | None = None) -> str:
+    """An answer file with every question, ready to fill in."""
+    catalog = catalog or load()
+    lines = [
+        "# OBAAF self-assessment answers. Answer each item yes, no, or na where allowed.",
+        "# Keep this file inside your studio: it is never sent anywhere.",
+        "# Score it with:  obaaf assess score this-file.yaml",
+        f"format: {ANSWER_FORMAT}",
+        'studio: ""',
+        'respondent: ""',
+        f'date: "{date.today().isoformat()}"',
+        "answers:",
+    ]
+    for tier in sorted(catalog.tiers):
+        t = catalog.tiers[tier]
+        lines.append(f"  # Tier {tier}, {t['name']}: {t['summary']}")
+        for iid, item in sorted(catalog.items.items(), key=lambda kv: _item_order(kv[0])):
+            if item["tier"] != tier:
+                continue
+            lines.append(f"  # {iid} {item['question']}")
+            lines.append(f"  #     Evidence: {item['evidence']}.")
+            if item.get("na_when"):
+                lines.append(f"  #     Answer na only if: {item['na_when']}")
+            lines.append(f'  "{iid}": {{answer: unanswered, evidence: ""}}')
+    return "\n".join(lines) + "\n"
+
+
+def _case_names(cases: list[dict]) -> str:
+    return ", ".join(f"{c['name']} ({c['reported']})" for c in cases)
+
+
+def to_text(result: Result, catalog: Catalog | None = None, limit: int = 10) -> str:
+    catalog = catalog or load()
+    out = []
+    who = f" for {result.answers.studio}" if result.answers.studio else ""
+    out.append(f"OBAAF self-assessment{who}")
+    out.append(f"Tier reached: {result.tier} ({result.tier_name})")
+    for tier, counts in result.per_tier.items():
+        satisfied = counts["yes"] + counts["na"]
+        out.append(f"  Tier {tier} {catalog.tiers[tier]['name']:<11} {satisfied:>2}/{counts['items']} satisfied")
+    for warning in result.warnings:
+        out.append(f"Note: {warning}")
+    if result.fixes:
+        shown = result.fixes[:limit] if limit else result.fixes
+        out.append("")
+        out.append(f"Fix next ({len(shown)} of {len(result.fixes)}, lowest tier and effort first):")
+        effort = catalog.assessment["effort"]
+        for fix in shown:
+            item = fix.item
+            label = effort[item["effort"]]["label"].lower()
+            out.append(f"{fix.rank:>3}. {item['id']} {item['short']} [tier {item['tier']}, {label}]")
+            if fix.prevents:
+                out.append(f"       Would have prevented: {_case_names(fix.prevents)}")
+            if fix.limits:
+                out.append(f"       Detects or limits: {_case_names(fix.limits)}")
+            out.append(f"       How: {item['fix'][0]}")
+    else:
+        out.append("All items satisfied.")
+    return "\n".join(out) + "\n"
+
+
+def to_markdown(result: Result, catalog: Catalog | None = None, link_base: str = "") -> str:
+    catalog = catalog or load()
+    who = f" - {result.answers.studio}" if result.answers.studio else ""
+    out = [f"# OBAAF self-assessment{who}", ""]
+    meta = []
+    if result.answers.date:
+        meta.append(f"Date: {result.answers.date}")
+    if result.answers.respondent:
+        meta.append(f"Respondent: {result.answers.respondent}")
+    meta.append(f"Scored by obaaf {__version__}")
+    out += [" · ".join(meta), ""]
+    out.append(f"**Tier reached: {result.tier} ({result.tier_name}).** "
+               "A tier describes controls in place, not a guarantee of security.")
+    out.append("")
+    out.append("| Tier | Satisfied | No | Unanswered |")
+    out.append("| --- | --- | --- | --- |")
+    for tier, counts in result.per_tier.items():
+        out.append(f"| {tier} {catalog.tiers[tier]['name']} | {counts['yes'] + counts['na']} of {counts['items']} "
+                   f"| {counts['no']} | {counts['unanswered']} |")
+    out.append("")
+    if result.fixes:
+        out.append("## What to fix next")
+        out.append("")
+        out.append("Ranked lowest tier first, then lowest effort, then by the documented compromises each item "
+                   "addresses.")
+        out.append("")
+        out.append("| # | Item | Tier | Effort | Documented cases it addresses | How to fix |")
+        out.append("| --- | --- | --- | --- | --- | --- |")
+        effort = catalog.assessment["effort"]
+        for fix in result.fixes:
+            item = fix.item
+            cases = _case_names(fix.prevents + fix.limits) or "-"
+            links = ", ".join(f"[{_label(link)}]({link_base}{link})" for link in item["fix"])
+            out.append(f"| {fix.rank} | {item['id']} {item['short']} | {item['tier']} | "
+                       f"{effort[item['effort']]['label']} | {cases} | {links} |")
+        out.append("")
+    if result.warnings:
+        out.append("## Notes")
+        out.append("")
+        out.extend(f"- {w}" for w in result.warnings)
+        out.append("")
+    return "\n".join(out)
+
+
+def _label(link: str) -> str:
+    from obaaf.render import _label as render_label
+
+    return render_label(link)
+
+
+def to_json(result: Result) -> str:
+    payload = {
+        "format": "obaaf-assessment-result/v0.1",
+        "scoredBy": f"obaaf {__version__}",
+        "studio": result.answers.studio,
+        "date": result.answers.date,
+        "tier": result.tier,
+        "tierName": result.tier_name,
+        "perTier": {str(k): v for k, v in result.per_tier.items()},
+        "fixes": [
+            {
+                "rank": f.rank,
+                "item": f.item["id"],
+                "short": f.item["short"],
+                "tier": f.item["tier"],
+                "effort": f.item["effort"],
+                "answer": f.answer,
+                "profile": f.item["profile"],
+                "prevents": [c["id"] for c in f.prevents],
+                "limits": [c["id"] for c in f.limits],
+                "fix": f.item["fix"],
+            }
+            for f in result.fixes
+        ],
+        "warnings": result.warnings,
+    }
+    return json.dumps(payload, indent=2) + "\n"

obaaf/attest/__init__.py

@@ -0,0 +1,6 @@
+"""Generators for OBAAF's records: snapshot, agent run, approval, build record, manifest.
+
+The generators write in-toto predicates (and optionally whole statements). In
+the GitHub Actions templates the predicates are signed by actions/attest in a
+job that holds the OIDC permission, so no long-lived key exists (FR11).
+"""

obaaf/attest/agentrecord.py

@@ -0,0 +1,67 @@
+"""The agent record that travels with an agent-authored change (R8, G8.3).
+
+When the effect lane applies a proposal, it commits a record file next to the
+change, at `.obaaf/records/<bundle digest>.json`, and names it in a commit
+trailer (`OBAAF-Agent-Record: <path>`). The record holds the proposal bundle and
+the two signed attestations: the agent-run record from the agent lane and the
+approval record from the effect lane. The release verifier reads it from the
+commit, so the evidence is archived with the source and needs no network
+lookups beyond signature verification.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from pathlib import Path
+
+from obaaf.attest.common import RecordError, canonical_json, files_under, sha256_bytes, write_json
+from obaaf.attest.proposal import ALLOWED_FILES, bundle_digest
+
+FORMAT = "obaaf-agent-record/v0.1"
+TRAILER = "OBAAF-Agent-Record"
+
+
+__all__ = ["FORMAT", "TRAILER", "bundle_digest", "digest_of_listing", "build", "write", "parse"]
+
+
+def digest_of_listing(files: dict[str, bytes]) -> str:
+    listing = sorted([name, sha256_bytes(data)] for name, data in files.items())
+    return sha256_bytes(canonical_json(listing))
+
+
+def build(proposal_dir: str | Path, agent_run: dict, approval: dict, agent_run_url: str = "") -> dict:
+    root = Path(proposal_dir)
+    files = {p.relative_to(root).as_posix(): base64.b64encode(p.read_bytes()).decode("ascii") for p in files_under(root)}
+    return {
+        "format": FORMAT,
+        "bundleDigest": {"sha256": bundle_digest(root)},
+        "proposal": {"files": files},
+        "attestations": {"agentRun": agent_run, "approval": approval},
+        "agentRunUrl": agent_run_url,
+    }
+
+
+def write(record: dict, records_dir: str | Path) -> Path:
+    path = Path(records_dir) / f"{record['bundleDigest']['sha256']}.json"
+    write_json(path, record)
+    return path
+
+
+def parse(text: str) -> tuple[dict, dict[str, bytes]]:
+    """Return (record, proposal files) after checking the record's own digest."""
+    try:
+        record = json.loads(text)
+    except ValueError as exc:
+        raise RecordError(f"agent record is not JSON: {exc}") from exc
+    if record.get("format") != FORMAT:
+        raise RecordError(f"unexpected agent record format {record.get('format')!r}")
+    files = {}
+    for name, encoded in record["proposal"]["files"].items():
+        if name not in ALLOWED_FILES:
+            raise RecordError(f"unexpected file in agent record: {name!r}")
+        files[name] = base64.b64decode(encoded)
+    expected = record.get("bundleDigest", {}).get("sha256")
+    if digest_of_listing(files) != expected:
+        raise RecordError("the proposal files in the record do not match its bundle digest")
+    return record, files

obaaf/attest/common.py

@@ -0,0 +1,111 @@
+"""Shared helpers: digests, in-toto statements, schema validation, the CI environment."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterable
+
+from obaaf import __version__
+from obaaf.catalog import data_text
+from obaaf.predicates import SCHEMA_FOR_TYPE, STATEMENT_TYPE
+
+
+class RecordError(ValueError):
+    """A record cannot be produced or does not validate."""
+
+
+def sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def sha256_file(path: str | Path) -> str:
+    digest = hashlib.sha256()
+    with open(path, "rb") as handle:
+        for chunk in iter(lambda: handle.read(1 << 20), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def canonical_json(obj: Any) -> bytes:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def files_under(path: str | Path) -> list[Path]:
+    """Files under a directory (sorted, relative order stable), or the file itself."""
+    path = Path(path)
+    if path.is_file():
+        return [path]
+    if not path.is_dir():
+        raise RecordError(f"not found: {path}")
+    return sorted(p for p in path.rglob("*") if p.is_file() and not p.is_symlink())
+
+
+def subjects_for(paths: Iterable[str | Path], base: str | Path | None = None) -> list[dict]:
+    """in-toto ResourceDescriptors (name + sha256) for files; names are relative to `base`."""
+    out = []
+    for path in paths:
+        path = Path(path)
+        name = path.relative_to(base).as_posix() if base else path.name
+        out.append({"name": name, "digest": {"sha256": sha256_file(path)}})
+    if not out:
+        raise RecordError("no subjects: the record must cover at least one file")
+    return out
+
+
+def statement(subjects: list[dict], predicate_type: str, predicate: dict) -> dict:
+    return {"_type": STATEMENT_TYPE, "subject": subjects, "predicateType": predicate_type, "predicate": predicate}
+
+
+def validate_predicate(predicate_type: str, predicate: dict) -> list[str]:
+    """Errors from validating a predicate against its JSON Schema (empty when valid)."""
+    schema_path = SCHEMA_FOR_TYPE.get(predicate_type)
+    if not schema_path:
+        return []
+    import jsonschema  # imported lazily: only the record commands need it
+
+    schema = json.loads(data_text(schema_path))
+    validator = jsonschema.Draft202012Validator(schema, format_checker=jsonschema.FormatChecker())
+    return [
+        f"{'/'.join(str(p) for p in err.absolute_path) or '(root)'}: {err.message}"
+        for err in sorted(validator.iter_errors(predicate), key=lambda e: list(e.absolute_path))
+    ]
+
+
+def ci_run() -> dict:
+    """Facts about the current GitHub Actions run, from the runner's environment."""
+    env = os.environ
+    server = env.get("GITHUB_SERVER_URL", "https://github.com")
+    repo = env.get("GITHUB_REPOSITORY", "")
+    run_id = env.get("GITHUB_RUN_ID", "")
+    out = {
+        "platform": "github-actions" if env.get("GITHUB_ACTIONS") == "true" else "local",
+        "repository": repo,
+        "runId": run_id,
+        "runAttempt": env.get("GITHUB_RUN_ATTEMPT", ""),
+        "url": f"{server}/{repo}/actions/runs/{run_id}" if repo and run_id else "",
+        "workflowRef": env.get("GITHUB_WORKFLOW_REF", ""),
+        "workflowSha": env.get("GITHUB_WORKFLOW_SHA", ""),
+        "eventName": env.get("GITHUB_EVENT_NAME", ""),
+        "actor": env.get("GITHUB_ACTOR", ""),
+        "triggeringActor": env.get("GITHUB_TRIGGERING_ACTOR", ""),
+        "runnerEnvironment": env.get("RUNNER_ENVIRONMENT", ""),
+    }
+    return {k: v for k, v in out.items() if v}
+
+
+def write_json(path: str | Path, obj: Any) -> None:
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(obj, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def obaaf_version() -> str:
+    return __version__

obaaf/attest/manifest.py

@@ -0,0 +1,143 @@
+"""The binary manifest (G2.1, item 2.6).
+
+A manifest records every vendored binary, SDK, engine build and plugin with its
+source, version and digest. `check` fails on any unrecorded change: a new file,
+a changed file or a missing file under a tracked path. Symbolic links are
+recorded with their targets, so replacing a file with a link, or retargeting a
+link, is a change too.
+
+Components are declared in a small YAML file, for example:
+
+    components:
+      - id: steamworks-sdk
+        name: Steamworks SDK
+        version: "1.62"
+        source: Steamworks partner site
+        kind: sdk
+        paths: ["ThirdParty/Steamworks/**"]
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import os
+from pathlib import Path
+
+from obaaf import yamlutil
+from obaaf.attest.common import RecordError, now, sha256_bytes, sha256_file, write_json
+
+FORMAT = "obaaf-manifest/v0.1"
+KINDS = {"sdk", "engine", "plugin", "middleware", "binary", "asset-pack", "tool"}
+
+
+def load_components(path: str | Path) -> list[dict]:
+    data = yamlutil.load_file(path) or {}
+    components = data.get("components") if isinstance(data, dict) else None
+    if not isinstance(components, list) or not components:
+        raise RecordError(f"{path}: expected a 'components' list")
+    seen = set()
+    for comp in components:
+        for key in ("id", "name", "version", "source", "kind", "paths"):
+            if not comp.get(key):
+                raise RecordError(f"{path}: component {comp.get('id', '?')} is missing {key!r}")
+        if comp["kind"] not in KINDS:
+            raise RecordError(f"{path}: component {comp['id']} has unknown kind {comp['kind']!r}")
+        if comp["id"] in seen:
+            raise RecordError(f"{path}: duplicate component id {comp['id']}")
+        seen.add(comp["id"])
+        comp["version"] = str(comp["version"])
+    return components
+
+
+def _matches(rel: str, patterns: list[str]) -> bool:
+    for pattern in patterns:
+        if fnmatch.fnmatchcase(rel, pattern):
+            return True
+        if pattern.endswith("/**") and (rel == pattern[:-3] or rel.startswith(pattern[:-2])):
+            return True
+    return False
+
+
+def _tracked_files(root: Path, components: list[dict]) -> dict[str, str]:
+    """Map each tracked file (relative path) to its component id. First matching component wins."""
+    owned: dict[str, str] = {}
+    for path in sorted(root.rglob("*")):
+        if not (path.is_symlink() or path.is_file()) or ".git" in path.relative_to(root).parts:
+            continue
+        rel = path.relative_to(root).as_posix()
+        for comp in components:
+            if _matches(rel, comp["paths"]):
+                owned[rel] = comp["id"]
+                break
+    return owned
+
+
+def create(root: str | Path, components_file: str | Path) -> dict:
+    root = Path(root)
+    components = load_components(components_file)
+    owned = _tracked_files(root, components)
+    empty = [c["id"] for c in components if c["id"] not in owned.values()]
+    if empty:
+        raise RecordError(f"no files match the paths of component(s): {', '.join(empty)}")
+    entries = [dict(_describe(root / rel), path=rel, component=comp) for rel, comp in sorted(owned.items())]
+    return {
+        "format": FORMAT,
+        "createdAt": now(),
+        "components": [
+            {k: c[k] for k in ("id", "name", "version", "source", "kind", "paths")} for c in components
+        ],
+        "entries": entries,
+    }
+
+
+def _describe(path: Path) -> dict:
+    """The digest of a file, or of a symbolic link's target text (the link is never followed)."""
+    if path.is_symlink():
+        target = os.readlink(path)
+        return {"sha256": sha256_bytes(target.encode("utf-8", "surrogateescape")), "size": 0, "symlink": target}
+    return {"sha256": sha256_file(path), "size": path.stat().st_size}
+
+
+def load(path: str | Path) -> dict:
+    manifest = json.loads(Path(path).read_text(encoding="utf-8"))
+    if manifest.get("format") != FORMAT:
+        raise RecordError(f"{path}: not an OBAAF manifest ({manifest.get('format')!r})")
+    return manifest
+
+
+def check(root: str | Path, manifest: dict) -> list[str]:
+    """Differences between the files on disk and the manifest (empty when they match)."""
+    root = Path(root)
+    recorded = {e["path"]: e for e in manifest["entries"]}
+    current = _tracked_files(root, manifest["components"])
+    problems = []
+    for rel in sorted(set(recorded) - set(current)):
+        problems.append(f"missing: {rel} is in the manifest but not on disk")
+    for rel in sorted(set(current) - set(recorded)):
+        problems.append(f"unrecorded: {rel} ({current[rel]}) is not in the manifest")
+    for rel in sorted(set(current) & set(recorded)):
+        actual = _describe(root / rel)
+        expected = recorded[rel]
+        if ("symlink" in actual) != ("symlink" in expected):
+            what = "a symbolic link" if "symlink" in actual else "a regular file"
+            problems.append(f"changed: {rel} is now {what}")
+        elif "symlink" in actual and actual["symlink"] != expected["symlink"]:
+            problems.append(f"changed: {rel} now links to {actual['symlink']!r}, the manifest records "
+                            f"{expected['symlink']!r}")
+        elif actual["sha256"] != expected["sha256"]:
+            problems.append(f"changed: {rel} has sha256 {actual['sha256']}, the manifest records {expected['sha256']}")
+    return problems
+
+
+def sdk_versions(manifest: dict) -> list[dict]:
+    """Components that ship to players or build the game, for the build record."""
+    return [
+        {"name": c["name"], "id": c["id"], "version": c["version"], "kind": c["kind"], "reportedBy": "manifest"}
+        for c in manifest["components"]
+        if c["kind"] in ("sdk", "engine", "plugin", "middleware")
+    ]
+
+
+def write(manifest: dict, out: str | Path) -> None:
+    write_json(out, manifest)