docs: what destroy and invoke do today, and a binding contract proposal

MANIFEST.sha256

@@ -78,11 +78,13 @@
 5432506f15d65fa59572362a70db4bc403c13b163ec961ecb2951d7f98d093d0  module/go.mod
 546e7c533da4b86b8817ee426865df0d11e24d2aa1580647634345f452a5017e  module/canonical_json_test.go
 57980b8a84a13ffad62b7295e3095bd635f8894716665d0654dfb54eebbf10e5  docs/contracts/en/host-expectations.md
+5b7f1f228e76f1240526022991728bbe1834c4c06b19ed5f52a15441e54dd6ee  docs/design/README.md
 5c650f84f688d4d965721df74779228bb6fdfa47d5c08c46e8274e6d97b212c8  module/testdata/vcn-v1/lifecycle-map.json
 5ca6da66b9de8a04ca71f1c18ba2026ad02b8c1c70c700a432058da267e6b27d  module/correspondence/vcn.json
 5d51889fc8cd00c4c0bf1462b01be8c4d6754e2a4e59dd8e7f0599c610c64472  tools/vault-sign-agent.sh
 5d8afd2b9d29065c768de8a21562049904b7c4ad3449448c3159af34e3a0b9df  docs/en/concept/git-management.meta.yaml
 5daa3bf50db9db492aac5721bddc0837a6a30dec9558d886abf45ad89632f68e  module/manual_real_oci_test.go
+60f8027dfd091bdaddd7537c65780676cabd460e85b6c7657e8eed294c8b1de7  docs/design/measurements/destroy-invoke/output.txt
 635384b1db18a7654d1e30b660ba825645d88a89e7bc0e808500a213b584f278  module/testdata/vcn-v1/cases/malformed-cidr/expected/observed.registry.json
 66181e4c6a0b2735b5a8b3088b37e6a844e2c692399a5b72b036059da0188e0a  tools/releaselib/__init__.py
 688dffd2264877f3a64fca1d3526c57bb34cb1c18f5a01aa906667311831a052  docs/en/workflow.md
@@ -94,11 +96,11 @@
 6db64092fb2c2dc8bcbd3e321faf04f6cc40b16e890c8dec3e56e4178df01402  LICENSE.yaml
 6e47d263c8203e2fdd44672be70aeb71456e767e0d2ea6840831f6070eb8214f  tools/oci-extract/testdata/polymorphic.go
 6f3655bf787efee284225bcb6096913d0ec556771dddb42845311e649c21e7ad  docs/hu/concept/declarative_ecosystem_integration.md
+7038a486c0c4b17922d3c35885486cf27321baec8ba9262c04b7db36333aba45  docs/design/measurements/destroy-invoke/probe_test.go.txt
 7068014ecee4111cb4456d3d3328c33b53a79c7803d68f040036f34449423f65  tools/oci-extract/testdata/instance.go
 7080b3423beded8b64891afdcf2e6f6d8bec6ebeaa88aecbb1b06e149b54ef86  module/module.wasm
 7136d8366bbd7c5ccc19a3d810a7f55c31541acec9b0f05bd84e45a39107ded7  tests/test_capability_manifest.py
 7426752feb1140b2023192728df35248e4f802617c150bb0523ab97dc1638c0b  tools/init-hooks.sh
-7499755898c9fe815f8cb5b62314630258bc68fe5d461097ff7f10644508bed3  docs/design/README.md
 74d93981f1935d21001ed0475ebb84132ab67c71840ca82ca0cbfac5aca29ea2  docs/contracts/en/wasm-abi.md
 763f2814427dc8faaa7fb1ccf3e8afe2f6460273a2dfe852287b3ef66bc43b96  tools/oci-extract/policy_test.go
 768d54fe8ec5fde38c41ec075ce02b51d93cf3bf5f47e8d81e33932f3e3ece27  module/ocid_boundary_test.go
