Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions MANIFEST.sha256
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
1126b99a345f693bd4c98eedaa86397ad4251f34f89dc48079f33764af0804d8 docs/hu/makefile-cheatsheet.md
113f83b3ca0443799224e8f29396b90777539217771ecb6f1c932df1b5168389 LICENSE.meta.yaml
11a0fb2cf1ce82ed7df0fe05a6fceb8e20051c48c4e9c80925f34d68dace503d tools/schemalib/validator.py
1264e708b92df67154f5f50bf52d9e7c5b3edb586db583dc47fc10b59bc060ab module/canonical_json.go
134ea29c14da90cff091cb9bd5406522e182a07a86c6c4203e1436df8c26c4bc docs/en/concept/declarative_ecosystem_integration.meta.yaml
13b0b2a232d66df4fe26ec751b49b600fc63dbcde26b2bf17c675bfed78d30f8 module/testdata/vcn-v1/cases/partial-read/expected/observed.registry.json
15551f514d13c6d42283a2cf09355f900f862624a51f3e32b6675ef3a24fce4a tools/oci-extract/go.mod
Expand Down Expand Up @@ -61,16 +62,16 @@
41ab08a0eb4f0739f352e60b35512c5402644f16fc349552cd185c490cb4d5a3 module/contracts_test.go
439445a5ad606bc5cd95a94cb4fba54f3f4dca17ed402d28c45c355cb235f301 module/module_loadtest_test.go
441f681287c170544f90844b29e4a103f89e91ac23a6cc8e974635d8bcde5a2b docs/en/architecture.md
456ea91a25295d5fd5c05b614e467e571f7611760ce1e4ff1222a1b5c00af583 module/provider.go
46120946bf939cfeae2c4806a39aef398f904f89b61c670ee5dd0d3c769138c2 tools/oci-extract/resolve_test.go
49ea29dcc165db8a6b406e82492500fd4761a7121c2420116e31f8e58f865dec tools/oci-extract/resolve.go
4ac6d59c5e3cd88c9dde821511c970827ae56e40a89a308a210cd985ecfdc41e CLAUDE.md
4d7369474566105752ec28aefab51de748b237342c71d05b3189fa8c2ae1fdef Makefile
4fffcdac095c0623fefb8515ab80b3e9629c0febc454456cd08b3cdf3c941720 LICENSE.md
511b61d9cf52d8f761a5dc2991ec25ed973632bc0d1f1a0607166e68e3d84552 docs/design/specs/provider-abi.md
526ab17415fc9a42967d35159db9438c3e696bf5a246e57a9f68c2dd0e596837 module/testdata/vcn-v1/cases/drift/expected/observed.oci.json
53bc2df597bc242dd2f8d2176b3a68e3d0681079132431c8e9900e14d34314c7 module/provider_test.go
5432506f15d65fa59572362a70db4bc403c13b163ec961ecb2951d7f98d093d0 module/go.mod
546e7c533da4b86b8817ee426865df0d11e24d2aa1580647634345f452a5017e module/canonical_json_test.go
56934c1ce7b4de656087d0b2ddb9e9dcbf56dd0c541d9e279c19c7535e84445a module/provider.go
57980b8a84a13ffad62b7295e3095bd635f8894716665d0654dfb54eebbf10e5 docs/contracts/en/host-expectations.md
5c650f84f688d4d965721df74779228bb6fdfa47d5c08c46e8274e6d97b212c8 module/testdata/vcn-v1/lifecycle-map.json
5ca6da66b9de8a04ca71f1c18ba2026ad02b8c1c70c700a432058da267e6b27d module/correspondence/vcn.json
Expand All @@ -89,6 +90,7 @@
6f3655bf787efee284225bcb6096913d0ec556771dddb42845311e649c21e7ad docs/hu/concept/declarative_ecosystem_integration.md
7068014ecee4111cb4456d3d3328c33b53a79c7803d68f040036f34449423f65 tools/oci-extract/testdata/instance.go
7080b3423beded8b64891afdcf2e6f6d8bec6ebeaa88aecbb1b06e149b54ef86 module/module.wasm
70d185e08cc84d9c493f925bd3e4153c6a69078b7a1b560d290031e4ad602933 module/plan_noop_exactness_test.go
7136d8366bbd7c5ccc19a3d810a7f55c31541acec9b0f05bd84e45a39107ded7 tests/test_capability_manifest.py
7426752feb1140b2023192728df35248e4f802617c150bb0523ab97dc1638c0b tools/init-hooks.sh
74d93981f1935d21001ed0475ebb84132ab67c71840ca82ca0cbfac5aca29ea2 docs/contracts/en/wasm-abi.md
Expand All @@ -104,6 +106,7 @@
7efd45c44d808639d5fe607cf4182e930be6b8d82709e716114e63512f69b55f module/testdata/vcn-v1/cases/conformant/expected/verdict.fields.json
805c05942247d6327f0f006a8799119ace530c4ae288ad637d0f8faddca21d86 docs/hu/architecture.md
806851c10862d6900eb858a229e3ba7138943abe3fd75e5b1e8f8ca4b57d1d6f mk/golang.mk
81eab1d1dbbeffa23d53c33e39f0bf6977348178640c1032827651d27180ffa9 docs/design/specs/canonical-json.md
836f908676723485f9648e69e184c49e51304febd4bcdc500c54038522a6092d module/observe_derivation_test.go
8400c953622cd5ba5414898bbc85e51494eaa3dae6ac9051ab4ac67c4a6e3384 module/testdata/vcn-v1/cases/conformant/expected/evidence.claims.json
8400c953622cd5ba5414898bbc85e51494eaa3dae6ac9051ab4ac67c4a6e3384 module/testdata/vcn-v1/cases/desired-absent/expected/evidence.claims.json
Expand All @@ -129,9 +132,9 @@
976bee7ffb9a4a599d5aee841d941ea7d12fecb6fdbb05d44238754b67148cb1 module/envelope_test.go
97f3f81e90d839c74efbe7ad2e1732b08ac0612a38499d6ef5dedcc637c64eb6 module/testdata/vcn-v1/cases/malformed-cidr/oci/response.json
9b18a2109d250d26d57d3cec5ed9c67bd803d34e9592ab98fb1826a5dc457a8f module/cicflow_mock_test.go
9b6f006a0e21f7baaad8509b3323e4c7e5bc4d16ab8cc165a70af855f78da460 module/testdata/canonical_json_vectors.json
9ba2ca374fd1900e82a2b6a9c27233e1603dce89b1908592b2a6cc93313be84c docs/hu/wasm-module-authoring.md
9c11fd643268e578437b015dc5a4ea6e5a3f290f0303ac04ea4d429768208617 tools/schemalib/__init__.py
9d31cb8835fcbd2d1d68aaa21609ebf1668bb5182d78aa8087e86b8f3bee65a4 docs/design/README.md
9de6268f09ede92c5adcb82ceec4ecd66761ade6e6aa79131cfeb8cc9814f44d tools/wasm_assert_tests_passed.sh
a03b3fccfc1f8eb7f76833fdff8a50ea84c80c039db87bc0e41109e96f64420b docs/en/concept/declarative_ecosystem_integration.md
a1cba33d61cd932030481da78da553eb0f31b536a7c3879d5bdd9992c69d189a module/testdata/vcn-v1/cases/not-found/expected/observed.oci.json
Expand All @@ -157,6 +160,7 @@ b8e7c23cfe46a0daf7d3441b15657e9d4b35c4bf50f9421c2841dfbf19cacc82 docs/en/archit
b9325f58a95216b240f3715a773e34fe8cdfa4d5fe48a5e7b32002a40be5cc2e tests/test_tools/test_finalize_release.py
bb8a1743ab9f77a309bd851b4a1660f6f2420900455a5a0dfb83f4e6905968ff module/abi_manifest_test.go
bbe93c718d90a03de5aab2999031c7097bd63a8e40ec14589c8dbe4364a4ec52 renovate.json
bcb406d5d10094dafb465d317935b4b8656e895a3331278765065669c8681fcf docs/design/specs/provider-abi.md
bef22a55d1559676a57b4a05b48efc7cd226d3d733a1c932e183666679046b53 module/testdata/vcn-v1/cases/drift/expected/evidence.claims.json
bfccbd3cd778ac6f0458b7d45d7b25e2cbdc0a789f40e81c1de476f8aab44363 tools/schemalib/loader.py
c31a1313ace9ae3da9483d7ac7bbc0938d5e2f6c7c0460d785d94db5bb931e85 docs/contracts/en/release-artifact.md
Expand Down Expand Up @@ -187,6 +191,7 @@ d5daed86d55d8b22d307e8b4df9ab5af7cfa9c2647750d28c5344daeb40f92f8 module/testdat
d73ece9aa8ca3e7e76655705dd0c074869a83fe66a8745212f95a6a4db8916cf tests/test_oci_sdk_lock.py
d75063538a29c37caad5e4f1ba680c81bc4827ee935e78281ab168b72d5e53a2 tools/check_doc_links.py
d8e2e8a0c3377de19d2e1f04a7bf7f4dacce1a3bcc25ac67884ac2dab4be1bdc docker-compose.yml
da89091049f1e5ad288de12df086c679803c8e56a86bf42f569256437e672571 docs/design/README.md
dbe54644234ddff2e00a48a38e44b2b21fa4eeb3142f17872614ea656deb5836 tools/oci-extract/testdata/vcn_client.go
dbfb640d40533eeb73ececd170189f951f16ad07c549a8321dbb12251e78d067 features/feature-001/spec.md
dc0c98d1e3ca6fac0ef40227c6f8c026397180059c95188d9adb4567cef2e11d tests/test_tools/test_infra.py
Expand Down
3 changes: 3 additions & 0 deletions docs/design/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,9 @@ namespace it opens. Written 2026-07-18 from the design session recorded in
extraction.
- [specs/state-model.md](specs/state-model.md) — intent/state object-level
correspondence and the `effective_config` projection.
- [specs/canonical-json.md](specs/canonical-json.md) — `cic-canonical-json/1`: the exact JSON
value-equality and canonical form `plan` decides on (and a later plan digest will be
computed over).

