tan-cli 0.7.0__py3-none-any.whl

tan/core/jsonc_splice.py

@@ -0,0 +1,404 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Locate WHERE inside a launch.json's own raw text a single ``configurations``
+entry lives, so a write can splice just that entry instead of parsing the whole
+document and re-serialising it (tan-cli#182).
+
+Port of ``crates/tan-core/src/jsonc_splice.rs``. ``debug_launch`` already
+answers "what does this file MEAN" (``strip_jsonc`` + ``json.loads``); this
+module answers the narrower "where, in the ORIGINAL text, do the characters for
+element N of the top-level ``configurations`` array begin and end". The scan
+mirrors ``strip_jsonc``'s string/comment tracking so the two can never disagree
+about what counts as structure -- but nothing here builds a value; it only
+returns offsets into the caller's own string.
+
+The payoff: a caller that copies ``original[:start]`` and ``original[end:]``
+verbatim around a replacement never touches a comment, a trailing comma, or a
+leading BOM sitting outside the edited span -- there is no re-serialisation step
+for those characters to survive.
+
+[`locate_configuration_edit`] returns ``None`` whenever the raw text does not
+confidently resolve to a ``"configurations": [ ... ]`` array (missing key, wrong
+shape, any scan mismatch). The caller's documented fallback is the old
+whole-document re-serialise, which is always safe if lossy of comments, so a
+locator miss degrades gracefully instead of risking a malformed write.
+
+One deliberate simplification against the Rust: that `Scanner` carries a
+`Vec<(byte, char)>` and converts token index -> byte offset at every boundary,
+because Rust strings are byte-indexed and a multi-byte character would
+otherwise desynchronise the two. Python strings are indexed by code point and
+slice by code point, so index and offset are the same number here and the
+conversion layer has nothing to do. Same semantics, no `byte_at`.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+#: U+FEFF, spelled out rather than embedded: a literal BOM in source is
+#: invisible and the first editor or codec to normalise it away would silently
+#: turn the guard below into a no-op.
+BOM = "\ufeff"
+
+
+@dataclass(frozen=True)
+class SpliceEdit:
+    """Where to make the edit, as offsets into the ORIGINAL text.
+
+    ``kind == "replace"``: replace the configuration object spanning
+    ``[start, end)`` (``start`` is its ``{``, ``end`` one past the matching
+    ``}``) with the new entry, reindented using ``indent``.
+
+    ``kind == "append"``: insert a new entry immediately after offset ``start``
+    (the end of the array's last element, or just past its ``[`` when the array
+    is empty). ``needs_leading_comma`` is ``True`` when the element already
+    there is not followed by a trailing comma. ``closing_indent`` is set only
+    when appending into an array collapsed onto one line (``"configurations":
+    []`` -- VS Code's own stock template, the single most common real input):
+    ``original`` supplies no line break of its own before the ``]`` there, so
+    without it the appended entry's trailing newline drags the ``]`` down to
+    column 0 (tan-cli#182 review finding #5).
+    """
+
+    kind: str
+    start: int
+    indent: str
+    end: int = 0
+    needs_leading_comma: bool = False
+    closing_indent: str | None = None
+
+
+def locate_configuration_edit(original: str, index: int | None) -> SpliceEdit | None:
+    """Find where the ``index``-th configuration entry lives in ``original``
+    (``index is None`` means "no match -- append a fresh entry instead").
+
+    ``index`` counts ONLY object-shaped elements of the top-level
+    ``configurations`` array, in order -- the same filter
+    ``parse_launch_json_or_default`` applies before handing the array to
+    ``create_launch_json_write_plan``, so an index computed against that
+    filtered list passes straight through.
+    """
+    s = _Scanner(original)
+    array_open = _find_configurations_array(s)
+    if array_open is None:
+        return None
+
+    cursor = array_open + 1
+    object_spans: list[tuple[int, int]] = []
+    last_element_end: int | None = None
+    # Whether the LAST element seen was followed by a comma before `]`, and
+    # where that comma left the cursor -- an existing comma already separates
+    # "the last element" from "whatever comes next", so appending there reuses
+    # it instead of emitting a second one (`,,`).
+    trailing_comma = False
+    after_trailing_comma = 0
+    while True:
+        cursor = s.skip_ws_and_comments(cursor)
+        if s.char_at(cursor) == "]":
+            break
+        elem_start = cursor
+        is_object = s.char_at(cursor) == "{"
+        elem_end = s.skip_value(cursor)
+        if elem_end is None:
+            return None
+        if is_object:
+            object_spans.append((elem_start, elem_end))
+        last_element_end = elem_end
+        cursor = s.skip_ws_and_comments(elem_end)
+        char = s.char_at(cursor)
+        if char == ",":
+            cursor += 1
+            # Provisional: disproved below if another element follows -- the
+            # next iteration's own comma-or-`]` check overwrites both before
+            # they are ever read again.
+            trailing_comma = True
+            after_trailing_comma = cursor
+        elif char == "]":
+            trailing_comma = False
+            break
+        else:
+            return None
+
+    if index is not None:
+        if index >= len(object_spans):
+            return None
+        start, end = object_spans[index]
+        return SpliceEdit(
+            kind="replace", start=start, end=end, indent=_indent_before(original, start)
+        )
+
+    if last_element_end is not None:
+        # A pre-existing trailing comma already separates the last element from
+        # our new one, so insert AFTER it -- inserting before would leave the
+        # two elements adjacent with no separator and strand the comma as a
+        # second, now-orphaned trailing comma of its own.
+        if trailing_comma:
+            after, needs_leading_comma = after_trailing_comma, False
+        else:
+            after, needs_leading_comma = last_element_end, True
+        indent = (
+            _indent_before(original, object_spans[-1][0])
+            if object_spans
+            else _DEFAULT_INDENT
+        )
+        return SpliceEdit(
+            kind="append",
+            start=after,
+            indent=indent,
+            needs_leading_comma=needs_leading_comma,
+        )
+
+    # Empty array: insert right after the `[`. Indent one level deeper than the
+    # array's OWN line (not the flat default), so the entry lines up under
+    # whatever indentation width the rest of the file already uses.
+    array_line_indent = _indent_before(original, array_open)
+    # `cursor` still holds the position of the closing `]` (the loop broke on it
+    # before ever entering the element branch): collapsed onto one line (`[]`,
+    # no whitespace between the brackets) means `original` supplies no line
+    # break for `]` to land on, so supply the array's own indent explicitly. An
+    # already-multi-line empty array (`[\n]`) keeps its own formatting.
+    closing_indent = array_line_indent if cursor == array_open + 1 else None
+    return SpliceEdit(
+        kind="append",
+        start=array_open + 1,
+        indent=f"{array_line_indent}    ",
+        needs_leading_comma=False,
+        closing_indent=closing_indent,
+    )
+
+
+def apply_edit(original: str, edit: SpliceEdit, entry: Any) -> str:
+    """Apply a located edit, inserting ``entry`` (pretty-printed and reindented
+    to match where it lands) and returning the full new document. Every
+    character of ``original`` outside the edited span is copied through
+    unchanged -- that is the whole point: no re-serialisation pass runs over
+    them, so a comment, a trailing comma or a BOM elsewhere survives verbatim.
+    """
+    pretty = pretty_json(entry)
+    eol = _dominant_eol(original)
+    if edit.kind == "replace":
+        return (
+            original[: edit.start]
+            + _reindent(pretty, edit.indent, eol)
+            + original[edit.end :]
+        )
+    out = original[: edit.start]
+    if edit.needs_leading_comma:
+        out += ","
+    out += eol + edit.indent + _reindent(pretty, edit.indent, eol) + eol
+    if edit.closing_indent is not None:
+        out += edit.closing_indent
+    return out + original[edit.start :]
+
+
+def pretty_json(value: Any) -> str:
+    """`serde_json::to_string_pretty`'s shape: two-space indent, ``": "`` after
+    a key, no space after a comma, and non-ASCII emitted as itself rather than
+    escaped (serde does not escape it, and this text lands in a file a human
+    reads). ``json.dumps`` with an ``indent`` already defaults the item
+    separator to ``","``, so the two agree without spelling it out -- it IS
+    spelled out, because the default differs when ``indent`` is ``None`` and a
+    reader should not have to know which branch applies.
+    """
+    return json.dumps(value, indent=2, separators=(",", ": "), ensure_ascii=False)
+
+
+def _dominant_eol(original: str) -> str:
+    """The line ending already dominant in ``original`` -- ``\\r\\n`` if it holds
+    at least one, else ``\\n`` -- so a spliced-in entry's own newlines match its
+    neighbours instead of leaving a mixed-EOL file behind on a CRLF-authored
+    (Windows-default) launch.json (tan-cli#182 review finding #4).
+    """
+    return "\r\n" if "\r\n" in original else "\n"
+
+
+#: A pretty printer starts every nested line 2 spaces deeper than its parent; a
+#: brand-new array element one level under `"configurations": [` (itself one
+#: level under the document root) lands at 4 spaces with no existing sibling to
+#: copy a style from.
+_DEFAULT_INDENT = "    "
+
+
+def _reindent(pretty: str, indent: str, eol: str) -> str:
+    """Re-prefix every line of ``pretty`` AFTER the first with ``indent``,
+    joined with ``eol`` rather than a bare ``\\n``. The first line is left
+    alone: for a replace it takes the position of the old ``{``, already after
+    whatever indentation preceded it; for an append the caller pushes ``indent``
+    itself before calling.
+    """
+    lines = pretty.split("\n")
+    return lines[0] + "".join(f"{eol}{indent}{line}" for line in lines[1:])
+
+
+def _indent_before(text: str, pos: int) -> str:
+    """The whitespace-only run from the start of ``pos``'s line up to ``pos``,
+    if it IS whitespace-only; otherwise [`_DEFAULT_INDENT`]. Matches a
+    new/replaced entry's indentation to its neighbours."""
+    before = text[:pos]
+    line_start = before.rfind("\n") + 1  # -1 + 1 == 0 when there is no newline
+    candidate = before[line_start:]
+    if candidate and all(c in " \t" for c in candidate):
+        return candidate
+    return _DEFAULT_INDENT
+
+
+def _find_configurations_array(s: _Scanner) -> int | None:
+    """Scan the top-level object for a ``"configurations"`` key and return the
+    offset of its value's opening ``[``, or ``None`` if the key is absent, is
+    not the very next thing after ``:``, or the document does not open with
+    ``{`` at all (every case the caller treats as "fall back to full
+    re-serialise").
+
+    A SECOND top-level ``"configurations"`` key also returns ``None``: JSON does
+    not forbid a duplicate key, and ``json.loads`` (like VS Code's own
+    jsonc-parser) resolves one to its LAST occurrence, but this scan would hand
+    back the FIRST -- splicing into the array nothing downstream reads, while
+    the caller's index (computed against the parsed, last-wins document)
+    silently addresses the other one (tan-cli#182 review finding #3).
+    """
+    p = s.skip_ws_and_comments(0)
+    if s.char_at(p) != "{":
+        return None
+    p += 1
+    found: int | None = None
+    while True:
+        p = s.skip_ws_and_comments(p)
+        char = s.char_at(p)
+        if char == "}":
+            return found
+        if char == ",":
+            p += 1
+            continue
+        if char != '"':
+            return None
+        key_start = p
+        key_end = s.skip_string(p)
+        if key_end is None:
+            return None
+        key_text = s.text[key_start + 1 : key_end - 1]
+        p = s.skip_ws_and_comments(key_end)
+        if s.char_at(p) != ":":
+            return None
+        p = s.skip_ws_and_comments(p + 1)
+        if key_text == "configurations":
+            if found is not None:
+                return None
+            if s.char_at(p) != "[":
+                return None
+            found = p
+        nxt = s.skip_value(p)
+        if nxt is None:
+            return None
+        p = nxt
+
+
+class _Scanner:
+    """Char-offset view over the source text, with the same string/comment
+    tracking ``strip_jsonc`` uses -- so the two can never disagree about what
+    counts as JSON structure vs quoted text vs a comment."""
+
+    def __init__(self, text: str) -> None:
+        self.text = text
+
+    def char_at(self, p: int) -> str | None:
+        """The character at ``p``, or ``None`` past the end. Guarded rather than
+        sliced blindly: a NEGATIVE index would wrap to the end of the string and
+        silently restart the scan there."""
+        if 0 <= p < len(self.text):
+            return self.text[p]
+        return None
+
+    def skip_ws_and_comments(self, p: int) -> int:
+        """Skip whitespace, a stray BOM, and ``//`` / ``/* */`` comments."""
+        while True:
+            char = self.char_at(p)
+            if char is None:
+                return p
+            if char.isspace() or char == BOM:
+                p += 1
+            elif char == "/" and self.char_at(p + 1) == "/":
+                p += 2
+                while (c := self.char_at(p)) is not None:
+                    p += 1
+                    if c == "\n":
+                        break
+            elif char == "/" and self.char_at(p + 1) == "*":
+                p += 2
+                while True:
+                    c = self.char_at(p)
+                    if c is None:
+                        break
+                    if c == "*" and self.char_at(p + 1) == "/":
+                        p += 2
+                        break
+                    p += 1
+            else:
+                return p
+
+    def skip_string(self, p: int) -> int | None:
+        """Skip a JSON string starting at its opening ``"``; returns the offset
+        just past the closing ``"``, or ``None`` if it never closes."""
+        q = p + 1
+        while True:
+            char = self.char_at(q)
+            if char is None:
+                return None
+            if char == "\\":
+                q += 2
+            elif char == '"':
+                return q + 1
+            else:
+                q += 1
+
+    def skip_balanced(self, p: int) -> int | None:
+        """Skip a balanced ``{...}``/``[...]`` region starting at its opening
+        bracket, tracking nested brackets/strings/comments so one inside a
+        string or comment is never mistaken for structure. ``None`` if it never
+        balances."""
+        depth = 0
+        q = p
+        while True:
+            char = self.char_at(q)
+            if char is None:
+                return None
+            if char == '"':
+                nxt = self.skip_string(q)
+                if nxt is None:
+                    return None
+                q = nxt
+            elif char == "/" and self.char_at(q + 1) in ("/", "*"):
+                q = self.skip_ws_and_comments(q)
+            elif char in "{[":
+                depth += 1
+                q += 1
+            elif char in "}]":
+                depth -= 1
+                q += 1
+                if depth == 0:
+                    return q
+            else:
+                q += 1
+
+    def skip_value(self, p: int) -> int | None:
+        """Skip one JSON value (string/object/array/number/true/false/null);
+        returns the offset just past it, or ``None`` on a value that never
+        terminates."""
+        char = self.char_at(p)
+        if char is None:
+            return None
+        if char == '"':
+            return self.skip_string(p)
+        if char in "{[":
+            return self.skip_balanced(p)
+        # number / true / false / null: run until a structural delimiter. A `/`
+        # is checked separately so a comment with no preceding space
+        # (`nullfoo//c`) is never folded into it.
+        q = p
+        while (c := self.char_at(q)) is not None:
+            if c in ",}]" or c.isspace():
+                break
+            if c == "/" and self.char_at(q + 1) in ("/", "*"):
+                break
+            q += 1
+        return q if q != p else None

tan/core/launch_provenance.py

@@ -0,0 +1,257 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The ``.alp/debug-launch-provenance.json`` sidecar ``tan debug-config``
+reads and writes alongside ``.vscode/launch.json`` -- a content-hash record
+of which ``configFiles``/``setupCommands`` list entries a PRIOR
+tan-authored write itself produced, so the next run's merge
+(``debug_launch._merge_list_by_identity``) can tell "tan wrote this, safe to
+update or retract" apart from "the customer's, leave it alone" without
+relying on POSITION. tan-cli#518, the gap tan-cli#489's own docstring names
+as a "Known, accepted limitation" (``debug_launch.py``'s
+``_merge_list_by_identity``).
+
+tan-cli#1020 review widened this sidecar to a THIRD field, ``loadFiles``
+(tan-cli#945) -- the same content-hash record, read by the same
+:meth:`LaunchProvenance.hashes_for`, but consumed by a DIFFERENT merge rule
+(``debug_launch._merge_load_files``, not ``_merge_list_by_identity``): a
+``loadFiles`` this run cannot prove it wrote is left untouched WHOLESALE
+(never appended-to, unlike ``configFiles``/``setupCommands``), because it
+names one deliberate artefact list -- possibly an explicit ``[]`` for
+attach-only -- not a set of independently-owned entries. This module itself
+needed no change for that: `hashes_for`/`updated`/`record` are already
+generic over the field name.
+
+## Why content hash, and why a sidecar at all
+
+The design decision (tan-cli#518, 2026-08-28) rules out an in-file marker:
+``launch.json`` is schema-validated by VS Code against the debug adapter's
+own contract, and an unknown property inside a ``configurations[]`` entry
+draws a permanent squiggle in the customer's editor -- "that warning is
+ours, ignore it" is not something a tool should ever require of its own
+output. So the record lives beside ``launch.json``, in ``.alp/`` (the same
+directory ``tan init``'s own ``sdk-path`` pointer already occupies --
+``init_cmd.py``, ``bootstrap_cmd._project_pin_file``), never inside it.
+``launch.json`` itself is byte-for-byte unaffected by this module: no new
+key, no comment, nothing ``jsonc_splice``'s span-preserving edits need to
+know about.
+
+Position was the ORIGINAL provenance proxy (tan-cli#489's anchor-relative
+placement) and it has exactly one failure mode: a customer's own hand-added
+entry that happens to fall into the position tan is about to reuse gets
+silently overwritten, indistinguishable from tan's own prior output sitting
+there. A NAME would have the same flaw one layer up -- ``configFiles``
+entries have no name at all, and ``setupCommands``' own ``text`` field is
+exactly the identity ``_list_item_identity`` already matches by (matching by
+identity already never reaches position; only an UNMATCHED entry does).
+Content hash is the one thing that is stable across reordering and a
+reformatting round-trip (see ``content_hash`` below) yet changes the instant
+a human -- or a formatter with different defaults -- touches the actual
+value.
+
+## The asymmetry this whole module exists to preserve
+
+Every desync degrades the SAME direction: a missing file, corrupt JSON, a
+schema this build does not recognise, an entry whose hash was never
+recorded, a stale record left over from a run that resolved something
+different -- all of them read as "not tan's", never as "tan's, go ahead".
+:func:`load` never raises; every failure returns :func:`empty`, the record
+that owns nothing. A customer who deletes
+``.alp/debug-launch-provenance.json`` outright gets exactly that: tan
+forgets what it wrote and starts leaving every existing list entry alone
+(``debug_launch._merge_list_by_identity``'s position-based pass degrades to
+append-only without a confirmed hash) -- a mildly stale entry the customer
+can delete in one keystroke, never a deleted customer edit. The SIDECAR
+re-establishes itself from the very next write, so the MECHANISM's
+degradation is one run, not permanent -- but a list entry it left stranded
+during that one run (appended beside a value it could not prove was its
+own) is not retroactively cleaned up once the sidecar heals; it stays in
+``launch.json`` until the customer deletes it themselves. See
+``debug_launch.sdk_identity_stranded_appends`` (surfaced by
+``debug_config_cmd.py`` as ``debug-config.sdk-identity-appended``) for the
+disclosure that names it rather than leaving it silent.
+
+**``loadFiles`` heals the same way for the same reason, but only from ONE
+specific starting point** (tan-cli#1020 re-review): a sidecar loss re-derives
+provenance the instant the field itself is next observed absent from the
+existing entry -- the pre-#945 upgrade shape, and the only case where there
+is provably nothing to protect (``debug_launch._merge_configuration``'s
+key-absent branch records what it just wrote, exactly like a brand-new
+entry). A sidecar lost while the KEY WAS ALREADY PRESENT -- a genuinely
+tan-authored value, or a customer's own -- cannot re-derive provenance from
+observation alone, because ``_merge_load_files``'s protect branch (unlike
+``configFiles``/``setupCommands``'s append) makes no write of its own to
+attribute: recording ownership of an untouched value the sidecar merely
+forgot would be indistinguishable, to the very next run, from recording
+ownership of a customer's own untouched value, which is the exact silent-
+overwrite failure tan-cli#518/#1020's protect rule exists to prevent. So
+that narrower case stays protected -- and disclosed, every run, via
+``debug-config.load-files-preserved`` -- until the customer's own edit (or a
+value that happens to already match the fresh resolution) lets it agree
+again; it does not "heal" the way an appended `configFiles` entry's
+provenance does.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+#: Sidecar schema version. A `load` that sees anything else treats the whole
+#: file as unrecognised -- the safe direction for a shape a future (or past)
+#: build cannot confidently parse; see `load`.
+SCHEMA_VERSION = 1
+
+#: `<workspace_root>/.alp/debug-launch-provenance.json` -- beside `tan
+#: init`'s own `.alp/sdk-path` (`init_cmd.py`, `bootstrap_cmd._project_pin_
+#: file`), never inside `.vscode/launch.json` itself.
+SIDECAR_RELATIVE_PATH = (".alp", "debug-launch-provenance.json")
+
+
+def sidecar_path(workspace_root: str | Path) -> Path:
+    """The sidecar path for a workspace root, following the same
+    `.alp/<file>` convention `tan init`/`tan sdk` already use."""
+    return Path(workspace_root).joinpath(*SIDECAR_RELATIVE_PATH)
+
+
+def content_hash(value: Any) -> str:
+    """A stable hash of a `configFiles`/`setupCommands` list ENTRY's
+    semantic content. `json.dumps(..., sort_keys=True)` canonicalises key
+    order before hashing, so re-serialising an unchanged `setupCommands`
+    dict with a different key order (an external formatter, a hand-edit
+    that only reordered `text`/`ignoreFailures`) hashes IDENTICAL to what
+    tan itself wrote, and is never mistaken for a customer edit -- the exact
+    property the issue names: "re-serialisation with different key order or
+    whitespace must not read as an edit". Whitespace never reaches the hash
+    at all, because this hashes the PARSED value, not raw text.
+    """
+    canonical = json.dumps(value, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+@dataclass
+class LaunchProvenance:
+    """The parsed sidecar: per-configuration-name, per-list-field sets of
+    content hashes tan itself wrote the last time a run touched that field.
+
+    Immutable from the outside -- :meth:`updated` is the only way a caller
+    (`debug_launch.create_launch_json_write_plan`) ever changes one, and it
+    always returns a NEW record rather than mutating `self`, so a
+    `LaunchJsonWritePlan` never rewrites the `LaunchProvenance` its own
+    caller is still holding a reference to.
+    """
+
+    _by_config: dict[str, dict[str, list[str]]] = field(default_factory=dict)
+
+    def hashes_for(self, configuration_name: str, list_field: str) -> frozenset[str]:
+        """The hashes tan recorded for `list_field` (`configFiles` /
+        `setupCommands`) the last time it wrote `configuration_name` --
+        empty when the configuration, the field, or the whole sidecar was
+        never recorded (or could not be read; see `load`). Empty is the
+        safe default everywhere this is called from: it is exactly the
+        "nothing is ours" set."""
+        return frozenset(self._by_config.get(configuration_name, {}).get(list_field, ()))
+
+    def record(self, configuration_name: str, list_field: str, entries: list[Any]) -> None:
+        """Replace `list_field`'s recorded hash set for `configuration_name`
+        with the hashes of exactly `entries` -- MUTATES `self`; only
+        :meth:`updated` (which always operates on a fresh copy) calls this
+        directly."""
+        config = self._by_config.setdefault(configuration_name, {})
+        config[list_field] = [content_hash(entry) for entry in entries]
+
+    def updated(
+        self, configuration_name: str, owned_entries: dict[str, list[Any]]
+    ) -> LaunchProvenance:
+        """A NEW record equal to `self` except `configuration_name`'s fields
+        named in `owned_entries` are replaced by the hashes of exactly
+        those entries -- the list entries THIS run identified as
+        tan-authored (matched, positionally placed, or freshly appended;
+        never an entry `debug_launch._merge_list_by_identity`'s pass 3
+        left untouched, and never a field the run did not touch at all --
+        that field, absent from `owned_entries`, keeps whatever `self`
+        already had for it).
+
+        A field this run DID touch is fully REPLACED, never merged with its
+        own stale entries: an entry that vanishes from this run's draft
+        resolution must not leave a phantom hash behind for something
+        unrelated to accidentally match against later. This is the
+        pure-functional twin of :meth:`record` -- `create_launch_json_write_
+        plan` never mutates the `provenance` object a caller handed it.
+        """
+        result = LaunchProvenance(
+            {name: dict(fields) for name, fields in self._by_config.items()}
+        )
+        for list_field, entries in owned_entries.items():
+            result.record(configuration_name, list_field, entries)
+        return result
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "schemaVersion": SCHEMA_VERSION,
+            "configurations": {
+                name: dict(fields) for name, fields in self._by_config.items() if fields
+            },
+        }
+
+
+def empty() -> LaunchProvenance:
+    """The record that owns nothing -- what every unreadable, missing, or
+    schema-unrecognised sidecar degrades to. tan-cli#518's whole point: a
+    desync must read as "not tan's", never as "everything is tan's"."""
+    return LaunchProvenance()
+
+
+def load(content: str | None) -> LaunchProvenance:
+    """Parse a sidecar's raw text into a :class:`LaunchProvenance`. Never
+    raises -- anything this cannot confidently parse (`None`, empty, not
+    JSON, not an object, a `configurations` that is not an object, a
+    `schemaVersion` this build does not recognise, or a per-field value that
+    is not a list of strings) returns :func:`empty` rather than guessing,
+    per this module's own asymmetry (see the module docstring). A caller
+    that could not even READ the file (permission denied, an I/O error) is
+    expected to pass `None` here for exactly the same reason -- this
+    function draws no distinction between "absent" and "unreadable"; both
+    mean "nothing is ours".
+    """
+    if not content:
+        return empty()
+    try:
+        document = json.loads(content)
+    except json.JSONDecodeError:
+        return empty()
+    if not isinstance(document, dict):
+        return empty()
+    if document.get("schemaVersion") != SCHEMA_VERSION:
+        return empty()
+    configurations = document.get("configurations")
+    if not isinstance(configurations, dict):
+        return empty()
+    by_config: dict[str, dict[str, list[str]]] = {}
+    for name, fields in configurations.items():
+        if not isinstance(name, str) or not isinstance(fields, dict):
+            continue
+        clean_fields: dict[str, list[str]] = {}
+        for field_name, hashes in fields.items():
+            if (
+                isinstance(field_name, str)
+                and isinstance(hashes, list)
+                and all(isinstance(h, str) for h in hashes)
+            ):
+                clean_fields[field_name] = hashes
+        if clean_fields:
+            by_config[name] = clean_fields
+    return LaunchProvenance(by_config)
+
+
+def render(record: LaunchProvenance) -> str:
+    """The sidecar's own pretty-printed bytes, trailing newline included --
+    the same two-space-indent shape `jsonc_splice.pretty_json` uses for
+    `launch.json`'s own fresh-file fallback, so a customer who opens either
+    file in `.alp`/`.vscode` sees the same formatting convention. Unlike
+    `launch.json`, this file is tan's own bookkeeping -- there is no
+    customer content in it to preserve byte-for-byte, so it is always a
+    plain whole-file re-serialise; nothing here ever needs `jsonc_splice`.
+    """
+    return json.dumps(record.to_json(), indent=2, sort_keys=True) + "\n"