@@ -107,9 +109,11 @@
 79273b206c6143ede2e8a28f7c3d667d93c5978c764b3db4f543c7f4a477253b  module/testdata/vcn-v1/cases/transport-error/expected/evidence.claims.json
 794a6e83b11358f4f2105408d7798a3495fa992d09d469823d0148233e6df57e  module/relay_integration_test.go
 79f7c4ad204e39c79b7b55a0ee925a603250bb49610366a98e3210e1b925abd3  module/testdata/vcn-v1/cases/malformed-cidr/expected/observed.oci.json
+7b2748a353c7aad1822022fbbb4a6271c54ef84a0fe5f3535f43850306857756  docs/design/measurements/destroy-invoke/README.md
 7b84214b85a3fd95e9153528df1fa1522ff026df1f561752d95c715250301ca6  tools/vault-sign-agent.md
 7df714ce12b9abfb18357c4fc25e67b8f23e6557b72ee1ea4c2a4a5d4a596c43  docs/contracts/hu/host-expectations.md
 7e18dd94212c07eb66f6db357067b71e870dc64d43336f9c1db3c08b30adf0f4  module/testdata/vcn-v1/cases/not-found/expected/observed.registry.json
+7eee1cc0f4fa15a4519d9f233388a647da0caddbb0521de3493843e0cbc31d25  docs/design/specs/destroy-invoke-binding.md
 7efd45c44d808639d5fe607cf4182e930be6b8d82709e716114e63512f69b55f  module/testdata/vcn-v1/cases/conformant/expected/verdict.fields.json
 805c05942247d6327f0f006a8799119ace530c4ae288ad637d0f8faddca21d86  docs/hu/architecture.md
 806851c10862d6900eb858a229e3ba7138943abe3fd75e5b1e8f8ca4b57d1d6f  mk/golang.mk
@@ -153,6 +157,7 @@ a85fe8169218b1abe90093cc5d7f8bccc0cb1eb98a4670881b31d37834e54893  tools/oci-extr
 a8ecf9c2551505fd5a4c477c735c88fff9c4627136dade955cdcbfc16d8ca131  docs/en/makefile-cheatsheet.md
 aedb718131b5633d08f58ac67b23d3940b4fbffd98e93c9f75db3cf80903f1f8  module/schemas/core/instance.json
 b1609aa1ad37f8f682e3025d866eaebe9719802b34aac580387d3bce65935f30  module/observed.go
+b28519ff1d7882a9ba98b06b57ba5b7ecfb4ff888d180db5f5f4bae0f4b56fb2  docs/design/measurements/destroy-invoke/raw_probe_test.go.txt
 b2c3bf78eb4368f14eb5d380cd7aee88bf33c39f88613fa1fae00f551f7e1d83  module/testdata/vcn-v1/plan.json
 b304ac8143d669cbb505d50ffbeb11deac010d54cfab4fa2f0d6ac2355382e7f  module/cicflow_host.go
 b3585cfa2c622b28548424d092f4ee05a679d7ced46a762f7c1f5bc4931e5c27  tools/oci-extract/testdata/bucket.go

docs/design/README.md

@@ -31,6 +31,10 @@ 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.
+- [specs/destroy-invoke-binding.md](specs/destroy-invoke-binding.md) — a measurement of what
+  `destroy` and `invoke` do today, the properties it implies, and a binding contract proposal
+  (concept); the probes and their output are in
+  [measurements/destroy-invoke/](measurements/destroy-invoke/README.md).
 - [specs/approval-and-execution-state.md](specs/approval-and-execution-state.md) — M4b (concept):
   what an approval names, the execution state of one approval (atomic reservation, UNKNOWN),
   the ProofTrace evidence, and the acceptance tests the Relay side will be held to.

docs/design/measurements/destroy-invoke/README.md