## Direction

Expand Down
76 changes: 76 additions & 0 deletions docs/design/specs/canonical-json.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# cic-canonical-json/1

The one definition this module uses for "these two JSON texts are the same value".
It decides whether a plan has any work to do (`plan`), and is the form a later digest
of a plan will be computed over. Go implements it (`module/canonical_json.go`); the
**normative expectations are the language-neutral vectors** in
`module/testdata/canonical_json_vectors.json`, so another implementation can be
checked against the same file.

Status: `plan` uses it today (**implemented**). Digests over it (`plan_digest`,
`target_digest`, `execution_digest`) are **concept** (not yet built).

## Why not the standard library

`encoding/json` reads every number as a `float64`, so two different integers above
2^53 compare equal (and `0.1` equals `0.10000000000000001`); it keeps only the last of
a repeated object key; and it turns an invalid UTF-8 byte or a lone surrogate escape
into U+FFFD, so distinct texts can collapse into one. `plan` used that comparison to
call two different values a `noop`.

## The form

The input is one strict JSON text (RFC 8259). The output is deterministic:

- **Whitespace** is dropped (only space, tab, CR and LF are whitespace on input).
- **Objects**: members sorted by the **decoded key's UTF-8 bytes**; the keys are
compared after escapes are decoded (`"a"` is `"a"`). A **repeated key is an
error**, never merged.
- **Arrays** keep their order.
- **Numbers** are exact, with no floating point: the value is written as
`<digits>e<exponent>`, where `<digits>` are the significant digits (no leading and
no trailing zeros) and the exponent is the power of ten that scales them, with a
`-` in front for a negative value. `1`, `1.0`, `1e0` and `10e-1` are all `1e0`;
`100` and `1e2` are `1e2`; `0.5` is `5e-1`; zero in any spelling (`-0`, `0.0`,
`0e5`) is `0`. `9007199254740993` stays `9007199254740993e0` and differs from
`9007199254740992e0`.
- **Strings** are decoded (all escapes, surrogate pairs combined) and written with
only the quote, the backslash and the characters below U+0020 escaped, the latter
as `\u00xx` in lower case. Every other character is written as it is, with no HTML
escaping. A lone surrogate escape is an error.
- Literals `true`, `false`, `null` as written.

