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
3 changes: 2 additions & 1 deletion MANIFEST.sha256
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
3 changes: 3 additions & 0 deletions docs/design/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
118 changes: 118 additions & 0 deletions docs/design/decision-brief-target-and-binding.md
Original file line number Diff line number Diff line change
@@ -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 `<digits>e<exp>`, 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.
Loading