@@ -0,0 +1,55 @@
+# Destroy and Invoke: measurement of the current behaviour
+
+What this is: the scratch probes and their output behind the tables in
+[`../../specs/destroy-invoke-binding.md`](../../specs/destroy-invoke-binding.md), section 1. They
+observe what `Destroy` and `Invoke` are given and what they sign and send. They are kept here
+unchanged so that the tables can be checked, not taken on trust.
+
+## Environment of the recorded run
+
+| | |
+|---|---|
+| Module commit measured | `eda4aebbe65bdfcf8e1d5a1a37db9df3d943013a` (`devel`), taken with `git archive` into an empty directory, so no working-tree residue |
+| Production code vs the earlier run | the same run was first made on `f48246e`; `module/provider.go`, `canonical_json.go`, `plan_binding.go` and `abi.go` are identical in `eda4aeb` (empty `git diff`), and the output of the two runs is identical apart from timings |
+| Go | go1.25.0 linux/amd64 (the repo's builder image) |
+| TinyGo | 0.39.0 (not used by the probes) |
+| Builder image | `cic-module-oracle-cloud-builder:latest`, id `sha256:b5a3b64b391e6d4a1254b41dfa59f78025a603cfccdaacf902c408967047debf` |
+| Host | Linux 7.0.0-43-generic |
+| Provider | none. The host seam is the module's own test mock (`cicFlowMock` in `module/cicflow_mock_test.go`): `sign` returns a fixed signature, `actuate` answers with a configured status and body. No OCI endpoint, credential or network is involved |
+
+"sign" and "actuate" in the tables are the numbers of calls that reached that mock seam.
+
+## Files
+
+- `probe_test.go.txt` - `TestZZDestroy`, `TestZZInvoke`, `TestZZRenderBodyVsInvoke`: the
+  dimension changes, the operation roles, the replay counts and the `renderBody` comparison.
+- `raw_probe_test.go.txt` - `TestZZInvokeRawBodies`: the body fidelity of `Invoke`. The request
+  TEXT is written out byte by byte (a backslash is `"\x5c"`) and handed to `Invoke` as it is, because
+  a request built with `json.Marshal` rewrites the body text (it compacts whitespace and escapes
+  `<`, `>`, `&`) and an editor or tool can rewrite an escape sequence typed into a source file;
+  either would make the body measurement meaningless.
+- `output.txt` - the output of the recorded run, verbatim (`DI` lines from the first file,
+  `RAW` lines from the second).
+
+The files end in `.txt` so that they are not compiled into the module.
+
+## Rerun
+
+From a clean checkout of the commit above, in a scratch copy (not in the repository):
+
+```
+cp probe_test.go.txt     <scratch>/module/zz_di_probe_test.go
+cp raw_probe_test.go.txt <scratch>/module/zz_di_raw_test.go
+cd <scratch>/module
+go test -count=1 -run 'TestZZ' -v .
+```
+
+The two files belong together (the second uses `ok200` from the first). They use helpers of the
+module's test package (`cicFlowMock`, `decodeResult`, `execBinding`, `destroyRequest`,
+`invokeRequest`, `renderBody`), which exist at the commit above.
+
+## Limits of this measurement
+
+It measures the module against a mock host seam. It does not measure what the Relay does with the
+calls that reach it, what OCI answers, or whether OCI accepts any request body; the real
+provider was not involved.

docs/design/measurements/destroy-invoke/output.txt

