gcf-python 2.2.2__py3-none-any.whl → 2.5.0__py3-none-any.whl

gcf/generic_delta.py

@@ -0,0 +1,487 @@
+"""GCF generic-profile delta encoding (SPEC Section 10a).
+
+Producer + consumer. Mirrors the gcf-go reference implementation; the shared
+conformance fixtures (generic-pack-root/, generic-delta/) hold both to identical
+bytes and hashes.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from .scalar import (
+    format_key,
+    format_number,
+    format_scalar,
+    parse_scalar,
+    quote_string,
+    split_respecting_quotes,
+)
+
+
+@dataclass
+class GenericSet:
+    """A keyed record set: the unit generic-profile delta operates on (Section 10a).
+
+    Rows are order-agnostic (set semantics); ``fields`` carries the declared column
+    order for the wire form; ``key`` names the identity column (the ``@id`` / ``key=``);
+    ``name`` is the tabular section name for a full payload.
+    """
+
+    key: str
+    fields: list[str]
+    rows: list[dict[str, Any]]
+    name: str = "rows"
+
+
+@dataclass
+class GenericDeltaPayload:
+    key: str
+    fields: list[str]
+    base_root: str = ""
+    new_root: str = ""
+    added: list[dict[str, Any]] = field(default_factory=list)
+    changed: list[dict[str, Any]] = field(default_factory=list)
+    removed: list[Any] = field(default_factory=list)
+    tool: str = ""
+    delta_tokens: int = 0
+    full_tokens: int = 0
+
+
+def _canonical_cell(v: Any) -> str:
+    """Canonicalize one value for the pack-root record (Section 10a.3).
+
+    Decoupled from the wire cell encoder: collision-free and record-safe, not
+    round-trippable. Typed literals stay bare (null is ``-``, booleans true/false,
+    numbers canonical); strings are ALWAYS quoted so they cannot collide with a
+    typed literal and any tab/newline inside is escaped.
+    """
+    if v is None:
+        return "-"
+    if isinstance(v, bool):  # must precede int: bool is a subclass of int
+        return "true" if v else "false"
+    if isinstance(v, (int, float)):
+        return format_number(float(v))
+    if isinstance(v, str):
+        return quote_string(v)
+    return quote_string(str(v))
+
+
+def generic_pack_root(s: GenericSet) -> str:
+    """Canonical pack root for a keyed set (gcf-pack-root-v1, generic profile, 10a.3).
+
+    Records and fields are sorted by unsigned UTF-8 byte order to match every SDK.
+    """
+    sorted_fields = sorted(s.fields, key=lambda x: x.encode("utf-8"))
+    records: list[str] = []
+    for row in s.rows:
+        parts = ["R"]
+        for f in sorted_fields:
+            parts.append(f)
+            parts.append(_canonical_cell(row.get(f)))
+        records.append("\t".join(parts) + "\n")
+    records.sort(key=lambda r: r.encode("utf-8"))
+    digest = hashlib.sha256("".join(records).encode("utf-8")).hexdigest()
+    return "sha256:" + digest
+
+
+def _index_by_key(s: GenericSet) -> dict[str, dict[str, Any]]:
+    m: dict[str, dict[str, Any]] = {}
+    for row in s.rows:
+        ident = _canonical_cell(row.get(s.key))
+        if ident in m:
+            raise ValueError(f"delta_invalid: duplicate identity {ident} for key {s.key!r}")
+        m[ident] = row
+    return m
+
+
+def _rows_equal(a: dict[str, Any], b: dict[str, Any], fields: list[str]) -> bool:
+    return all(_canonical_cell(a.get(f)) == _canonical_cell(b.get(f)) for f in fields)
+
+
+def diff_generic_sets(base: GenericSet, nxt: GenericSet) -> GenericDeltaPayload:
+    """Compute the delta from ``base`` to ``nxt`` (the blessed producer path).
+
+    Centralizes the keyed-diff invariants: identity uniqueness, added-not-in-base,
+    changed-must-exist, whole-row replacement, unchanged rows omitted. Output is
+    sorted by identity for reproducibility (10a.6). Schema change or a missing key
+    raises (caller must send full, 10a.7).
+    """
+    if not nxt.key:
+        raise ValueError("delta_invalid: no identity key")
+    if nxt.key != base.key or list(base.fields) != list(nxt.fields):
+        raise ValueError("delta_invalid: schema change (send full)")
+
+    base_by_id = _index_by_key(base)
+    next_by_id = _index_by_key(nxt)
+
+    d = GenericDeltaPayload(
+        key=nxt.key,
+        fields=list(nxt.fields),
+        base_root=generic_pack_root(base),
+        new_root=generic_pack_root(nxt),
+    )
+    for ident, row in next_by_id.items():
+        brow = base_by_id.get(ident)
+        if brow is None:
+            d.added.append(row)
+        elif not _rows_equal(brow, row, nxt.fields):
+            d.changed.append(row)
+        # equal rows are omitted (silence = "keep it", 10a.5)
+    for ident, brow in base_by_id.items():
+        if ident not in next_by_id:
+            d.removed.append(brow.get(nxt.key))
+
+    d.added.sort(key=lambda r: _canonical_cell(r.get(d.key)))
+    d.changed.sort(key=lambda r: _canonical_cell(r.get(d.key)))
+    d.removed.sort(key=_canonical_cell)
+    return d
+
+
+def _field_decl(fields: list[str], key: str) -> str:
+    return ",".join(("@" + format_key(f)) if f == key else format_key(f) for f in fields)
+
+
+def _encode_row(row: dict[str, Any], fields: list[str]) -> str:
+    return "|".join(format_scalar(row.get(f), "|") for f in fields)
+
+
+def encode_generic_full(s: GenericSet, tool: str = "") -> str:
+    """Emit a delta-participating full base payload: key= header, @id field, rows."""
+    name = s.name or "rows"
+    header = "GCF profile=generic"
+    if tool:
+        header += f" tool={tool}"
+    header += f" pack_root={generic_pack_root(s)} key={s.key}"
+    lines = [header, f"## {name} [{len(s.rows)}]{{{_field_decl(s.fields, s.key)}}}"]
+    lines += [_encode_row(row, s.fields) for row in s.rows]
+    return "\n".join(lines) + "\n"
+
+
+def encode_generic_delta(d: GenericDeltaPayload) -> str:
+    """Serialize a delta payload (10a.2). Sections ordered added/changed/removed."""
+    header = "GCF profile=generic"
+    if d.tool:
+        header += f" tool={d.tool}"
+    header += f" delta=true base_root={d.base_root} new_root={d.new_root} key={d.key}"
+    if d.full_tokens > 0:
+        savings = 100.0 * (1.0 - d.delta_tokens / d.full_tokens)
+        header += f" savings={savings:.0f}%"
+    lines = [header]
+    if d.added:
+        lines.append(f"## added [{len(d.added)}]{{{_field_decl(d.fields, d.key)}}}")
+        lines += [_encode_row(r, d.fields) for r in d.added]
+    if d.changed:
+        lines.append(f"## changed [{len(d.changed)}]{{{_field_decl(d.fields, d.key)}}}")
+        lines += [_encode_row(r, d.fields) for r in d.changed]
+    if d.removed:
+        lines.append(f"## removed [{len(d.removed)}]{{@{d.key}}}")
+        lines += [format_scalar(idv, "|") for idv in d.removed]
+    return "\n".join(lines) + "\n"
+
+
+def verify_generic_delta(base: GenericSet, d: GenericDeltaPayload, expected_new_root: str) -> GenericSet:
+    """Apply a delta to a base set and verify the result hashes to expected_new_root.
+
+    Atomic (10a.5): the whole payload is validated before any mutation; on failure the
+    base is left untouched and a ValueError is raised.
+    """
+    if generic_pack_root(base) != d.base_root:
+        raise ValueError("base_mismatch: base root does not equal delta base_root")
+    base_by_id = _index_by_key(base)
+
+    for idv in d.removed:
+        if _canonical_cell(idv) not in base_by_id:
+            raise ValueError(f"delta_invalid: removing identity {_canonical_cell(idv)} not in base")
+    for row in d.added:
+        if _canonical_cell(row.get(d.key)) in base_by_id:
+            raise ValueError(f"delta_invalid: adding identity {_canonical_cell(row.get(d.key))} that already exists")
+    for row in d.changed:
+        if _canonical_cell(row.get(d.key)) not in base_by_id:
+            raise ValueError(f"delta_invalid: changing identity {_canonical_cell(row.get(d.key))} not in base")
+
+    work = dict(base_by_id)
+    for idv in d.removed:
+        work.pop(_canonical_cell(idv), None)
+    for row in d.added:
+        work[_canonical_cell(row.get(d.key))] = row
+    for row in d.changed:
+        work[_canonical_cell(row.get(d.key))] = row
+
+    result = GenericSet(key=base.key, fields=list(base.fields), rows=list(work.values()), name=base.name)
+    got = generic_pack_root(result)
+    if got != expected_new_root:
+        raise ValueError(f"root_mismatch: computed {got}, expected {expected_new_root}")
+    return result
+
+
+# --- consumer-side wire parsing ---
+
+
+def _parse_header_fields(header: str) -> dict[str, str]:
+    m: dict[str, str] = {}
+    for tok in header.split():
+        if "=" in tok:
+            k, _, v = tok.partition("=")
+            if k:
+                m[k] = v
+    return m
+
+
+def _parse_count(s: str) -> int:
+    if s == "0":
+        return 0
+    if not s or s[0] == "0" or not s.isdigit():
+        raise ValueError(f"invalid_count: {s}")
+    return int(s)
+
+
+def _split_delta_field_decl(decl: str) -> tuple[list[str], str]:
+    if len(decl) < 2 or decl[0] != "{" or decl[-1] != "}":
+        raise ValueError(f"invalid field declaration: {decl}")
+    inner = decl[1:-1]
+    if inner == "":
+        return [], ""
+    fields: list[str] = []
+    key_field = ""
+    for raw in split_respecting_quotes(inner, ","):
+        f = raw.strip()
+        is_key = False
+        if f.startswith("@"):
+            f = f[1:]
+            is_key = True
+        if len(f) >= 2 and f[0] == '"' and f[-1] == '"':
+            from .scalar import parse_quoted_string
+
+            f = parse_quoted_string(f)
+        if is_key:
+            key_field = f
+        fields.append(f)
+    return fields, key_field
+
+
+def _parse_section_header(content: str) -> tuple[str, int, list[str], str]:
+    bi = content.find(" [")
+    if bi < 0:
+        raise ValueError(f"delta_invalid: section header without count: {content!r}")
+    name = content[:bi].strip()
+    rest = content[bi + 1:]  # "[N]{...}"
+    if not rest or rest[0] != "[":
+        raise ValueError(f"delta_invalid: malformed section header: {content!r}")
+    close = rest.find("]")
+    if close < 0:
+        raise ValueError(f"delta_invalid: unterminated count: {content!r}")
+    count = _parse_count(rest[1:close])
+    fields, key_field = _split_delta_field_decl(rest[close + 1:])
+    return name, count, fields, key_field
+
+
+def _parse_row(line: str, fields: list[str]) -> dict[str, Any]:
+    cells = split_respecting_quotes(line, "|")
+    if len(cells) != len(fields):
+        raise ValueError(f"delta_invalid: row has {len(cells)} cells, expected {len(fields)}: {line!r}")
+    return {f: parse_scalar(cells[i], True) for i, f in enumerate(fields)}
+
+
+def decode_generic_full(text: str) -> tuple[GenericSet, str]:
+    """Parse a delta-participating full base payload into (GenericSet, pack_root)."""
+    lines = text.rstrip("\n").split("\n")
+    if not lines:
+        raise ValueError("empty payload")
+    hdr = _parse_header_fields(lines[0])
+    if hdr.get("profile") != "generic":
+        raise ValueError("not a generic payload")
+    s = GenericSet(key=hdr.get("key", ""), fields=[], rows=[])
+    i = 1
+    while i < len(lines):
+        line = lines[i]
+        if not line.startswith("## "):
+            i += 1
+            continue
+        name, count, fields, key_field = _parse_section_header(line[3:])
+        s.name, s.fields = name, fields
+        if not s.key:
+            s.key = key_field
+        i += 1
+        for _ in range(count):
+            if i >= len(lines):
+                raise ValueError("delta_invalid: fewer rows than declared count")
+            s.rows.append(_parse_row(lines[i], fields))
+            i += 1
+    return s, hdr.get("pack_root", "")
+
+
+def decode_generic_delta(text: str) -> GenericDeltaPayload:
+    """Parse a delta payload (10a.2) into a GenericDeltaPayload for application."""
+    lines = text.rstrip("\n").split("\n")
+    if not lines:
+        raise ValueError("empty payload")
+    hdr = _parse_header_fields(lines[0])
+    if hdr.get("profile") != "generic":
+        raise ValueError("not a generic payload")
+    if hdr.get("delta") != "true":
+        raise ValueError("not a delta payload")
+    d = GenericDeltaPayload(
+        key=hdr.get("key", ""),
+        fields=[],
+        base_root=hdr.get("base_root", ""),
+        new_root=hdr.get("new_root", ""),
+        tool=hdr.get("tool", ""),
+    )
+    i = 1
+    while i < len(lines):
+        line = lines[i]
+        if not line.startswith("## "):
+            i += 1
+            continue
+        name, count, fields, key_field = _parse_section_header(line[3:])
+        if not d.key and key_field:
+            d.key = key_field
+        if not d.fields and name in ("added", "changed"):
+            d.fields = fields
+        i += 1
+        if name in ("added", "changed"):
+            rows = []
+            for _ in range(count):
+                if i >= len(lines):
+                    raise ValueError(f"delta_invalid: fewer rows than declared count in ## {name}")
+                rows.append(_parse_row(lines[i], fields))
+                i += 1
+            if name == "added":
+                d.added = rows
+            else:
+                d.changed = rows
+        elif name == "removed":
+            for _ in range(count):
+                if i >= len(lines):
+                    raise ValueError("delta_invalid: fewer identities than declared count in ## removed")
+                d.removed.append(parse_scalar(lines[i], True))
+                i += 1
+        else:
+            raise ValueError(f"delta_invalid: unknown delta section {name!r}")
+    return d
+
+
+# --- producer-side re-anchor session helper (SPEC Section 10a.8) ---
+#
+# GenericDeltaSession manages the re-anchor cadence for a stream of
+# generic-profile updates. It is thin sugar over the primitives: each ``next``
+# emits either a compact delta or, on its chosen cadence, a full re-anchor,
+# updating its held base. It introduces NO new wire syntax: every payload it
+# emits is exactly what ``encode_generic_full`` or ``encode_generic_delta``
+# produce, and the decoder accepts them cadence-agnostically. N and the size
+# guard are the helper's knobs; they are never wire fields. (Section 10a.8 is
+# non-normative producer policy.)
+
+
+# The working default cadence for FixedN (SPEC Section 10a.8).
+DEFAULT_REANCHOR_N = 15
+
+
+class ReanchorMode(Enum):
+    """Selects the session's cadence policy."""
+
+    FIXED_N = 0  # re-anchor every N turns
+    SIZE_GUARD = 1  # re-anchor once cumulative delta reaches the full payload's size
+
+
+@dataclass
+class ReanchorPolicy:
+    """Selects when a :class:`GenericDeltaSession` re-anchors.
+
+    Construct it with :func:`fixed_n` or :func:`size_guard`.
+    """
+
+    mode: ReanchorMode = ReanchorMode.FIXED_N
+    n: int = 0  # turns between anchors; FixedN only
+
+
+def fixed_n(n: int) -> ReanchorPolicy:
+    """Re-anchor every ``n`` turns. ``n <= 0`` falls back to ``DEFAULT_REANCHOR_N``."""
+    if n <= 0:
+        n = DEFAULT_REANCHOR_N
+    return ReanchorPolicy(mode=ReanchorMode.FIXED_N, n=n)
+
+
+def size_guard() -> ReanchorPolicy:
+    """Re-anchor once the cumulative delta bytes since the last anchor reach the
+    current full payload's byte size: it re-anchors more under heavy churn, rarely
+    under light churn, and bounds the delta spent between anchors to about one full
+    payload. Production-recommended.
+    """
+    return ReanchorPolicy(mode=ReanchorMode.SIZE_GUARD)
+
+
+def _byte_len(s: str) -> int:
+    """UTF-8 byte length, matching Go's ``len(string)`` (bytes, not code points)."""
+    return len(s.encode("utf-8"))
+
+
+class GenericDeltaSession:
+    """Holds the current base and re-anchor state for a producer loop.
+
+    Not safe for concurrent use. Call :meth:`current_full` to get the initial
+    full payload to transmit, then :meth:`next` for each subsequent state.
+    """
+
+    def __init__(self, base: GenericSet, tool: str, policy: ReanchorPolicy) -> None:
+        if policy.mode == ReanchorMode.FIXED_N and policy.n <= 0:
+            policy = ReanchorPolicy(mode=policy.mode, n=DEFAULT_REANCHOR_N)
+        self._base = base
+        self._tool = tool
+        self._policy = policy
+        self._turn = 0
+        self._cum = 0  # cumulative delta bytes since the last anchor
+
+    @property
+    def turn(self) -> int:
+        """The number of :meth:`next` calls so far (the initial full is turn 0)."""
+        return self._turn
+
+    def current_full(self) -> str:
+        """Return the full payload for the current base (:func:`encode_generic_full`).
+
+        Send this first to establish the base; it is also a valid manual re-anchor.
+        """
+        return encode_generic_full(self._base, self._tool)
+
+    def _reanchor(self, nxt: GenericSet) -> str:
+        wire = encode_generic_full(nxt, self._tool)
+        self._base = nxt
+        self._cum = 0
+        return wire
+
+    def next(self, nxt: GenericSet) -> tuple[str, bool]:
+        """Advance the session by one turn to ``nxt``.
+
+        Returns ``(wire, is_full)``: the wire to transmit and whether it is a full
+        re-anchor (``True``) or a delta (``False``). A schema change forces a full
+        (Section 10a.7). The held base becomes ``nxt`` either way. The wire is
+        byte-identical to calling ``encode_generic_full`` / ``encode_generic_delta``
+        directly. May raise on duplicate identity / no key (propagated from
+        :func:`diff_generic_sets`).
+        """
+        self._turn += 1
+
+        # Schema change (or a fresh key) cannot be expressed as a delta -> full.
+        if nxt.key != self._base.key or list(self._base.fields) != list(nxt.fields):
+            return self._reanchor(nxt), True
+
+        d = diff_generic_sets(self._base, nxt)
+        delta_wire = encode_generic_delta(d)
+
+        if self._policy.mode == ReanchorMode.SIZE_GUARD:
+            reanchor = self._cum + _byte_len(delta_wire) >= _byte_len(
+                encode_generic_full(nxt, self._tool)
+            )
+        else:  # FIXED_N
+            reanchor = self._turn % self._policy.n == 0
+
+        if reanchor:
+            return self._reanchor(nxt), True
+        self._base = nxt
+        self._cum += _byte_len(delta_wire)
+        return delta_wire, False

