Skip to content
This repository was archived by the owner on Aug 12, 2026. It is now read-only.

docs: the twelve questions the specification does not answer, and code does - #24

Merged
sinkog merged 1 commit into
develfrom
docs/pending-decisions
Aug 9, 2026
Merged

docs: the twelve questions the specification does not answer, and code does#24
sinkog merged 1 commit into
develfrom
docs/pending-decisions

Conversation

@sinkog

@sinkog sinkog commented Aug 9, 2026

Copy link
Copy Markdown
Member

Everything closed so far has been a defect — the document says something wrong, or an implementation does not do what it says.

What is left is a different kind, and lumping the two together would hide it:

Places where the specification says nothing, something had to happen, and whatever the first implementation did became the answer. Nobody chose it. It is not written down. It is load-bearing.

In at least three of the twelve, the two implementations answered differently and no vector could see it.

The list, with what was measured

question measured
D-1 does scalar_type constrain or describe? never read during validation, in either implementation
D-2 absent optional position Go removes the node, Rust materializes null
D-3 may an instance author a primitive? one vector replaces the declaration; no rule stated
D-4 origin of an injected default takes the enclosing origin — a value the YAML did not contain is recorded as yaml-authored
D-5 is access a grammar or a shape? operations checked; nothing inside them
D-6 what characters may a name contain? a child named a.b has no address that resolves — INV-040 is false for it
D-7 which YAML dialect? tags and !!binary are whatever each library does
D-8 are stages and codes normative? they exist only in the fixtures; §8 lists none
D-9 INV-032 in a language that cannot express it stated as a type-system property Go cannot satisfy
D-10 what does the mapping gate promise? matches INV-nnn tokens, never reads MUST
D-11 resource budgets none, at any entry point
D-12 does make release implement INV-045? it does not compute or verify the subject

Each entry states the question, what happens today, whether that is a decision or an accident, the options with what each costs, and what it blocks.

None is fixed by writing more code. They are settled by choosing — and then by a vector that holds both implementations to the choice.

Two that belong together

D-5 (access has described value domains and no enforced grammar) is the same shape of question as the first audit's F-08 (contract is required to be enforced and nothing evaluates it).

Deciding them separately will produce two different answers to one question.

Also corrected

README called check_spec_vectors.py "negative-tested". Nothing under tests/ references it. It now says what the tool actually checks.


make ci passes.

…e does

Everything closed so far has been a defect: a place where the document says
something wrong, or where an implementation does not do what it says. What is
left is a different kind, and lumping the two together would hide it.

These are places where the specification says NOTHING, something had to happen,
and whatever the first implementation did became the answer. Nobody chose it. It
is not written down. It is load-bearing. In at least three of the twelve, the
two implementations answered differently and no vector could see it.

The list, with what was measured for each:

  D-1   scalar_type is never read during validation, in either implementation
  D-2   an absent optional position: Go removes it, Rust materializes null
  D-3   an instance-authored primitive replaces the declaration, in one vector,
        with no rule stated
  D-4   an injected `inherit` takes the ENCLOSING origin, so a value the YAML
        did not contain is recorded as yaml-authored
  D-5   `access` operations are checked; nothing inside them is
  D-6   a child named `a.b` has no address that resolves, so INV-040 is false
        for it
  D-7   YAML dialect, tags and !!binary are whatever each library does
  D-8   stage names and error codes exist only in the fixtures; §8 lists none
  D-9   INV-032 is stated as a type-system property Go cannot satisfy
  D-10  the mapping gate matches INV-nnn tokens and never reads MUST, so an
        unnumbered normative clause cannot enter coverage
  D-11  no budget of any kind at any entry point
  D-12  `make release` does not compute or verify the INV-045 subject

Each entry states the question, what happens today, whether that is a decision
or an accident, the options with what each costs, and what it blocks. None is
fixed by writing more code — they are settled by choosing, and then by a vector
that holds both implementations to the choice.

Two of them belong together and the document says so: D-5 (`access` has
described value domains and no enforced grammar) is the same shape of question
as the first audit's F-08 (`contract` is required to be enforced and nothing
evaluates it). Deciding them separately will produce two different answers to
one question.

Also corrected here: README called check_spec_vectors.py "negative-tested".
Nothing under tests/ references it. It now says what the tool checks.

---
[signing-metadata]
key = cic-my-sign-key
signature = vault:v1:MEQCIFFTSjhQDodXUF5N5Fwssk2oJvPTim8QWhZh/MVikZUmAiA9L3shLNiez2rtcEKUp65MO3R0JgjPEOAd3q+JwOpPwg==
hash-algorithm = sha256
digest = HEE1Hq+VkiUU/KPY6u9/j+Mbrv1SR8FnxfN7a5f4C2Y=

