From bc268f92acf5f44018f5a11a8d2e165fa20168ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A1bor=20Z=20Sink=C3=B3?= Date: Sun, 8 Nov 2026 15:52:42 +0100 Subject: [PATCH 1/2] docs: D5-2, the Forms side of the realization context (question 7), second reading pass Reads the Forms library and the engine's documents for where a context-derived value could enter, and records what they say. Forms is a pure library with schema-declared defaults (origin authored or default) and no execution context; the engine states that Parse, Normalize, Resolve and Validate are the environment's job and that facts like reference resolution are written onto the object before it arrives; P5 (Resolve from a supplied snapshot, materialize, receipt) is design with no code and no receipt producer exists; the closed receipt contract's derived_values name their inputs as paths of the object. A text search finds no realization, deployment, tenancy, base_path, key_id or provider_id data in the Forms repository, and provider_id only as a state-only field in the engine's OCI fixtures. Concludes that a schema default cannot carry a realization value, that the library cannot derive it, that the named seam is Resolve from a supplied snapshot (not in code), and that the receipt cannot name an input outside the object today. Records two ways to close that (the context inside the object, with an engine contract change, or outside it, bound at the execution layer) as decisions D5-6 and D5-7, and a naming collision between the engine's environment and the realization environment. Documentation only; nothing is implemented and the source of the repositories read was not read, only their documents and a text search. --- [signing-metadata] key = cic-my-sign-key signature = vault:v1:MEQCIBMBcThmXaWazE/BKhho2cGufzorelu3YVxrIC9wMC5KAiBHLbT0otLH+w/oGMgMmFwApAcZDbXXOJFQzo1Kx1Vkeg== hash-algorithm = sha256 digest = 7dVcKaS4QBrfAP/GIsE5xHBTnjSLsdIYI51p3Rl8fKY= [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----- --- MANIFEST.sha256 | 2 +- docs/design/specs/realization-context.md | 81 ++++++++++++++++++++++-- 2 files changed, 77 insertions(+), 6 deletions(-) diff --git a/MANIFEST.sha256 b/MANIFEST.sha256 index 319bcb6..0002bfd 100644 --- a/MANIFEST.sha256 +++ b/MANIFEST.sha256 @@ -174,7 +174,6 @@ b8e7c23cfe46a0daf7d3441b15657e9d4b35c4bf50f9421c2841dfbf19cacc82 docs/en/archit b9325f58a95216b240f3715a773e34fe8cdfa4d5fe48a5e7b32002a40be5cc2e tests/test_tools/test_finalize_release.py bb8a1743ab9f77a309bd851b4a1660f6f2420900455a5a0dfb83f4e6905968ff module/abi_manifest_test.go bbe93c718d90a03de5aab2999031c7097bd63a8e40ec14589c8dbe4364a4ec52 renovate.json -bdcc6a3130f3522ce94c9c200247fd6925a47f22cab85eb0a799d17b83c203ed docs/design/specs/realization-context.md bdea227cb29b579b2daaa7fa398102adc096ff9073c78bd9ec1f0dde44b89824 docs/design/relay-requirements.md bef22a55d1559676a57b4a05b48efc7cd226d3d733a1c932e183666679046b53 module/testdata/vcn-v1/cases/drift/expected/evidence.claims.json bfccbd3cd778ac6f0458b7d45d7b25e2cbdc0a789f40e81c1de476f8aab44363 tools/schemalib/loader.py @@ -210,6 +209,7 @@ dbe54644234ddff2e00a48a38e44b2b21fa4eeb3142f17872614ea656deb5836 tools/oci-extr dbfb640d40533eeb73ececd170189f951f16ad07c549a8321dbb12251e78d067 features/feature-001/spec.md dc0c98d1e3ca6fac0ef40227c6f8c026397180059c95188d9adb4567cef2e11d tests/test_tools/test_infra.py dcd74edeae0b4e8ffc610d2dfc01c302221eda1b1aac6df12f8334b2c96fbf20 module/testdata/vcn-v1/cases/malformed-cidr/expected/verdict.fields.json +de600b7cd904a5e6ed1973f76d25e81433debb035bd8b46a2a545e323e49a92c docs/design/specs/realization-context.md de838914aa32b597e9575a29096df381802c369f867f2655e7ca114106ddab92 module/testdata/vcn-v1/cases/not-found/oci/error.json df1a1d134a0917f492882af78775b072430c47dd43008625140ad35e206457e9 tests/test_tools/test_releaselib/test_vault_service.py df4af3ee8dfbb9616d0409f9975d7caf232a84517813debddce5a1aa06920f69 oci-sdk.lock.yaml diff --git a/docs/design/specs/realization-context.md b/docs/design/specs/realization-context.md index 8885d25..765a385 100644 --- a/docs/design/specs/realization-context.md +++ b/docs/design/specs/realization-context.md @@ -23,9 +23,15 @@ is written down and what is in the code; where the sources are silent it says so `architecture.md`, `relay-requirements.md`, the D5 and M4 documents); CIC-Relay at `55a899f` (`features/feature-011-oci-provider/design.md`, `core/nexus/iac`, `core/nexus/drift`, `core/nexus/ois`, `core/cabinet`, `cmd/relay/cic_flow_*`). -- **Not read in this pass:** the Forms engine and its docs (`cic-primitive-forms`, +- **Not read in the first pass:** the Forms engine and its docs (`cic-primitive-forms`, `cic-primitive-engine`), the schema registry (`cic-schema-registry`), `primitives`, `CIC-basic-knowledge`, and the OIS repository. Statements about them are second-hand and marked. +- **Second pass (section 6):** the Forms library's README, `docs/P1-SUPPORTED-SUBSET.md`, + `docs/P5-RESOLVE-MATERIALIZE-RECEIPT.md` and the ADR list (`cic-primitive-forms` at `5531111`), + the engine's `docs/MATERIALIZATION-SPEC.md` scope note and `docs/RECEIPT-SCHEMA.md` + (`cic-primitive-engine` at `93c793a`), a text search of both repositories, and the top level + of the schema registry. **Still not read:** the ADR bodies, the engine and library source beyond + the text search, the schemas in the registry, `primitives`, `CIC-basic-knowledge`, OIS. ## 2. What exists @@ -48,7 +54,7 @@ concept -> code -> runtime -> audit | Link | State | Evidence | |---|---|---| -| intent to the expanded object (Forms) | code exists elsewhere, **not read** here | `forms-integration-direction.md` section 3 | +| intent to the expanded object (Forms) | code exists elsewhere (pure library, `implemented` per its README); read at document level in section 6, not at source level | `forms-integration-direction.md` section 3 | | **realization context: which provider account, environment, contract version and execution identity this object is realized in** | **does not exist** | no document in this repository defines it; no Go type for a realization, deployment context, environment or binding in the Relay's `cmd`, `core`, `pkg` at `55a899f` (searched by type name); in the spec's example the state object's `binding` has only `provider` and `provider_id` | | derivation of `host`, `base_path`, `key_id` from it | does not exist | measured: all five target values are caller-supplied to every entry point (`destroy-invoke-binding.md`, `target-origin-and-path-safety.md`); the registry records no API version, base path or host | | routing an object to a module and an environment | `concept` | `forms-integration-direction.md` section 3 ("module routing") | @@ -147,12 +153,77 @@ target is not an approval. 6. **Lifecycle**: rotation and revocation of the execution identity binding; what happens to an approved but unexecuted plan when its context changes. 7. **The Forms side**: where in "defaults with origin" and "policy resolution" a context-derived value - would enter; this needs the Forms engine and its documents read, which this pass did not do. + would enter. Answered in part by the second pass (section 6): it does not enter there; the open + points are D5-6 and D5-7. + +## 6. The Forms side (question 7), second pass + +Read: the Forms library `README.md`, `docs/P1-SUPPORTED-SUBSET.md`, `docs/P5-RESOLVE-MATERIALIZE-RECEIPT.md` +and the ADR list (`cic-primitive-forms` at `5531111`); the engine's `docs/MATERIALIZATION-SPEC.md` (the +scope note at its top) and `docs/RECEIPT-SCHEMA.md` (`cic-primitive-engine` at `93c793a`). + +### 6.1 What they say + +- **The Forms library is a pure library**: no Git, no network, no filesystem policy, no execution + context (README). Its defaults are **schema-declared**: `normalize` keeps `value_origins` + (`authored` or `default`, per position); `expand` keeps an origin (`authored` or `materialized`) + and an attestation (ADR 0010). `PolicyResolution` gives the effective access and modify rule per + position; its `unknown` is "a caller input, a P5 snapshot-reference not resolved". +- **P5 is design, no code**: "Resolve (from supplied snapshot), materialize, receipt". Resolve is kept + out of the first units. No receipt producer exists "anywhere in the CIC ecosystem" as far as the + engine's own documents can show. +- **The engine's scope correction**: `Parse`, `Normalize`, `Resolve` and `Validate` are "permanently the + environment's job". The engine receives a candidate **materialized object**, checks its Complete + property, canonicalizes it and digests it. Reference resolution and default or derivation decisions + "are facts the object's environment establishes and writes onto it". +- **The receipt contract is closed** (15 required fields): `applied_defaults[]` (the rule is the literal + `schema-default`) and `derived_values[]` (`path`, `rule` = `name-vN`, `inputs`, `value_digest`). + `inputs` is a deduplicated, sorted **set of paths the derivation read**; `input_digest` is the + digest of the canonical authored input; "`rule` and `inputs` are the producer's statements"; there + is no signature field. +- **Nothing in either repository carries target or realization data**: a text search of + `cic-primitive-forms` finds no occurrence of `realization`, `deployment context`, `tenancy`, + `oraclecloud`, `base_path`, `key_id` or `provider_id`; in `cic-primitive-engine` the only hits are + `provider_id` in the OCI conformance fixtures and `plan.rs` tests, as a state-only field. The schema + registry's `docs/en/architecture.md` uses "environment" for the execution environment of its + compiler, which is unrelated. + +### 6.2 What follows for the realization context + +- **A schema default cannot carry it.** Defaults are the schema's and the rule is `schema-default`; a + host or a region in a default would make the schema environment-specific, and the object it + describes is meant to be provider-independent. +- **The library cannot derive it**, by construction (no execution context). +- **The named seam for facts from outside is `Resolve` from a supplied snapshot (P5, design only).** + A realization context would be such a snapshot, supplied by the layer that realizes the object. + That seam does not exist in code. +- **The audit form has a gap.** A `derived_values` entry names its `inputs` as paths of the object. A + value derived from a context that is not part of the object has no such path, and the receipt + contract is closed, so it cannot name that input today. +- **Two ways to close it** (the owner's choice; neither is implemented): (i) the context is + materialized **into** the object, so `derived_values` can name it as paths, which makes the + object environment-specific and changes the closed receipt contract in the engine repository; + (ii) the context stays **outside** the object and is bound at the execution layer by the realization + digest of section 4, with the receipt unchanged and the object provider-independent. Section 4 + was written for (ii). +- **A word that means two things.** The engine's "environment" is the processing layer that prepares + the object (Parse, Normalize, Resolve, Validate). The realization "environment" of section 4 is a + provider account, region and realm. They are different things; a document that says "the + environment writes the host onto the object" would be reading the engine's word with the CIC + model's meaning. + +### 6.3 Decisions this adds + +- **D5-6.** The realization context inside the object (i) or outside it, bound at the execution layer + (ii). Section 4 assumes (ii); (i) needs an engine contract change. +- **D5-7.** Names: a distinct word for the realization environment, so it is not confused with the + engine's "environment". ## What this does not claim The realization context is not implemented anywhere and no document in this repository defined it -before this one. Nothing here is verified against the Forms engine, the schema registry or the OIS -repository, which were not read in this pass. The Relay facts are from `55a899f`, read, not run. +before this one. Section 6 rests on documents and a text search of the Forms and engine repositories, not on their +source or their ADR bodies; nothing here is verified against the schemas of the schema registry or +the OIS repository, which were not read. The Relay facts are from `55a899f`, read, not run. Section 4 is a proposal: the premise it rests on is the owner's statement of the model, and the open questions above are the points where that statement has to be completed before anything is built. From f2c9c39fb89b556e438e0c1b45eae2404edda35d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A1bor=20Z=20Sink=C3=B3?= Date: Sun, 8 Nov 2026 19:11:02 +0100 Subject: [PATCH 2/2] docs: D5-6, do not claim a receipt change that the sources do not show (review F1) The text said that putting the realization context into the materialized object changes the engine's closed receipt contract. The documents read do not show that: if the context is part of the object's schema, a derived_values input could in principle name its paths, so what is needed is a reconsideration of the schema and the object boundary, and whether the existing receipt can represent the derivation without an extension is not verified. The text now says that. It also keeps the P5 snapshot idea as a proposal (nothing says a realization context is an accepted snapshot kind), and records that D5-6 is not a choice for this repository alone: it touches the object boundary and is to be decided with the Forms, engine and Relay contracts. Documentation only. --- [signing-metadata] key = cic-my-sign-key signature = vault:v1:MEQCIBiEDAN5EpZWeS9LQgowSgXf9PNWV2lJ5fdQl+KavN/DAiAXEzgN7Z1+JBDeKpESwbIUklTiUfkXCaR6+mI47tW8/A== hash-algorithm = sha256 digest = QoX3QJavo2LBBG4ZvWe5Cy/z+XQ5CxM7H1JUY4LgMf8= [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----- --- MANIFEST.sha256 | 2 +- docs/design/specs/realization-context.md | 22 ++++++++++++++-------- 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/MANIFEST.sha256 b/MANIFEST.sha256 index 0002bfd..6cea221 100644 --- a/MANIFEST.sha256 +++ b/MANIFEST.sha256 @@ -84,6 +84,7 @@ 5d8afd2b9d29065c768de8a21562049904b7c4ad3449448c3159af34e3a0b9df docs/en/concept/git-management.meta.yaml 5daa3bf50db9db492aac5721bddc0837a6a30dec9558d886abf45ad89632f68e module/manual_real_oci_test.go 60f8027dfd091bdaddd7537c65780676cabd460e85b6c7657e8eed294c8b1de7 docs/design/measurements/destroy-invoke/output.txt +61cb7c8973e265f1b773afe40f0cd252bae1802fb2d17fd148ceb6ac1c20d786 docs/design/specs/realization-context.md 635384b1db18a7654d1e30b660ba825645d88a89e7bc0e808500a213b584f278 module/testdata/vcn-v1/cases/malformed-cidr/expected/observed.registry.json 66181e4c6a0b2735b5a8b3088b37e6a844e2c692399a5b72b036059da0188e0a tools/releaselib/__init__.py 688dffd2264877f3a64fca1d3526c57bb34cb1c18f5a01aa906667311831a052 docs/en/workflow.md @@ -209,7 +210,6 @@ dbe54644234ddff2e00a48a38e44b2b21fa4eeb3142f17872614ea656deb5836 tools/oci-extr dbfb640d40533eeb73ececd170189f951f16ad07c549a8321dbb12251e78d067 features/feature-001/spec.md dc0c98d1e3ca6fac0ef40227c6f8c026397180059c95188d9adb4567cef2e11d tests/test_tools/test_infra.py dcd74edeae0b4e8ffc610d2dfc01c302221eda1b1aac6df12f8334b2c96fbf20 module/testdata/vcn-v1/cases/malformed-cidr/expected/verdict.fields.json -de600b7cd904a5e6ed1973f76d25e81433debb035bd8b46a2a545e323e49a92c docs/design/specs/realization-context.md de838914aa32b597e9575a29096df381802c369f867f2655e7ca114106ddab92 module/testdata/vcn-v1/cases/not-found/oci/error.json df1a1d134a0917f492882af78775b072430c47dd43008625140ad35e206457e9 tests/test_tools/test_releaselib/test_vault_service.py df4af3ee8dfbb9616d0409f9975d7caf232a84517813debddce5a1aa06920f69 oci-sdk.lock.yaml diff --git a/docs/design/specs/realization-context.md b/docs/design/specs/realization-context.md index 765a385..82053d6 100644 --- a/docs/design/specs/realization-context.md +++ b/docs/design/specs/realization-context.md @@ -195,17 +195,20 @@ scope note at its top) and `docs/RECEIPT-SCHEMA.md` (`cic-primitive-engine` at ` describes is meant to be provider-independent. - **The library cannot derive it**, by construction (no execution context). - **The named seam for facts from outside is `Resolve` from a supplied snapshot (P5, design only).** - A realization context would be such a snapshot, supplied by the layer that realizes the object. - That seam does not exist in code. + A realization context could be proposed as such a snapshot, supplied by the layer that realizes the + object. That is a proposal: nothing in the P5 document says that a realization context is an + accepted kind of snapshot, and the seam does not exist in code. - **The audit form has a gap.** A `derived_values` entry names its `inputs` as paths of the object. A value derived from a context that is not part of the object has no such path, and the receipt contract is closed, so it cannot name that input today. - **Two ways to close it** (the owner's choice; neither is implemented): (i) the context is - materialized **into** the object, so `derived_values` can name it as paths, which makes the - object environment-specific and changes the closed receipt contract in the engine repository; - (ii) the context stays **outside** the object and is bound at the execution layer by the realization - digest of section 4, with the receipt unchanged and the object provider-independent. Section 4 - was written for (ii). + materialized **into** the object. That requires reconsidering the object's schema and the object + boundary (the object would become environment-specific). Whether the existing receipt contract can + represent the derivation of such values without an extension is **not yet verified**: if the context + is part of the object's schema, a `derived_values[].inputs` entry could in principle name its + paths, so a new receipt field is not shown to be necessary. (ii) the context stays **outside** the + object and is bound at the execution layer by the realization digest of section 4, with the receipt + contract not involved and the object provider-independent. Section 4 was written for (ii). - **A word that means two things.** The engine's "environment" is the processing layer that prepares the object (Parse, Normalize, Resolve, Validate). The realization "environment" of section 4 is a provider account, region and realm. They are different things; a document that says "the @@ -215,7 +218,10 @@ scope note at its top) and `docs/RECEIPT-SCHEMA.md` (`cic-primitive-engine` at ` ### 6.3 Decisions this adds - **D5-6.** The realization context inside the object (i) or outside it, bound at the execution layer - (ii). Section 4 assumes (ii); (i) needs an engine contract change. + (ii). Section 4 assumes (ii). (i) means reconsidering the schema and the object boundary; whether it + also needs a receipt extension is not verified. This is not a choice for this repository alone: it + touches the object boundary and has to be decided together with the contracts of the Forms library + and the engine (and the Relay's). - **D5-7.** Names: a distinct word for the realization environment, so it is not confused with the engine's "environment".