Skip to content

Overlay JSON numbers: case for and against carrying the fork's numeric fixes later #71

Open

Description

@djbclark

Follow-up to #65. The 2026-11-17 operator ruling (relayed from the PR 65 review) is: keep the documented JSON-number difference in docs/architecture/upstream-overlay.md §7 for now, and open this issue to record the case for and against closing it later with an overlay patch series.

What the gap is

The overlay applies core's CMDB loader but not the fork's numeric handling:

  • libntech json.c at the fork pin cc892efae: JsonPrimitiveToString() returns the number as parsed, and exponent form is classified as a real (registers B-4 and B-10).
  • core rlist.c: RlistAppendContainerPrimitive() does the same.

On upstream plus overlay, a top-level vars/variables scalar or primitive array holding an integer past long, or exponent form without a dot (1e5), reaches StringToLongExitOnError() via JsonPrimitiveGetAsInteger(). cf-agent exits in the install step after validation passed: no partial install (nothing is evaluated), but the policy cannot refuse or report it.

Reals also differ in formatting: upstream installs 0.00049 as 0.00 (StringFromDouble()), the fork installs 0.00049.

Reach today is narrow: the projector refuses floats (bin/projector.py:523) and writes no exponents, tendcf variables are containers, and no test holds a bare number, so CI does not cover it. A hand-edited file is the real exposure.

Pros of opening the later PR (carry the patches)

  1. One behaviour, one story. "Upstream plus overlay matches the pinned fork" becomes true for numbers too, and the §7 caveat can be deleted rather than maintained.
  2. Fails closed instead of exiting. A hand-edited or third-party JSON file cannot kill cf-agent mid-install with no policy-level explanation.
  3. Cheap while the patch series is small. The overlay already carries a libntech strict-parse series; adding two hunks plus one core hunk and a numeric fixture follows the existing mechanism (bin/overlay.py, overlay.json).
  4. Removes a review liability. Cross-vendor reviewers found this independently twice (Overlay: replace B-5b with the all-or-nothing CMDB loader; libntech strict parse; overlay-build CI #65 MED1 and Fable A1); carrying it stops the same finding resurfacing on every overlay review.

Cons of opening the later PR

  1. It touches the trust-boundary build for no user-visible bug. The §2 rule exists so the overlay stays a narrow, auditable patch set; each additional patch is more surface on the enforcing path.
  2. Upstream would decline it anyway. Upstream is only later offered the core all-or-nothing series; the numeric behaviour is a fork-only difference, so the patches would live in the overlay permanently with no path to upstream.
  3. Cost lands on a slice that has nothing to do with state 1. The overlay's job is to reproduce the loader; number classification is orthogonal to launching the VM and the root launchd render path (State 1 macOS VM: minimal tart image and root launchd render path check (B6) #70).
  4. The fixture is the hard part. Proving parity needs a numeric fixture that pins both the refusal/exit behaviour and the real-formatting behaviour across both builds, plus a way to assert it in CI without a macOS leg.

Suggested trigger for revisiting

Open the PR if any of these becomes true: the projector starts emitting numbers, a policy or site file gains a numeric vars value, a user reports a cf-agent exit on a hand-edited file, or the overlay's patch set is next touched for another reason (then bundle it).

Links: #65 (the merged overlay work), upstream-overlay.md §7.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions