diff --git a/MANIFEST.sha256 b/MANIFEST.sha256 index 6cea221..03de3f1 100644 --- a/MANIFEST.sha256 +++ b/MANIFEST.sha256 @@ -1,6 +1,7 @@ 00a82847650d5800e5b0ed58d5e08abc9d68846008c743d26c2c6837d1884cdf docs/en/concept/git-management.md 01956821ece300a66ff61849618cb03b0b3fd5aefce4dfd9bff7a4a33c867e1e docs/design/specs/capability-manifest.md 052458dca6bed674aec47f25561534ce72cda99a62faf33e2e947474400c7374 tools/vault-rootCA-sign-agent.sh +b77d7b10fc71d2e285ebd2b8887d7e5029581604aef6938048e3ba56fdb301cc docs/design/decision-brief-target-and-binding.md 05fca2112ed6319a91d0f373f9dcab23df35687daea510498110e9f1ce80e498 module/testdata/vcn-v1/cases/field-absent/expected/verdict.fields.json 0991a93d56b1e24dc9285369a6f636b50fcc5fa6dec48305f76647828c6fbd19 mk/wasm.mk 0d08c6a7982760ef2c1bac82bf587e8d2c0e30fadc6638056e63aaa5e259a1cd tools/finalize_release.py @@ -157,7 +158,6 @@ a4c522ffc80fc87ff4244ba3da8f19591d8206ed9acb4d1d7896ced9f75714a3 docs/design/sp a6728222647cd2d265b28a522ecd3f8d779e01bb8bea5367912f4cd7fb8c72d2 module/execute_create_id_test.go a6c2baaaf307c0718ecaa43f654742269c3830fd9ff899a000af5e56713e5082 tools/__init__.py a85fe8169218b1abe90093cc5d7f8bccc0cb1eb98a4670881b31d37834e54893 tools/oci-extract/client_test.go -a8976b81a8096be5dd2b1404be36b4b295a1f92a3cae6be6fe9630a61855c6ec docs/design/README.md a8ecf9c2551505fd5a4c477c735c88fff9c4627136dade955cdcbfc16d8ca131 docs/en/makefile-cheatsheet.md aedb718131b5633d08f58ac67b23d3940b4fbffd98e93c9f75db3cf80903f1f8 module/schemas/core/instance.json b1609aa1ad37f8f682e3025d866eaebe9719802b34aac580387d3bce65935f30 module/observed.go @@ -254,4 +254,5 @@ fb5779e0edb8a71595d9d8c81946bfb324b86066c6b94b73b036e3e110591b5c module/testdat fb885dd678928855a632f1411e364e0674409d8fa15da767ce07d036e2da824f tools/oci-extract/cmd/oci-sweep/main.go fbe50f259dca8b38a1772df4d5e3f70509cd5293ec7944a08f424713479646c8 docs/design/specs/canonical-json.md fc893fc83e0ba0aac68d4fa7813ec56ac425fe385e4d896fd77532ee94a39509 tools/oci-extract/testdata/vcn.go +fc9e856ba10b6becd06955ebb0a4d443abf77f32cfd1a2406dc8ad534b8c7beb docs/design/README.md fd1ca75aba965be594bceb3fe1ad0232750f0ba1a9232dbb5ed64eb280e8c60e docs/design/specs/provider-abi.md diff --git a/docs/design/README.md b/docs/design/README.md index 2d5bb20..4792b5d 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -31,6 +31,9 @@ namespace it opens. Written 2026-07-18 from the design session recorded in computed over. - [specs/plan-digest.md](specs/plan-digest.md) — `plan_digest`, `target_digest`, `execution_digest` and the gate `execute` applies before it signs anything. +- [decision-brief-target-and-binding.md](decision-brief-target-and-binding.md) — one place for the open + decisions on target data and execution binding (architecture, contracts, order of implementation), + with the dependencies between them; it decides nothing. - [specs/realization-context.md](specs/realization-context.md) — D5-2: a survey of what is written and what is in code about the realization context that target data should be derived from, where the chain breaks, and a proposal (concept). diff --git a/docs/design/decision-brief-target-and-binding.md b/docs/design/decision-brief-target-and-binding.md new file mode 100644 index 0000000..6abb4d3 --- /dev/null +++ b/docs/design/decision-brief-target-and-binding.md @@ -0,0 +1,118 @@ +# Decision brief: target data and execution binding + +Status: **a brief for decisions.** It decides nothing. Every "recommendation" is the author's; the +decision is the owner's, and where a decision touches another repository's contract it is joint (see the +codes below). It gathers what the documents of this series left open, in one place, in the order in which +the decisions depend on each other. + +Documents it draws on: `specs/plan-digest.md` (M4a, implemented), `specs/approval-and-execution-state.md` +and `relay-requirements.md` R6 to R10 (M4b, concept), `specs/destroy-invoke-binding.md`, +`specs/target-origin-and-path-safety.md` (D5), `specs/realization-context.md` (D5-2, with the Forms side in +its section 6). + +## 0. How to read it + +Each decision carries one or more codes for how it can be settled: + +- **[S]** decidable from the sources: the answer is a fact that can be read; +- **[M]** needs a measurement that has not been made; +- **[O]** the owner's choice, there is no fact to read; +- **[J]** joint: it changes the contract of another repository (Forms library, engine, Relay) and cannot be + decided in this repository alone. + +The three layers depend on each other in one direction: **architecture decisions constrain contract +decisions, and contract decisions constrain the order of implementation.** The layers are kept apart so +that a module-level step is not read as an answer to an architecture question. + +## 1. Where things stand + +| Work | State | +|---|---| +| M1 (resource id syntax), M3 (registry-conformant execute), M5 (poll target), exact JSON equality, M4a (plan, target and execution digests, derive-again gate) | **implemented**, merged, CI green | +| M4b (approval, authority, single use, evidence), R6 to R10 | **concept**: requirements toward the Relay, not raised in CIC-Relay, nothing implemented there | +| `destroy` and `invoke` binding | **measured** (they bypass the `execute` gate), contract **proposed** | +| Target data origin (D5) and the realization context (D5-2) | **measured / surveyed**, contract **proposed** (concept) | + +The M4a gate proves a plan and a target are consistent with each other. It does not prove approval, +authority, single use, or where the target came from. + +## 2. Layer A: architecture decisions + +These decide what the realization context is and where it lives. The other decisions in this layer (A2 to A7) +cannot be settled until A1 is; the module-only steps of section 4 do not wait for it. + +| ID | Decision | Code | Recommendation | +|---|---|---|---| +| **A1** (D5-6) | The realization context **inside** the materialized object, or **outside** it, bound at the execution layer | **[J][O]** | Work on (ii), outside, as an assumption to be confirmed, because it keeps the object provider-independent and the receipt contract out of it. (i) is not excluded: it means reconsidering the object's schema and boundary, and whether the existing receipt can represent the derivation without an extension is **not verified**. Not a choice for this repository alone: it touches the object boundary and the Forms library and engine contracts | +| A2 (D5-2 Q1) | Where a realization context is authored and stored: deployment repository, Relay configuration, a schema kind in the registry, elsewhere | [O][J] | none: the sources are silent | +| A3 (Q2) | Granularity: one context per environment shared by many objects (object binding kept in the state), or one per object | [O] | per environment with the object binding in the state, since the state model already separates the logical identity (`uid`) from the provider identity (`provider_id`) | +| A4 (Q3) | Who issues and signs a context, and what authenticates it | [O][J] | the layer that realizes the object issues it; its authenticator reaches the module through the Relay's authenticated execution context (R6) | +| A5 (Q5) | Routing and decomposition: how one intent spanning providers or regions becomes several realizations | [O][J] | defer: the data path calls it concept, and no first slice needs it | +| A6 (Q6) | Lifecycle: rotation and revocation of the execution identity binding; an approved but unexecuted plan whose context changed | [O] | an approval names `execution_digest`, which commits to the target, but the current `execution_digest` does not commit to a realization context: `target_digest` binds only `host`, `base_path`, `key_id`, `kind`, `resource_id` and `revision` (`module/plan_binding.go`, `targetEnvelope`). A changed realization context does not necessarily change it, and an unchanged `key_id` does not show that the authority behind it is unchanged. The context identity or digest, its validity and its authorization binding must be part of the approval's verified execution context; whether that extends `execution_digest` or is a separate approval binding stays an open architectural decision (R7); rotation and revocation policy is still the owner's | +| A7 (D5-7) | A distinct name for the realization environment, so it is not confused with the engine's "environment" (the processing layer) | [O] | decide first: it is cheap and every later document uses the word | + +## 3. Layer B: contract decisions, by boundary + +### 3.1 Provider module + +| ID | Decision | Code | Recommendation / what settles it | +|---|---|---|---| +| D-DI-1 | `invoke` runs only `action`-role operations | [O] | yes: ends the measured bypass (an `invoke` of a delete, update, create or read operation) | +| D-DI-2 | A field outside the operation's declared set: refuse or drop silently | [O] | refuse | +| D-DI-3 | The number form of the body that is sent (canonical `e`, or a plain decimal when lossless and bounded) | **[M]** | cannot be decided without measuring what OCI accepts for an integer field; the canonical-JSON round trip alone is not enough, the request must also be valid under the target OCI request schema (review of #46, F2) | +| D-DI-4 | One field name `execution_digest` for `execute`, `destroy` and `invoke`, told apart by the digest's tag | [O] | yes | +| D-DI-5 | Keep the old, digest-less `destroy` and `invoke` request | [O] | no: no consumer was found in the repositories cloned here; repositories not cloned here were not checked | +| **Source of an action's fields** (review of #46, F1) | Where the declared fields of an `invoke` come from | **[S]** | **the registry already carries it**: each of the four `action`-role operations (`AddVcnCidr`, `ChangeVcnCompartment`, `ChangeSubnetCompartment`, `ChangeInstanceCompartment`) has an `input` schema with declared `properties` and `additionalProperties: false` (read from `module/schemas/core/*.json`); the other roles have none. The module's `resourceContract` does not load it today (it keeps `method`, `path`, `role`). So the source is the operation's own `input` schema, not the config's `action-managed` fields. Whether every future action operation will carry one was not checked | +| D5-1 | Record the service API version per service in the registry, so `base_path` is derived and no longer given | [S][M] | needs the extractor and the SDK read (how the Go SDK exposes a service's API version is **not verified**); it is independent of A1 because the provider contract lives in the registry under both alternatives | +| D5-4 | Structural checks of `host` and `base_path` before `sign` (one path builder, no URL syntax, no control characters): refuse or normalize | [O] | refuse; it is defense in depth at the single place that builds the path (four entry points share it), not the architecture's starting point | +| D5-5 | The `poll` alias with an empty `base_path` (it takes the API version from the caller today) | [O] | once D5-1 lands the version comes from the registry; until then leave as it is | +| D-M5-3 | A retirement date for the `poll` `path` alias | [O] | none: it was left to a separate compatibility decision | + +### 3.2 Relay (read-only from here) + +| ID | Decision | Code | Note | +|---|---|---|---| +| R-raise | Raise R6 to R10 as issues in CIC-Relay (the file says "not yet raised") | [O] | the Relay team owns the design; R6's content (what the authenticated execution context carries) depends on **A1** and **A4** | +| R-host | The host-boundary property of R7 (the approval binds the actual `sign` and `actuate` calls) | [J] | stated as a required property, not a design | + +### 3.3 Forms library and engine + +Only if **A1** is (i): reconsidering the object's schema and boundary, and checking whether the existing +closed receipt can represent the derivation of context-derived values without an extension. If A1 is (ii) +the context lives outside the object, so these two do not automatically need a contract change; the +concrete integration requirements are still to be checked separately. + +## 4. Layer C: order of implementation + +Steps 1 to 3 are module-only and do **not** depend on the architecture layer. Step 4 does. None of 1 to 3 +is the realization proof, and none of them should be reported as one. + +| Step | What | Needs | +|---|---|---| +| 1 | Path-building hardening: one builder, structural checks, nothing that is not a path segment reaches the string that is signed, checked before `sign` | D5-4 | +| 2 | The API version in the registry, so `base_path` is derived | D5-1 (an SDK read) | +| 3 | The `destroy` and `invoke` execution digests, with the action input from the registry and `invoke` limited to `action` operations | D-DI-1, 2, 4, 5 and the registry `input` source; **D-DI-3 needs a measurement first** | +| 4 | The realization context: its record, its digest, its delivery to an execution, the derivation of the target | **A1 to A4** and, depending on A1, the Forms and engine contracts, the Relay's R6 and R7 | +| 5 | M4b on the Relay side | the Relay team, after R-raise | + +## 5. Measurements that are missing + +| Measurement | Needed for | +|---|---| +| What OCI accepts as the number form of an integer field in a request body | D-DI-3 | +| The request-target that actually goes out over the network (the real Relay, and the Go HTTP client's output for a URL with a query or a fragment), not the mock's URL | step 1; the review of #47 asks for this evidence before an implementation review | +| What OCI or a proxy does with dot segments, an encoded dot segment and a double slash | step 1 | +| Whether the OCI operations used accept an idempotency token the `execution_digest` could be derived into | the UNKNOWN state of M4b | +| The fields of a real Work Request response (the resources it names), and the type segment of its OCID | correlating a Work Request with an execution | +| A run of the rewritten manual harness against real OCI | the harness has only been compiled | + +## 6. Still on hold, unchanged + +The `module.wasm` rebuild, signature and release; the production integration; the asynchronous create +cases B and C; phase 3 of the CI-integrity issue (#37). This brief does not change any of them. + +## What this brief does not do + +It does not decide anything, change a contract, or claim that any step is implemented. The +recommendations are one author's reading of the documents of this series. Decisions marked [J] cannot be +closed by this repository: they need the owners of the Forms library, the engine and the Relay.