gcf/keyed_map.py

@@ -0,0 +1,86 @@
+"""GCF keyed-tabular map encoding (SPEC 7.2a).
+
+A JSON object whose values are all objects forming a losslessly-tabular set is
+encoded as a keyed table `## [N:]{key,...}`: the shared value fields are declared
+once in a header and each member is one positional row prefixed by its key. This
+is the object-valued analogue of Section 7.4 tabular array encoding. It is
+canonical (default-on): eligible maps always encode as keyed tables, with no
+option to disable.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def keyed_map_eligible(m: Any) -> tuple[list[str], list[Any], list[str], str] | None:
+    """Report whether an object is a keyed map of objects that should render as a
+    keyed table `## [N:]{key,...}` (SPEC 7.2a.1). Returns the ordered member keys,
+    the corresponding value objects, the ordered value-field union, and the
+    key-column label, or None when the object is not eligible.
+    """
+    if not isinstance(m, dict):
+        return None
+
+    keys = list(m.keys())
+    values = [m[k] for k in keys]
+
+    # A keyed map requires at least two members: the form factors the shared value
+    # fields into one header, which only pays off across multiple members. A
+    # single-member map yields a one-row table the same size as a section, so keying
+    # it would change canonical output for every nested single-member object (e.g.
+    # `{"data": {...}}` wrappers) with no benefit. Single-member objects use ordinary
+    # encoding; a single-key wrapper of a multi-member map therefore defers, and the
+    # inner map is keyed at its own level (SPEC 7.2a.1).
+    if len(keys) < 2:
+        return None
+
+    # Every value must be an object; build the ordered field union.
+    seen: set[str] = set()
+    value_fields: list[str] = []
+    for v in values:
+        if not isinstance(v, dict):
+            return None  # non-object value
+        for f in v:
+            if f not in seen:
+                seen.add(f)
+                value_fields.append(f)
+    if not value_fields:
+        return None  # all-empty value objects
+
+    # A keyed header needs at least one value field that can be a tabular column.
+    # A field name containing ">" cannot be a column (SPEC 7.4.6.1.4); if every
+    # value field contains ">", the keyed form would have only the key column,
+    # which is invalid. Such a map uses Section 7.2 section encoding instead, the
+    # object analogue of an array falling back to expanded form.
+    if not any(">" not in f for f in value_fields):
+        return None
+
+    # Key-column label: "key", made unique by prepending "_" on collision.
+    key_label = "key"
+    while key_label in seen:
+        key_label = "_" + key_label
+
+    return keys, values, value_fields, key_label
+
+
+def keyed_rows_to_map(rows: list[Any], fields: list[str]) -> dict[str, Any]:
+    """Reconstruct the map from decoded keyed-table rows: the first declared field
+    is the member key; the remaining fields form the value object (SPEC 7.2a.4).
+    """
+    if len(fields) < 2:
+        raise ValueError("keyed_map: header must declare at least two fields")
+    key_label = fields[0]
+    out: dict[str, Any] = {}
+    for r in rows:
+        if not isinstance(r, dict):
+            raise ValueError("keyed_map: row is not an object")
+        if key_label not in r:
+            raise ValueError(f"keyed_map: row missing key column {key_label!r}")
+        kv = r[key_label]
+        ks = kv if isinstance(kv, str) else str(kv)
+        if ks in out:
+            raise ValueError(f"keyed_map: duplicate member key {ks!r}")
+        value = {k: v for k, v in r.items() if k != key_label}
+        out[ks] = value
+    return out

gcf/packroot.py

@@ -0,0 +1,53 @@
+"""GCF graph-profile pack root (gcf-pack-root-v1, SPEC Section 10.2).
+
+Computes the canonical pack root hash for a graph snapshot (symbols + edges).
+Mirrors the gcf-go reference implementation (packroot.go); the shared conformance
+fixtures (graph-pack-root/) hold both to identical bytes and hashes.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+from .constants import KIND_ABBREV
+from .scalar import format_number
+from .types import Edge, Symbol
+
+
+def pack_root(symbols: list[Symbol], edges: list[Edge]) -> str:
+    """Canonical pack root for a graph snapshot (gcf-pack-root-v1, graph profile, 10.2).
+
+    Symbol and edge records are sorted independently by unsigned UTF-8 byte order,
+    then concatenated (all symbols, then all edges) and hashed with SHA-256. Two
+    implementations given the same logical graph MUST produce the same result.
+    """
+    # Build canonical symbol records.
+    sym_records: list[str] = []
+    for s in symbols:
+        kind = KIND_ABBREV.get(s.kind, s.kind)
+        score = format_number(float(s.score))
+        sym_records.append(
+            f"S\t{kind}\t{s.qualified_name}\t{score}\t{s.provenance}\t{s.distance}\n"
+        )
+
+    # Map qualified_name -> kind abbreviation for edge endpoint resolution.
+    sym_kind_map: dict[str, str] = {}
+    for s in symbols:
+        sym_kind_map[s.qualified_name] = KIND_ABBREV.get(s.kind, s.kind)
+
+    # Build canonical edge records.
+    edge_records: list[str] = []
+    for e in edges:
+        src_kind = sym_kind_map.get(e.source, "")
+        tgt_kind = sym_kind_map.get(e.target, "")
+        edge_records.append(
+            f"E\t{src_kind}\t{e.source}\t{tgt_kind}\t{e.target}\t{e.edge_type}\n"
+        )
+
+    # Sort independently by unsigned UTF-8 byte order.
+    sym_records.sort(key=lambda r: r.encode("utf-8"))
+    edge_records.sort(key=lambda r: r.encode("utf-8"))
+
+    canonical = "".join(sym_records) + "".join(edge_records)
+    digest = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+    return "sha256:" + digest