## What is refused (an error, never a repair)

Not valid UTF-8 (a byte order mark included); a value followed by anything but
whitespace; a leading zero, a `+`, a bare `.5` or `1.`, `NaN` or `Infinity`; trailing
commas, comments, single quotes, unquoted keys; a raw control character in a string;
a bad or short escape; a lone or mismatched surrogate escape; a repeated object key;
empty or whitespace-only input.

## Bounds

An input beyond a bound is refused, not truncated:

| Bound | Limit |
|---|---|
| input text | 1 MiB (2^20 bytes) |
| nesting of arrays and objects | 64 |
| digits in a number's integer and fraction parts | 1000 |
| digits in a number's written exponent | 6 |
| exponent after normalization | -10000 to 10000 |

An error names the byte offset and the reason, never the offending text.

## Where it applies today

`plan` refuses `desired.data` and `observed.data` that are not canonicalizable
(`validation`, `field_path: desired.data` / `observed.data`), and compares values
(whole payloads and field by field) by their canonical form. `validate` and the other
operations are unchanged.

## What this is not

Not JCS (RFC 8785): that requires ES6 floating-point number formatting, which is
exactly the loss this form exists to avoid. Not a signature or an approval: two texts
with the same canonical form are the same JSON value, and nothing more.
9 changes: 9 additions & 0 deletions docs/design/specs/provider-abi.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,15 @@ execution-result: # as implemented
no id should end as `accepted` with the id still pending, and what `poll` would
have to return to deliver the created resource's identifier.

### What `plan` requires of its inputs

`desired.data` and `observed.data` must be strict, bounded JSON with exact numbers and
no repeated object key, as defined in `canonical-json.md` (cic-canonical-json/1);
otherwise `plan` answers `validation` with `field_path: desired.data` or
`observed.data`. Values are compared by their canonical form, so key order, whitespace,
escape spelling and number spelling (`1`, `1.0`, `1e0`) do not make a difference, while
different values always do (two integers above 2^53 are never equal).

### What `execute` accepts before it sends anything

Two independent checks run over the **whole** plan before the first step is signed
Expand Down
Loading
Loading