@@ -0,0 +1,41 @@
+DI destroy: baseline                                              status=ok    sign=1 actuate=1 | DELETE iaas.eu-frankfurt-1.oraclecloud.com/20160918/vcns/ocid1.vcn.oc1..approved body="" key=t/u/f if-match=etag-1
+DI destroy: only binding.resource_id differs                      status=ok    sign=1 actuate=1 | DELETE iaas.eu-frankfurt-1.oraclecloud.com/20160918/vcns/ocid1.vcn.oc1..OTHER body="" key=t/u/f if-match=etag-1
+DI destroy: only binding.host differs                             status=ok    sign=1 actuate=1 | DELETE iaas.us-ashburn-1.oraclecloud.com/20160918/vcns/ocid1.vcn.oc1..approved body="" key=t/u/f if-match=etag-1
+DI destroy: only binding.base_path differs                        status=ok    sign=1 actuate=1 | DELETE iaas.eu-frankfurt-1.oraclecloud.com/20990101/vcns/ocid1.vcn.oc1..approved body="" key=t/u/f if-match=etag-1
+DI destroy: only binding.key_id differs                           status=ok    sign=1 actuate=1 | DELETE iaas.eu-frankfurt-1.oraclecloud.com/20160918/vcns/ocid1.vcn.oc1..approved body="" key=other/tenancy/key if-match=etag-1
+DI destroy: only binding.revision differs                         status=ok    sign=1 actuate=1 | DELETE iaas.eu-frankfurt-1.oraclecloud.com/20160918/vcns/ocid1.vcn.oc1..approved body="" key=t/u/f if-match=etag-STALE
+DI destroy: instance kind (TerminateInstance)                     status=ok    sign=1 actuate=1 | DELETE iaas.eu-frankfurt-1.oraclecloud.com/20160918/instances/ocid1.instance.oc1..i body="" key=t/u/f if-match=
+DI destroy: the same request 3x, provider 204 then 404 -> results=[ok error/not-found error/not-found] sign=3 actuate=3
+--- PASS: TestZZDestroy (0.00s)
+DI invoke: baseline ChangeVcnCompartment                          status=ok    sign=1 actuate=1 | POST iaas.eu-frankfurt-1.oraclecloud.com/20160918/vcns/ocid1.vcn.oc1..approved/actions/changeCompartment body="{\"compartmentId\":\"ocid1.compartment..c\"}" key=t/u/f if-match=etag-1
+DI invoke: only binding.resource_id differs                       status=ok    sign=1 actuate=1 | POST iaas.eu-frankfurt-1.oraclecloud.com/20160918/vcns/ocid1.vcn.oc1..OTHER/actions/changeCompartment body="{\"compartmentId\":\"ocid1.compartment..c\"}" key=t/u/f if-match=etag-1
+DI invoke: only binding.host differs                              status=ok    sign=1 actuate=1 | POST iaas.us-ashburn-1.oraclecloud.com/20160918/vcns/ocid1.vcn.oc1..approved/actions/changeCompartment body="{\"compartmentId\":\"ocid1.compartment..c\"}" key=t/u/f if-match=etag-1
+DI invoke: only binding.base_path differs                         status=ok    sign=1 actuate=1 | POST iaas.eu-frankfurt-1.oraclecloud.com/20990101/vcns/ocid1.vcn.oc1..approved/actions/changeCompartment body="{\"compartmentId\":\"ocid1.compartment..c\"}" key=t/u/f if-match=etag-1
+DI invoke: only binding.key_id differs                            status=ok    sign=1 actuate=1 | POST iaas.eu-frankfurt-1.oraclecloud.com/20160918/vcns/ocid1.vcn.oc1..approved/actions/changeCompartment body="{\"compartmentId\":\"ocid1.compartment..c\"}" key=other/tenancy/key if-match=etag-1
+DI invoke: only binding.revision differs                          status=ok    sign=1 actuate=1 | POST iaas.eu-frankfurt-1.oraclecloud.com/20160918/vcns/ocid1.vcn.oc1..approved/actions/changeCompartment body="{\"compartmentId\":\"ocid1.compartment..c\"}" key=t/u/f if-match=etag-STALE
+DI invoke: operation=DeleteVcn (registry role delete)             status=ok    sign=1 actuate=1 | DELETE iaas.eu-frankfurt-1.oraclecloud.com/20160918/vcns/ocid1.vcn.oc1..approved body="{\"compartmentId\":\"ocid1.compartment..c\"}" key=t/u/f if-match=etag-1
+DI invoke: operation=UpdateVcn (registry role update)             status=ok    sign=1 actuate=1 | PUT iaas.eu-frankfurt-1.oraclecloud.com/20160918/vcns/ocid1.vcn.oc1..approved body="{\"compartmentId\":\"ocid1.compartment..c\"}" key=t/u/f if-match=etag-1
+DI invoke: operation=CreateVcn (registry role create)             status=ok    sign=1 actuate=1 | POST iaas.eu-frankfurt-1.oraclecloud.com/20160918/vcns body="{\"compartmentId\":\"ocid1.compartment..c\"}" key=t/u/f if-match=etag-1
+DI invoke: operation=GetVcn (registry role read)                  status=ok    sign=1 actuate=1 | GET iaas.eu-frankfurt-1.oraclecloud.com/20160918/vcns/ocid1.vcn.oc1..approved body="{\"compartmentId\":\"ocid1.compartment..c\"}" key=t/u/f if-match=etag-1
+DI invoke: operation=AddVcnCidr (registry role action)            status=ok    sign=1 actuate=1 | POST iaas.eu-frankfurt-1.oraclecloud.com/20160918/vcns/ocid1.vcn.oc1..approved/actions/addCidr body="{\"compartmentId\":\"ocid1.compartment..c\"}" key=t/u/f if-match=etag-1
+DI invoke: unknown field names like an Execute plan would filter  status=ok    sign=1 actuate=1 | PUT iaas.eu-frankfurt-1.oraclecloud.com/20160918/vcns/ocid1.vcn.oc1..approved body="{\"displayName\":\"x\",\"lifecycleState\":\"TERMINATED\",\"id\":\"ot..." key=t/u/f if-match=etag-1
+DI invoke: the same request 5x -> sign=5 actuate=5
+--- PASS: TestZZInvoke (0.00s)
+DI renderBody(ChangeVcnCompartment, role action) = "{\"compartmentId\":\"ocid1.compartment..c\"}"
+DI renderBody(UpdateVcn, role update) = "{\"displayName\":\"X\"}"
+DI renderBody(CreateVcn, role create) = "{\"compartmentId\":\"ocid1.compartment..c\",\"displayName\":\"X\"}"
+DI renderBody(DeleteVcn, role delete) = ""
+DI renderBody(GetVcn, role read) = "{}"
+--- PASS: TestZZRenderBodyVsInvoke (0.00s)
+RAW whitespace and key order are kept                    status=ok    sign=1 actuate=1 sent="{ \"z\" : 1 , \"compartmentId\" : \"ocid1.compartment..c\" }" identical_to_input=false
+RAW a duplicate key is kept                              status=ok    sign=1 actuate=1 sent="{\"compartmentId\":\"ocid1.compartment..a\",\"compartmentId\":\"ocid1.compartment..b\"}" identical_to_input=true
+RAW a u-escape is kept as written                        status=ok    sign=1 actuate=1 sent="{\"s\":\"\\u00e9\\u003c\"}" identical_to_input=true
+RAW 2^53+1 and 1.0 are kept as written                   status=ok    sign=1 actuate=1 sent="{\"n\":9007199254740993,\"m\":1.0}" identical_to_input=true
+RAW data is JSON null                                    status=ok    sign=1 actuate=1 sent="null" identical_to_input=true
+RAW data is an array                                     status=ok    sign=1 actuate=1 sent="[1,2,3]" identical_to_input=true
+RAW data is a string                                     status=ok    sign=1 actuate=1 sent="\"just a string\"" identical_to_input=true
+RAW extra fields besides the action's                    status=ok    sign=1 actuate=1 sent="{\"compartmentId\":\"ocid1.compartment..c\",\"displayName\":\"EVIL\",\"lifecycleState\":\"TERMINATED\"}" identical_to_input=true
+RAW config absent entirely                               status=ok    sign=1 actuate=1 sent="{}" identical_to_input=false
+RAW data is not JSON (the whole request is not JSON)     status=error sign=0 actuate=0
+--- PASS: TestZZInvokeRawBodies (0.00s)
+ok  	github.com/CentralInfraCore/wasm-module-template/module	0.005s