gcf/scalar.py

@@ -6,10 +6,13 @@ import math
 import re
 from typing import Any
 
-_JSON_NUMBER_RE = re.compile(r"^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$")
+# \Z (end of string), not $, so a trailing newline does not count as the end:
+# in Python $ also matches just before a final \n, which would misclassify a
+# string like "5\n" as a number or "W\n" as a bare key and break round-trip.
+_JSON_NUMBER_RE = re.compile(r"^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?\Z")
 _NUMERIC_LIKE_RE = re.compile(r"^[+-]\.?\d|^\.\d|^0\d")
 _INLINE_ARRAY_RE = re.compile(r"\[[^\]]*\]\s*:")
-_BARE_KEY_RE = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+_BARE_KEY_RE = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*\Z")
 
 
 class _Missing:
@@ -29,6 +32,10 @@ def needs_quote(s: str) -> bool:
         return True
     if s in ("-", "~", "^", "true", "false"):
         return True
+    # A value shaped like an inline-schema attachment marker (^{...}) would decode
+    # as an attachment and lose the string, so it must be quoted (SPEC 2.4).
+    if len(s) >= 3 and s[0] == "^" and s[1] == "{" and s[-1] == "}":
+        return True
     if _JSON_NUMBER_RE.match(s):
         return True
     if _NUMERIC_LIKE_RE.match(s):
@@ -99,7 +106,8 @@ def format_number(f: float) -> str:
     if math.isinf(f):
         return "0"
     if f == 0.0:
-        return "-0" if math.copysign(1.0, f) < 0 else "0"
+        # Negative zero canonicalizes to 0 (SPEC 2.3.1): -0.0 equals 0.0 by value.
+        return "0"
     a = abs(f)
     if 1e-6 <= a < 1e21:
         # Use repr for shortest round-trippable form.