[certificate]
-----BEGIN CERTIFICATE-----
MIICBjCCAaygAwIBAgIUSnRMR6RPnEbg296XWPOqq/u5PCwwCgYIKoZIzj0EAwIw
QzELMAkGA1UEBhMCSFUxGTAXBgNVBAoMEENlbnRyYWxJbmZyYUNvcmUxGTAXBgNV
BAMMEENJQyBEZXZlbG9wZXIgQ0EwHhcNMjYwMzIwMTMyMjU5WhcNMjYxMjMxMTMy
MjU5WjBFMQswCQYDVQQGEwJIVTEZMBcGA1UECgwQQ2VudHJhbEluZnJhQ29yZTEb
MBkGA1UEAwwSR2Fib3IgWm9sdGFuIFNpbmtvMFkwEwYHKoZIzj0CAQYIKoZIzj0D
AQcDQgAEIG2CVmTfmLB9pLLclj7YmP2eedAjklpy4LGrU2ijoiy6Xqpuybv7OgJe
i+ez31s65NEV8+X/ByeX1cstR988z6N8MHowCQYDVR0TBAIwADAdBgNVHQ4EFgQU
yZN6AIX/TNnIJ9GwAa/NRN3ujHAwHwYDVR0jBBgwFoAUXn6CHYzPUqU4JVP8g+OS
WeDYjhcwDgYDVR0PAQH/BAQDAgeAMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEF
BQcDBDAKBggqhkjOPQQDAgNIADBFAiEA+bFzXRoJ4PCQbhAAtpkcMjt0vNj5rEW0
lOMBGDNyaWkCIB1vmM7PcZzv/c9bIrxF5kqv6QXomouhByUfeNUTbpKW
-----END CERTIFICATE-----

---
[signing-metadata]
key = cic-my-sign-key
signature = vault:v1:MEYCIQCu9hVs2pzfBy+js6yZCYFxZ1d4LsvXu1cySI1FZ/JT3gIhAP+WuweO+ZUVpfImhS9D3VbBRltT9AzrGEaNHyUioLnc
hash-algorithm = sha256
digest = hgWDRf8INVip96fp/NWhgCw2MNTZB0Ox1WVPor4Suhw=

[certificate]
-----BEGIN CERTIFICATE-----
MIICBjCCAaygAwIBAgIUSnRMR6RPnEbg296XWPOqq/u5PCwwCgYIKoZIzj0EAwIw
QzELMAkGA1UEBhMCSFUxGTAXBgNVBAoMEENlbnRyYWxJbmZyYUNvcmUxGTAXBgNV
BAMMEENJQyBEZXZlbG9wZXIgQ0EwHhcNMjYwMzIwMTMyMjU5WhcNMjYxMjMxMTMy
MjU5WjBFMQswCQYDVQQGEwJIVTEZMBcGA1UECgwQQ2VudHJhbEluZnJhQ29yZTEb
MBkGA1UEAwwSR2Fib3IgWm9sdGFuIFNpbmtvMFkwEwYHKoZIzj0CAQYIKoZIzj0D
AQcDQgAEIG2CVmTfmLB9pLLclj7YmP2eedAjklpy4LGrU2ijoiy6Xqpuybv7OgJe
i+ez31s65NEV8+X/ByeX1cstR988z6N8MHowCQYDVR0TBAIwADAdBgNVHQ4EFgQU
yZN6AIX/TNnIJ9GwAa/NRN3ujHAwHwYDVR0jBBgwFoAUXn6CHYzPUqU4JVP8g+OS
WeDYjhcwDgYDVR0PAQH/BAQDAgeAMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEF
BQcDBDAKBggqhkjOPQQDAgNIADBFAiEA+bFzXRoJ4PCQbhAAtpkcMjt0vNj5rEW0
lOMBGDNyaWkCIB1vmM7PcZzv/c9bIrxF5kqv6QXomouhByUfeNUTbpKW
-----END CERTIFICATE-----
@sinkog
sinkog force-pushed the docs/pending-decisions branch from f5cb072 to 9857b2c Compare August 9, 2026 18:09
@sinkog
sinkog merged commit a6e0c85 into devel Aug 9, 2026
1 check passed
sinkog added a commit that referenced this pull request Aug 10, 2026
docs: the four decisions and the review ledger, which #24 merged without
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant