From de334e401028753932d806b6165d8a206ebd8a9b Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Tue, 14 Jul 2026 08:23:24 -0700 Subject: [PATCH 01/52] Add standard hosting profiles RFC --- rfcs/0023-standard-hosting-profiles.md | 441 +++++++++++++++++++++++++ 1 file changed, 441 insertions(+) create mode 100644 rfcs/0023-standard-hosting-profiles.md diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md new file mode 100644 index 00000000..8ef1af2e --- /dev/null +++ b/rfcs/0023-standard-hosting-profiles.md @@ -0,0 +1,441 @@ +--- +title: Standard Hosting Profiles +authors: + - Gio +created: 2026-07-14 +last_updated: 2026-07-14 +status: draft +issue: +rfc_pr: +--- + +# Proposal: Standard Hosting Profiles + +## Summary + +Define a small catalog of named, release-tested OpenClaw runtime postures: +`local`, `container`, `reverse-proxy`, and `node-mode`. A selected profile +composes canonical readiness conditions into a support contract, identifies the +runtime activation being evaluated, and can be validated against packaged +release evidence. + +This RFC depends on the separate Readiness Conditions and Providers RFC. That +RFC is directly usable: operators may explicitly select additional required or +advisory criteria without any profile. This RFC adds named, release-tested +presets over the same mechanism; it does not redefine readiness evaluation or +provider lifecycle. + +## Motivation + +OpenClaw can be deployed in many shapes, but "OpenClaw supports containers" or +"OpenClaw supports hosted deployments" is too broad to test or support. The +same package may run: + +- as a local foreground Gateway; +- directly reachable through a container listener; +- behind a trusted identity proxy; or +- as a controller for one or more paired execution targets. + +Each posture has different facts that must be true before it can serve its +supported role. Today hosts encode those facts in startup flags, environment +variables, Docker health checks, adapter code, and private support checklists. +OpenClaw cannot report which posture was intended, and release tests cannot +make a durable support claim about it. + +Standard profiles turn that open-ended claim into a small product contract: + +```text +OpenClaw supports these named runtime postures. +Each posture composes stable readiness conditions. +Each release executes the matching conformance scenarios. +The running process reports which posture and activation it represents. +``` + +This helps maintainers reproduce issues against a supported subset without +preventing operators from configuring OpenClaw directly or running outside the +standard catalog. + +## Goals + +- Define `local`, `container`, `reverse-proxy`, and `node-mode` as standard + OpenClaw support profiles. +- Make selection optional and preserve zero-configuration local behavior. +- Select profiles through config, environment, or Gateway startup arguments + with explicit precedence. +- Compose profiles from reusable canonical readiness conditions. +- Define exact predicates and stable reasons for profile-specific conditions. +- Report the selected profile through readiness, health, and status. +- Identify the logical runtime and unique process/container incarnation whose + profile result is being reported. +- Let operator profiles extend, but never weaken, a standard profile. +- Bind packaged conformance evidence to an immutable OpenClaw artifact and + profile contract version. +- Keep host orchestration and OpenClaw runtime ownership separate. + +## Non-Goals + +- Define the canonical readiness-condition schema or plugin provider API. +- Generate, merge, repair, or replace OpenClaw configuration. +- Encode Docker, Kubernetes, systemd, Nomad, or ECS retry/interval settings. +- Define OCC resources, placement, tenant identity, quotas, or admission. +- Define the AgentHarness event protocol or put agent traffic in a control + plane. +- Standardize host storage, telemetry sinks, routing, worker pools, or admin + UX. +- Make the optional Policy or Doctor subsystems dependencies of startup. +- Guarantee checkpoint durability, restore compatibility, or safe destruction. +- Claim that every possible OpenClaw configuration belongs to a standard + profile. + +## Proposal + +### Dependency on canonical readiness + +This RFC assumes the contract proposed by Readiness Conditions and Providers: + +```text +condition type + status + requirement + reason + message +``` + +Profiles do not create a second evaluator. A profile is declarative data that +supplies a named preset of reusable conditions and requirement classes. The +canonical readiness engine evaluates those conditions exactly as if the +operator had selected them explicitly through `gateway.readiness`. + +Universal Gateway startup, drain, and selected-channel readiness remains in +force for every profile. No profile may remove, replace, or weaken it. + +```text +RFC 0018 direct use: + universal conditions + operator-selected criteria -> readiness + +RFC 0023 profile use: + universal conditions + standard profile preset + operator additions + -> readiness + OpenClaw support/conformance claim +``` + +### Standard profile catalog + +| Profile | Runtime posture | Additional required conditions | +| --- | --- | --- | +| `local` | Default local or foreground Gateway | Valid effective config, writable workspace, Gateway response, and required activation facts. | +| `container` | Gateway directly reachable through a container listener | `local` plus `ContainerStateReady`. | +| `reverse-proxy` | Gateway behind a trusted identity proxy | `local` plus `TrustedProxyReady`. Loopback remains valid for a same-host proxy. | +| `node-mode` | Gateway controlling one or more execution targets | `local` plus pairing, connected target, command approval, and control-channel conditions. | + +A profile names runtime posture, not packaging. Docker behind an identity proxy +selects `reverse-proxy`; Docker with a directly reachable listener selects +`container`. + +New standard profiles require an independently useful support posture, stable +condition predicates, packaged conformance scenarios, and an owner willing to +maintain the support promise. A new diagnostic condition alone does not justify +a new profile. + +### Profile conditions + +The standard catalog composes conditions owned by the canonical readiness +contract and existing OpenClaw runtime owners. + +| Condition | Profile | True when | Stable non-ready reasons | +| --- | --- | --- | --- | +| `ProfileSelected` | All | Selection precedence resolves to a valid standard or configured operator profile. | Invalid explicit values fail startup validation. | +| `RuntimeActivationIdentified` | All | Non-empty logical-runtime and unique-incarnation identities are resolved. | `RuntimeIdentityInvalid`, `IncarnationIdentityInvalid`, `ActivationIdentityUnavailable` | +| `ContainerStateReady` | `container` | Effective Gateway mode is local and resolved listener host is not loopback. | `ContainerGatewayRemote`, `ContainerGatewayLoopback`, `ContainerBindNotResolved` | +| `TrustedProxyReady` | `reverse-proxy` | Auth mode is `trusted-proxy`, a user header is configured, and at least one trusted source is present. | `TrustedProxyAuthMissing`, `TrustedProxyHeaderMissing`, `TrustedProxySourcesMissing` | +| `NodePairingReady` | `node-mode` | Pairing state is readable and contains an approved pairing. | `NodePairingUnavailable`, `NodePairingTimedOut`, `NodePairingPending`, `NodePairingMissing` | +| `ControlledTargetsReady` | `node-mode` | At least one connected target is correlated to an approved pairing. | `ControlledTargetsDisconnected` | +| `CommandApprovalReady` | `node-mode` | A connected paired target advertises a command permitted by effective grants. | `CommandApprovalMissing` | +| `ControlChannelReady` | `node-mode` | At least one live target session is correlated to an approved pairing. | `ControlChannelUnavailable` | + +`node-mode` stays product-neutral. A target may be a desktop, sandbox, VM, pod, +browser, or another execution surface. OpenClaw does not assume one node maps to +exactly one product or tenant. + +Common runtime conditions such as `ConfigLoaded`, `WorkspaceWritable`, +`GatewayResponding`, and conditionally required plugin, secret, or model-route +activation remain owned by readiness and their source subsystems. Profiles only +declare when they are required for the supported posture. + +### Selection and precedence + +Profile selection is optional. When no value is supplied, OpenClaw resolves +`local` so existing installations remain zero-configuration. + +Selection precedence is: + +```text +gateway startup argument +> OPENCLAW_HOSTING_PROFILE +> openclaw.json +> local default +``` + +Example: + +```json5 +{ + hosting: { + profile: "container", + }, +} +``` + +Equivalent startup selection: + +```bash +OPENCLAW_HOSTING_PROFILE=container openclaw gateway run +openclaw gateway run --hosting-profile container +``` + +The effective profile, selection source, and condition result are reported by +readiness, health, and status. Hosts may assert an expected profile when +probing, but expectation is an assertion over the running result, not another +selection source. + +Profiles validate effective runtime state. They do not generate or repair the +underlying Gateway, proxy, plugin, model, node, or storage config. + +### Runtime activation identity + +A readiness result must be attributable to one runtime activation. OpenClaw +resolves: + +- a logical runtime ID that may remain stable across process replacement; and +- a unique incarnation ID for the current process/container activation. + +Launchers may provide identities through startup arguments, environment, or a +mounted activation descriptor. Local runs receive safe generated defaults. +Invalid explicit identities fail startup rather than silently falling back. + +The activation summary is redacted and references, rather than copies, inputs +owned by other contracts: + +```ts +type RuntimeActivationSummary = { + runtimeId: string; + incarnationId: string; + profile: string; + configGeneration?: string; + hostIntegrationGeneration?: string; + restoreGeneration?: string; +}; +``` + +Managed Configuration, Hosted Integration, and Runtime State Continuity own +their generations and evidence. A profile only requires and reports the +resolved references needed for its support posture. + +This is not an OCC instance resource. OCC may supply desired identity and +profile selection, but OpenClaw evaluates the live activation in the runtime +plane. + +### Operator profiles + +An operator profile extends one standard profile and adds required or advisory +condition IDs: + +```json5 +{ + hosting: { + profile: "acme/managed", + profiles: { + "acme/managed": { + extends: "container", + requiredCriteria: ["plugin.storage.backend"], + advisoryCriteria: ["plugin.metrics.exporter"], + }, + }, + }, +} +``` + +V1 operator profiles are additive: + +- exactly one standard profile is inherited; +- inherited required conditions cannot be removed or weakened; +- standard profile IDs and core condition IDs are reserved; +- unknown required provider IDs fail closed; and +- the operator or plugin owner owns the added support promise. + +OpenClaw supports and release-tests the inherited standard baseline. It does +not claim release conformance for operator-added conditions. + +### Host-visible result + +The selected profile appears in the canonical readiness result. For example, a +container selected with a loopback-only listener returns: + +```http +HTTP/1.1 503 Service Unavailable +``` + +```json +{ + "profile": "container", + "ready": false, + "activation": { + "runtimeId": "worker-17", + "incarnationId": "01J..." + }, + "conditions": [ + { + "type": "ContainerStateReady", + "status": "False", + "requirement": "required", + "reason": "ContainerGatewayLoopback", + "message": "The effective Gateway listener is loopback-only." + } + ], + "failures": ["ContainerGatewayLoopback"] +} +``` + +After the listener becomes reachable, the same endpoint returns `200`. Docker, +Kubernetes, systemd, or OCC can consume the ordinary readiness endpoint without +interpreting a profile-specific API. + +### Packaged profile conformance + +A standard profile is a support promise only if the release process tests it. +Conformance produces an immutable record bound to the exact package or image: + +```ts +type HostingProfileConformanceRecord = { + schemaVersion: 1; + artifact: { + openclawVersion: string; + packageIdentity: string; + digest: string; + }; + profile: "local" | "container" | "reverse-proxy" | "node-mode"; + conditionContractVersion: number; + requiredConditionTypes: string[]; + result: "passed" | "failed"; + suiteIdentity: string; + completedAt: string; + provenance?: { + builder?: string; + sourceRevision?: string; + attestationRef?: string; + }; +}; +``` + +Readiness may project artifact identity and matching profile-conformance status, +but it reads packaged metadata; it never reruns release tests. Source and +development runs may report conformance as advisory `Unknown`. + +If a host supplies an immutable expected artifact identity, mismatch is a +required readiness failure. This prevents a different build from satisfying a +deployment's support claim. + +The initial profile matrix must execute package-installed scenarios for: + +- local readiness; +- container success and loopback failure; +- reverse-proxy success and missing-auth failure; +- node-mode unpaired failure and paired/approved recovery; and +- workspace-full failure and recovery without restart. + +Making this matrix release-blocking is a separate governance change after the +profile contract and repeatable packaged proof are accepted. + +### Support ownership and compatibility + +OpenClaw owns: + +- standard profile names and definitions; +- profile-specific condition predicates and reasons; +- selection precedence and result projection; +- activation identity semantics; and +- packaged conformance for the standard catalog. + +Hosts own: + +- which profile to select; +- container and scheduler manifests; +- probe timing, retries, and restart policy; +- placement, routing, tenants, and rollout; +- telemetry sinks and fleet alerts; and +- support for operator-added conditions. + +Adding a required condition, changing a stable reason, or changing an advisory +condition to required can alter host behavior and needs compatibility review, +release notes, and conformance coverage. + +### OCC and AgentHarness alignment + +OCC may compile desired state into OpenClaw config, profile selection, runtime +identity, and host policy. The runtime plane still evaluates readiness and +reports the live activation. + +AgentHarness owns harness execution events. Hosting profiles do not carry +assistant deltas, tool frames, approvals, patches, compaction events, or +harness protocol frames. + +```text +OCC/control plane + -> desired runtime identity and profile + +OpenClaw/runtime plane + -> live activation + -> canonical readiness conditions + -> selected profile result + +AgentHarness/data plane + -> harness execution events +``` + +### Relationship to continuity + +Readiness says whether the current runtime can serve work under its selected +profile. It does not say whether mutable state has been durably published or +whether the runtime is safe to destroy. + +A runtime may be ready but dirty, or not ready while its durable state is +complete. Checkpoint publication, restore compatibility, hibernate, and +generation-fenced safe destruction remain Runtime State Continuity concerns. + +### Implementation plan + +After the readiness-only stack is established, the profile implementation is a +separate series: + +| Slice | Draft PR | Intended scope | +| --- | --- | --- | +| Standard profile selection | [PR 18](https://github.com/giodl73-repo/openclaw/pull/18) | Add selection, `local`, `container`, and `reverse-proxy` compositions and predicates. | +| Node-mode profile | [PR 19](https://github.com/giodl73-repo/openclaw/pull/19) | Add product-neutral node pairing, target, approval, and control-channel conditions. | +| Runtime activation identity | [PR 42](https://github.com/giodl73-repo/openclaw/pull/42) | Attribute profile results to logical runtime and incarnation IDs. | +| Packaged release conformance | [PR 21](https://github.com/giodl73-repo/openclaw/pull/21) | Demonstrate the profile matrix; make it blocking only after acceptance. | + +The existing consolidated implementation remains evidence while these fork PRs +are restacked into independent readiness and profile review series. + +## Rationale + +Named profiles are useful because OpenClaw's configuration space is much larger +than any support matrix. A small standard catalog provides reproducible bug +reports, executable release evidence, and clear responsibility without taking +configuration freedom away from operators. + +Profiles belong in OpenClaw because only the runtime can define the predicates +that mean its Gateway, proxy, node, plugin, and activation state satisfy a +supported posture. Hosts should select and operationalize the posture, not +reverse-engineer its internal readiness semantics. + +Separating this proposal from readiness keeps both decisions honest. OpenClaw +can accept the condition/provider facility without accepting profile product +semantics, and profile review can focus on names, predicates, support ownership, +and release cost rather than debating the underlying readiness API again. + +## Unresolved questions + +- Should `local` be an explicit reported default or should no selection report + an unprofiled runtime until the operator opts in? +- Should operator profiles be part of the first implementation or follow after + the standard catalog proves stable? +- Which activation references are required in V1 beyond runtime and + incarnation identity? +- Should packaged conformance be visible only through status, or also as + advisory conditions in readiness? From 8124da625c3aeb85fe783a02a8eaec2742eb5ef0 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Tue, 14 Jul 2026 08:24:43 -0700 Subject: [PATCH 02/52] Link standard hosting profiles review PR --- rfcs/0023-standard-hosting-profiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 8ef1af2e..7bdb0779 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -6,7 +6,7 @@ created: 2026-07-14 last_updated: 2026-07-14 status: draft issue: -rfc_pr: +rfc_pr: https://github.com/giodl73-repo/rfcs/pull/7 --- # Proposal: Standard Hosting Profiles From e50a02b89223cb2213b9d3ef3b46d2aac73d5bd4 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Tue, 14 Jul 2026 09:42:39 -0700 Subject: [PATCH 03/52] Clarify hosting profile implementation stacks --- rfcs/0023-standard-hosting-profiles.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 7bdb0779..de6936bd 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -338,8 +338,10 @@ The initial profile matrix must execute package-installed scenarios for: - node-mode unpaired failure and paired/approved recovery; and - workspace-full failure and recovery without restart. -Making this matrix release-blocking is a separate governance change after the -profile contract and repeatable packaged proof are accepted. +Making this matrix release-blocking is a governance decision attached to +accepting the profile contract. The draft conformance PR demonstrates the +blocking package-acceptance wiring so reviewers can evaluate the complete +support promise; it should not land ahead of the profile contract. ### Support ownership and compatibility @@ -407,10 +409,11 @@ separate series: | Standard profile selection | [PR 18](https://github.com/giodl73-repo/openclaw/pull/18) | Add selection, `local`, `container`, and `reverse-proxy` compositions and predicates. | | Node-mode profile | [PR 19](https://github.com/giodl73-repo/openclaw/pull/19) | Add product-neutral node pairing, target, approval, and control-channel conditions. | | Runtime activation identity | [PR 42](https://github.com/giodl73-repo/openclaw/pull/42) | Attribute profile results to logical runtime and incarnation IDs. | -| Packaged release conformance | [PR 21](https://github.com/giodl73-repo/openclaw/pull/21) | Demonstrate the profile matrix; make it blocking only after acceptance. | +| Packaged release conformance | [PR 21](https://github.com/giodl73-repo/openclaw/pull/21) | Demonstrate the profile matrix and proposed blocking package-acceptance gate. | -The existing consolidated implementation remains evidence while these fork PRs -are restacked into independent readiness and profile review series. +The fork PRs are now restacked into independent readiness and profile review +series. The existing consolidated implementation remains historical behavior +evidence rather than the proposed landing shape. ## Rationale From 72e9dfa35f59ff63e39abfda9393d99c3214346b Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Tue, 14 Jul 2026 13:41:41 -0700 Subject: [PATCH 04/52] docs(rfc-0023): identify primary implementation --- rfcs/0023-standard-hosting-profiles.md | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index de6936bd..82b163c9 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -402,18 +402,24 @@ generation-fenced safe destruction remain Runtime State Continuity concerns. ### Implementation plan After the readiness-only stack is established, the profile implementation is a -separate series: +single dependent series in +[giodl73-repo/openclaw#94](https://github.com/giodl73-repo/openclaw/pull/94). +It is based on the exact head of the readiness implementation in +[openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) +and contains four profile-only commits: -| Slice | Draft PR | Intended scope | +| Commit | Review slice | Intended scope | | --- | --- | --- | -| Standard profile selection | [PR 18](https://github.com/giodl73-repo/openclaw/pull/18) | Add selection, `local`, `container`, and `reverse-proxy` compositions and predicates. | -| Node-mode profile | [PR 19](https://github.com/giodl73-repo/openclaw/pull/19) | Add product-neutral node pairing, target, approval, and control-channel conditions. | -| Runtime activation identity | [PR 42](https://github.com/giodl73-repo/openclaw/pull/42) | Attribute profile results to logical runtime and incarnation IDs. | -| Packaged release conformance | [PR 21](https://github.com/giodl73-repo/openclaw/pull/21) | Demonstrate the profile matrix and proposed blocking package-acceptance gate. | - -The fork PRs are now restacked into independent readiness and profile review -series. The existing consolidated implementation remains historical behavior -evidence rather than the proposed landing shape. +| `63596d964b7` | [PR 18](https://github.com/giodl73-repo/openclaw/pull/18) | Add selection, `local`, `container`, and `reverse-proxy` compositions and predicates. | +| `a68829096d1` | [PR 19](https://github.com/giodl73-repo/openclaw/pull/19) | Add product-neutral node pairing, target, approval, and control-channel conditions. | +| `11322a977f6` | [PR 42](https://github.com/giodl73-repo/openclaw/pull/42) | Attribute profile results to logical runtime and incarnation IDs. | +| `2f8defb707c` | [PR 21](https://github.com/giodl73-repo/openclaw/pull/21) | Demonstrate the profile matrix and proposed blocking package-acceptance gate. | + +PR 94 is the proposed implementation shape. The four smaller fork PRs expose +the same commits as review aids; they are not alternative landing requests. +The profile implementation remains fork-only until RFC 0018 and its readiness +implementation land. It can then be rebased onto upstream `main` and promoted +as one OpenClaw implementation PR without duplicating readiness commits. ## Rationale From c1b969166927575763c289a88f7082202f0703ac Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Tue, 14 Jul 2026 13:43:23 -0700 Subject: [PATCH 05/52] docs(rfc-0023): link upstream review --- rfcs/0023-standard-hosting-profiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 82b163c9..c99c657d 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -6,7 +6,7 @@ created: 2026-07-14 last_updated: 2026-07-14 status: draft issue: -rfc_pr: https://github.com/giodl73-repo/rfcs/pull/7 +rfc_pr: https://github.com/openclaw/rfcs/pull/37 --- # Proposal: Standard Hosting Profiles From 7a2e052a9571ba26379dadccacf4850849074d75 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Tue, 14 Jul 2026 14:00:37 -0700 Subject: [PATCH 06/52] docs(rfc-0023): link upstream implementation --- rfcs/0023-standard-hosting-profiles.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index c99c657d..a4343089 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -403,7 +403,7 @@ generation-fenced safe destruction remain Runtime State Continuity concerns. After the readiness-only stack is established, the profile implementation is a single dependent series in -[giodl73-repo/openclaw#94](https://github.com/giodl73-repo/openclaw/pull/94). +[openclaw/openclaw#107765](https://github.com/openclaw/openclaw/pull/107765). It is based on the exact head of the readiness implementation in [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) and contains four profile-only commits: @@ -415,11 +415,13 @@ and contains four profile-only commits: | `11322a977f6` | [PR 42](https://github.com/giodl73-repo/openclaw/pull/42) | Attribute profile results to logical runtime and incarnation IDs. | | `2f8defb707c` | [PR 21](https://github.com/giodl73-repo/openclaw/pull/21) | Demonstrate the profile matrix and proposed blocking package-acceptance gate. | -PR 94 is the proposed implementation shape. The four smaller fork PRs expose -the same commits as review aids; they are not alternative landing requests. -The profile implementation remains fork-only until RFC 0018 and its readiness -implementation land. It can then be rebased onto upstream `main` and promoted -as one OpenClaw implementation PR without duplicating readiness commits. +PR 107765 is a stacked upstream draft against `main`. Until PR 104018 lands, +its aggregate GitHub diff includes the readiness dependency followed by the +four profile commits. After PR 104018 lands, the same PR naturally reduces to +the profile-only diff. [Fork PR 94](https://github.com/giodl73-repo/openclaw/pull/94) +preserves that profile-only comparison view in the meantime. The four smaller +fork PRs expose the same profile commits as review aids; they are not +alternative landing requests. ## Rationale From b6acc3f9ac3110d083d30332f352a7f90112e352 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Tue, 14 Jul 2026 20:35:26 -0700 Subject: [PATCH 07/52] docs(rfc-0023): refresh profile implementation --- rfcs/0023-standard-hosting-profiles.md | 36 ++++++++++++++++---------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index a4343089..fa754b91 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -404,24 +404,34 @@ generation-fenced safe destruction remain Runtime State Continuity concerns. After the readiness-only stack is established, the profile implementation is a single dependent series in [openclaw/openclaw#107765](https://github.com/openclaw/openclaw/pull/107765). -It is based on the exact head of the readiness implementation in +It is based on readiness head `89d8607aab9f` from [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -and contains four profile-only commits: - -| Commit | Review slice | Intended scope | -| --- | --- | --- | -| `63596d964b7` | [PR 18](https://github.com/giodl73-repo/openclaw/pull/18) | Add selection, `local`, `container`, and `reverse-proxy` compositions and predicates. | -| `a68829096d1` | [PR 19](https://github.com/giodl73-repo/openclaw/pull/19) | Add product-neutral node pairing, target, approval, and control-channel conditions. | -| `11322a977f6` | [PR 42](https://github.com/giodl73-repo/openclaw/pull/42) | Attribute profile results to logical runtime and incarnation IDs. | -| `2f8defb707c` | [PR 21](https://github.com/giodl73-repo/openclaw/pull/21) | Demonstrate the profile matrix and proposed blocking package-acceptance gate. | +and contains seven profile-only commits: + +| Commit | Intended scope | +| --- | --- | +| `44c0f163489` | Add selection, `local`, `container`, and `reverse-proxy` compositions and predicates. | +| `d1a47217be6` | Add product-neutral node pairing, target, approval, and control-channel conditions. | +| `057ad938451` | Attribute profile results to logical runtime and incarnation IDs. | +| `ee942d3989a` | Demonstrate the profile matrix and proposed blocking package-acceptance gate. | +| `02602feb858` | Validate profile startup inputs before destructive lifecycle actions. | +| `1448fb9c749` | Prove writable host-provisioned workspace behavior and storage recovery. | +| `a416b9b9192` | Prove the existing node approval flow transitions node-mode to ready. | PR 107765 is a stacked upstream draft against `main`. Until PR 104018 lands, its aggregate GitHub diff includes the readiness dependency followed by the -four profile commits. After PR 104018 lands, the same PR naturally reduces to +seven profile commits. After PR 104018 lands, the same PR naturally reduces to the profile-only diff. [Fork PR 94](https://github.com/giodl73-repo/openclaw/pull/94) -preserves that profile-only comparison view in the meantime. The four smaller -fork PRs expose the same profile commits as review aids; they are not -alternative landing requests. +preserves that profile-only comparison view in the meantime. Fork PRs +[#18](https://github.com/giodl73-repo/openclaw/pull/18), +[#19](https://github.com/giodl73-repo/openclaw/pull/19), +[#42](https://github.com/giodl73-repo/openclaw/pull/42), and +[#21](https://github.com/giodl73-repo/openclaw/pull/21) expose the major design +slices as review aids; they are not alternative landing requests. + +The exact-head package-installed Docker matrix passes all four profiles plus +listener, trusted-proxy, node-approval, workspace-full, and recovery cases. +The proof image is `sha256:e87c9e0651d60b6b58262b6ee271f89d0bee060fd2761d0da1525aca60fd6337`. ## Rationale From 3d2739235ae20a4308e3cb94f11f142e27dc6117 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Wed, 15 Jul 2026 07:40:31 -0700 Subject: [PATCH 08/52] docs(rfc-0023): make profile activation opt-in --- rfcs/0023-standard-hosting-profiles.md | 54 ++++++++++++++------------ 1 file changed, 29 insertions(+), 25 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index fa754b91..e1018f14 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -3,7 +3,7 @@ title: Standard Hosting Profiles authors: - Gio created: 2026-07-14 -last_updated: 2026-07-14 +last_updated: 2026-07-15 status: draft issue: rfc_pr: https://github.com/openclaw/rfcs/pull/37 @@ -59,7 +59,8 @@ standard catalog. - Define `local`, `container`, `reverse-proxy`, and `node-mode` as standard OpenClaw support profiles. -- Make selection optional and preserve zero-configuration local behavior. +- Make selection opt-in so an upgrade preserves the existing unprofiled + readiness baseline. - Select profiles through config, environment, or Gateway startup arguments with explicit precedence. - Compose profiles from reusable canonical readiness conditions. @@ -118,7 +119,7 @@ RFC 0023 profile use: | Profile | Runtime posture | Additional required conditions | | --- | --- | --- | -| `local` | Default local or foreground Gateway | Valid effective config, writable workspace, Gateway response, and required activation facts. | +| `local` | Explicit local or foreground Gateway posture | Valid effective config, writable workspace, Gateway response, and required activation facts. | | `container` | Gateway directly reachable through a container listener | `local` plus `ContainerStateReady`. | | `reverse-proxy` | Gateway behind a trusted identity proxy | `local` plus `TrustedProxyReady`. Loopback remains valid for a same-host proxy. | | `node-mode` | Gateway controlling one or more execution targets | `local` plus pairing, connected target, command approval, and control-channel conditions. | @@ -159,8 +160,10 @@ declare when they are required for the supported posture. ### Selection and precedence -Profile selection is optional. When no value is supplied, OpenClaw resolves -`local` so existing installations remain zero-configuration. +Profile selection is optional and opt-in. When no value is supplied, OpenClaw +does not select a profile. Existing installations retain the universal +readiness baseline from RFC 0018 and do not silently acquire profile-specific +required conditions during an upgrade. Selection precedence is: @@ -168,7 +171,6 @@ Selection precedence is: gateway startup argument > OPENCLAW_HOSTING_PROFILE > openclaw.json -> local default ``` Example: @@ -188,10 +190,11 @@ OPENCLAW_HOSTING_PROFILE=container openclaw gateway run openclaw gateway run --hosting-profile container ``` -The effective profile, selection source, and condition result are reported by -readiness, health, and status. Hosts may assert an expected profile when -probing, but expectation is an assertion over the running result, not another -selection source. +When selected, the effective profile, selection source, and condition result +are reported by readiness, health, and status. An unprofiled runtime omits +`ProfileSelected` and profile-only requirements. Hosts may assert an expected +profile when probing, but expectation is an assertion over the running result, +not another selection source. Profiles validate effective runtime state. They do not generate or repair the underlying Gateway, proxy, plugin, model, node, or storage config. @@ -215,7 +218,7 @@ owned by other contracts: type RuntimeActivationSummary = { runtimeId: string; incarnationId: string; - profile: string; + profile?: string; configGeneration?: string; hostIntegrationGeneration?: string; restoreGeneration?: string; @@ -332,7 +335,7 @@ deployment's support claim. The initial profile matrix must execute package-installed scenarios for: -- local readiness; +- unchanged unprofiled readiness and explicit local-profile readiness; - container success and loopback failure; - reverse-proxy success and missing-auth failure; - node-mode unpaired failure and paired/approved recovery; and @@ -404,23 +407,24 @@ generation-fenced safe destruction remain Runtime State Continuity concerns. After the readiness-only stack is established, the profile implementation is a single dependent series in [openclaw/openclaw#107765](https://github.com/openclaw/openclaw/pull/107765). -It is based on readiness head `89d8607aab9f` from +It is based on readiness head `17b34f792d8` from [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -and contains seven profile-only commits: +and contains eight profile-only commits: | Commit | Intended scope | | --- | --- | -| `44c0f163489` | Add selection, `local`, `container`, and `reverse-proxy` compositions and predicates. | -| `d1a47217be6` | Add product-neutral node pairing, target, approval, and control-channel conditions. | -| `057ad938451` | Attribute profile results to logical runtime and incarnation IDs. | -| `ee942d3989a` | Demonstrate the profile matrix and proposed blocking package-acceptance gate. | -| `02602feb858` | Validate profile startup inputs before destructive lifecycle actions. | -| `1448fb9c749` | Prove writable host-provisioned workspace behavior and storage recovery. | -| `a416b9b9192` | Prove the existing node approval flow transitions node-mode to ready. | +| `642bed18093` | Add selection, `local`, `container`, and `reverse-proxy` compositions and predicates. | +| `b9121934a7f` | Add product-neutral node pairing, target, approval, and control-channel conditions. | +| `2b10b218279` | Attribute profile results to logical runtime and incarnation IDs. | +| `81f787820da` | Demonstrate the profile matrix and proposed blocking package-acceptance gate. | +| `05bbe94f8d5` | Validate profile startup inputs before destructive lifecycle actions. | +| `ab612666315` | Prove writable host-provisioned workspace behavior and storage recovery. | +| `630684819c8` | Prove the existing node approval flow transitions node-mode to ready. | +| `f54affa3983` | Make profile activation explicit and prove unprofiled upgrade compatibility. | PR 107765 is a stacked upstream draft against `main`. Until PR 104018 lands, its aggregate GitHub diff includes the readiness dependency followed by the -seven profile commits. After PR 104018 lands, the same PR naturally reduces to +eight profile commits. After PR 104018 lands, the same PR naturally reduces to the profile-only diff. [Fork PR 94](https://github.com/giodl73-repo/openclaw/pull/94) preserves that profile-only comparison view in the meantime. Fork PRs [#18](https://github.com/giodl73-repo/openclaw/pull/18), @@ -431,7 +435,9 @@ slices as review aids; they are not alternative landing requests. The exact-head package-installed Docker matrix passes all four profiles plus listener, trusted-proxy, node-approval, workspace-full, and recovery cases. -The proof image is `sha256:e87c9e0651d60b6b58262b6ee271f89d0bee060fd2761d0da1525aca60fd6337`. +The proof begins with an unprofiled package that remains `200` without +`ProfileSelected` or `WorkspaceWritable`, then exercises each explicit profile. +The proof image is `sha256:20d507b613b346e1165add88234eb00390ea6d1b086970dd3589dd3f41654175`. ## Rationale @@ -452,8 +458,6 @@ and release cost rather than debating the underlying readiness API again. ## Unresolved questions -- Should `local` be an explicit reported default or should no selection report - an unprofiled runtime until the operator opts in? - Should operator profiles be part of the first implementation or follow after the standard catalog proves stable? - Which activation references are required in V1 beyond runtime and From b464a74501019e63d69806258f5e5541b5b842ff Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Wed, 15 Jul 2026 17:09:22 -0700 Subject: [PATCH 09/52] docs(rfc-0023): add hosting profile v1 specification --- rfcs/0023-standard-hosting-profiles.md | 26 +- rfcs/0023/hosting-profile-v1-spec.md | 429 +++++++++++++++++++++++++ 2 files changed, 447 insertions(+), 8 deletions(-) create mode 100644 rfcs/0023/hosting-profile-v1-spec.md diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index e1018f14..beaa2632 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -90,6 +90,12 @@ standard catalog. ## Proposal +The implementer-facing v1 contract is captured in +[`0023/hosting-profile-v1-spec.md`](0023/hosting-profile-v1-spec.md). This RFC +remains the design rationale, support argument, and rollout plan; the sidecar is +the concise profile catalog, selection, activation, extension, projection, and +conformance reference for OpenClaw runtime and release implementations. + ### Dependency on canonical readiness This RFC assumes the contract proposed by Readiness Conditions and Providers: @@ -117,12 +123,12 @@ RFC 0023 profile use: ### Standard profile catalog -| Profile | Runtime posture | Additional required conditions | +| Profile | Runtime posture | Additional required condition types | | --- | --- | --- | -| `local` | Explicit local or foreground Gateway posture | Valid effective config, writable workspace, Gateway response, and required activation facts. | -| `container` | Gateway directly reachable through a container listener | `local` plus `ContainerStateReady`. | -| `reverse-proxy` | Gateway behind a trusted identity proxy | `local` plus `TrustedProxyReady`. Loopback remains valid for a same-host proxy. | -| `node-mode` | Gateway controlling one or more execution targets | `local` plus pairing, connected target, command approval, and control-channel conditions. | +| `local` | Explicit local or foreground Gateway posture | `ProfileSelected`, `RuntimeActivationIdentified`, `WorkspaceWritable` | +| `container` | Gateway directly reachable through a container listener | `local` plus `ContainerStateReady` | +| `reverse-proxy` | Gateway behind a trusted identity proxy | `local` plus `TrustedProxyReady`; loopback remains valid for a same-host proxy | +| `node-mode` | Gateway controlling one or more execution targets | `local` plus `NodePairingReady`, `ControlledTargetsReady`, `CommandApprovalReady`, `ControlChannelReady` | A profile names runtime posture, not packaging. Docker behind an identity proxy selects `reverse-proxy`; Docker with a directly reachable listener selects @@ -143,7 +149,7 @@ contract and existing OpenClaw runtime owners. | `ProfileSelected` | All | Selection precedence resolves to a valid standard or configured operator profile. | Invalid explicit values fail startup validation. | | `RuntimeActivationIdentified` | All | Non-empty logical-runtime and unique-incarnation identities are resolved. | `RuntimeIdentityInvalid`, `IncarnationIdentityInvalid`, `ActivationIdentityUnavailable` | | `ContainerStateReady` | `container` | Effective Gateway mode is local and resolved listener host is not loopback. | `ContainerGatewayRemote`, `ContainerGatewayLoopback`, `ContainerBindNotResolved` | -| `TrustedProxyReady` | `reverse-proxy` | Auth mode is `trusted-proxy`, a user header is configured, and at least one trusted source is present. | `TrustedProxyAuthMissing`, `TrustedProxyHeaderMissing`, `TrustedProxySourcesMissing` | +| `TrustedProxyReady` | `reverse-proxy` | Auth mode is `trusted-proxy`, a user header and trusted source are configured, and active ingress honors asserted identity only from validated trusted sources. | `TrustedProxyAuthMissing`, `TrustedProxyHeaderMissing`, `TrustedProxySourcesMissing`, `TrustedProxyIngressUnsafe` | | `NodePairingReady` | `node-mode` | Pairing state is readable and contains an approved pairing. | `NodePairingUnavailable`, `NodePairingTimedOut`, `NodePairingPending`, `NodePairingMissing` | | `ControlledTargetsReady` | `node-mode` | At least one connected target is correlated to an approved pairing. | `ControlledTargetsDisconnected` | | `CommandApprovalReady` | `node-mode` | A connected paired target advertises a command permitted by effective grants. | `CommandApprovalMissing` | @@ -151,7 +157,9 @@ contract and existing OpenClaw runtime owners. `node-mode` stays product-neutral. A target may be a desktop, sandbox, VM, pod, browser, or another execution surface. OpenClaw does not assume one node maps to -exactly one product or tenant. +exactly one product or tenant. One correlated approved pairing, connected +target, effective command grant, and live session must satisfy all four +conditions; independent targets cannot satisfy different rows. Common runtime conditions such as `ConfigLoaded`, `WorkspaceWritable`, `GatewayResponding`, and conditionally required plugin, secret, or model-route @@ -306,6 +314,7 @@ Conformance produces an immutable record bound to the exact package or image: ```ts type HostingProfileConformanceRecord = { schemaVersion: 1; + profileContractVersion: 1; artifact: { openclawVersion: string; packageIdentity: string; @@ -330,7 +339,8 @@ but it reads packaged metadata; it never reruns release tests. Source and development runs may report conformance as advisory `Unknown`. If a host supplies an immutable expected artifact identity, mismatch is a -required readiness failure. This prevents a different build from satisfying a +required `ArtifactIdentityMatches=False` readiness failure with reason +`ArtifactIdentityMismatch`. This prevents a different build from satisfying a deployment's support claim. The initial profile matrix must execute package-installed scenarios for: diff --git a/rfcs/0023/hosting-profile-v1-spec.md b/rfcs/0023/hosting-profile-v1-spec.md new file mode 100644 index 00000000..b1e4484b --- /dev/null +++ b/rfcs/0023/hosting-profile-v1-spec.md @@ -0,0 +1,429 @@ +# Standard Hosting Profile v1 Specification + +This document is the implementer-facing specification for RFC 0023, Standard +Hosting Profiles. The RFC explains the motivation, support model, and rollout +plan. This file defines the v1 standard profile catalog, condition composition, +selection precedence, activation identity, operator extension, host-visible +result, and packaged conformance contract. + +Status: draft, tied to RFC 0023 and dependent on RFC 0018. + +## Scope + +This specification defines: + +- the `local`, `container`, `reverse-proxy`, and `node-mode` standard profiles; +- composition over canonical readiness criteria from RFC 0018; +- opt-in selection through config, environment, or startup arguments; +- exact profile predicates and stable non-ready reasons; +- logical runtime and unique incarnation identity; +- additive operator profiles; +- readiness, health, and status projection; and +- packaged release conformance records and minimum scenarios. + +This specification does not define: + +- the readiness condition schema or plugin provider API; +- config generation, merge, repair, or policy enforcement; +- scheduler retry intervals, placement, routing, tenants, or rollout; +- OCC resources or the AgentHarness event protocol; +- checkpoint durability or safe destruction; or +- support for arbitrary OpenClaw configurations outside the standard catalog. + +## Dependencies + +This specification requires the canonical condition, aggregation, bounded +evaluation, and projection contract defined by RFC 0018. Profiles are data that +select and classify reusable criteria. They do not define a second evaluator. + +An implementation that has no selected profile remains a valid RFC 0018 +runtime. Selecting a profile adds the contract in this specification. + +## Terminology + +- **Standard profile**: an OpenClaw-owned, named runtime posture with stable + predicates and packaged release conformance. +- **Operator profile**: an operator-owned additive extension of exactly one + standard profile. +- **Universal baseline**: RFC 0018 conditions that apply with or without a + profile. +- **Profile criterion**: a reusable readiness criterion selected by a profile. +- **Logical runtime ID**: identity that may remain stable across process or + container replacement. +- **Incarnation ID**: identity unique to one running process or container + activation. +- **Conformance record**: immutable evidence that one artifact passed one + standard profile contract version. + +## Compatibility And Evolution + +Hosting Profile v1 uses these compatibility rules: + +- profile selection is optional and opt-in; +- an upgrade must not select a profile for an existing unprofiled deployment; +- standard profile IDs, predicates, required condition types and criterion + selectors, and stable reasons are compatibility contracts; +- adding or strengthening a required criterion changes host behavior and + requires compatibility review, release notes, and conformance coverage; +- operator profiles may strengthen but never weaken a standard profile; +- unknown explicit profile values fail startup validation; and +- new standard profiles require a separately reviewable support posture and + release conformance scenario. + +## Standard Profile Catalog + +The v1 standard catalog composes this exact ordered set of additional required +condition types over the RFC 0018 universal baseline: + +| Profile ID | Runtime posture | Additional required condition types, in order | +| --- | --- | --- | +| `local` | Explicit local or foreground Gateway | `ProfileSelected`, `RuntimeActivationIdentified`, `WorkspaceWritable` | +| `container` | Gateway directly reachable through a container listener | `ProfileSelected`, `RuntimeActivationIdentified`, `WorkspaceWritable`, `ContainerStateReady` | +| `reverse-proxy` | Gateway behind a trusted identity proxy | `ProfileSelected`, `RuntimeActivationIdentified`, `WorkspaceWritable`, `TrustedProxyReady` | +| `node-mode` | Gateway controlling one or more paired execution targets | `ProfileSelected`, `RuntimeActivationIdentified`, `WorkspaceWritable`, `NodePairingReady`, `ControlledTargetsReady`, `CommandApprovalReady`, `ControlChannelReady` | + +A profile describes runtime posture, not packaging. A container behind an +identity proxy selects `reverse-proxy`; a container with a directly reachable +listener selects `container`. + +The RFC 0018 universal baseline remains required and cannot be removed, +replaced, or weakened by a profile. + +`WorkspaceWritable` is selected through the RFC 0018 criterion ID +`openclaw.workspace-writable`. The remaining additional condition types are +profile-owned predicates and are not independently operator-selectable in v1. + +## Profile Criteria + +### Profile Selection + +`ProfileSelected` is `True` when selection precedence resolves to a valid +standard or configured operator profile. Invalid explicit values fail startup +validation rather than becoming a running false condition. + +### Runtime Activation Identity + +`RuntimeActivationIdentified` is `True` when both logical runtime and unique +incarnation identities are non-empty and valid. + +Stable non-ready reasons are: + +- `RuntimeIdentityInvalid`; +- `IncarnationIdentityInvalid`; and +- `ActivationIdentityUnavailable`. + +### Host Assertions + +Hosts may assert expected profile and immutable artifact identity. These +conditions follow the standard profile set when configured: + +| Condition type | True when | Stable non-true reasons | +| --- | --- | --- | +| `ProfileExpectationMatches` | The selected profile equals the host assertion. | `ExpectedProfileMismatch`, `ExpectedProfileNotSelected` | +| `ArtifactIdentityMatches` | The running immutable artifact identity equals the host assertion. | `ArtifactIdentityMismatch`, `ArtifactIdentityNotChecked` | + +### Container + +`ContainerStateReady` is `True` when the effective Gateway mode is local and +the resolved listener host is not loopback. + +Stable non-ready reasons are: + +- `ContainerGatewayRemote`; +- `ContainerGatewayLoopback`; and +- `ContainerBindNotResolved`. + +This criterion validates OpenClaw's effective listener state. It does not +inspect Docker, Kubernetes, ECS, Nomad, or another scheduler API. + +### Reverse Proxy + +`TrustedProxyReady` is `True` when: + +- effective auth mode is `trusted-proxy`; +- a user identity header is configured; and +- at least one trusted proxy source is configured; and +- the active Gateway ingress contract accepts asserted identity only from a + validated trusted source and does not honor a client-supplied identity header + on direct or untrusted ingress. + +Stable non-ready reasons are: + +- `TrustedProxyAuthMissing`; +- `TrustedProxyHeaderMissing`; and +- `TrustedProxySourcesMissing`; and +- `TrustedProxyIngressUnsafe`. + +Loopback is valid when a trusted proxy is colocated with the Gateway. + +### Node Mode + +The node-mode profile requires all four criteria below. One correlated approved +pairing, connected target, effective command grant, and live target session must +satisfy the set; independent targets cannot satisfy different rows. + +| Condition type | True when | Stable non-ready reasons | +| --- | --- | --- | +| `NodePairingReady` | Pairing state is readable and contains an approved pairing. | `NodePairingUnavailable`, `NodePairingTimedOut`, `NodePairingPending`, `NodePairingMissing` | +| `ControlledTargetsReady` | At least one connected target correlates to an approved pairing. | `ControlledTargetsDisconnected` | +| `CommandApprovalReady` | A connected paired target advertises a command permitted by effective grants. | `CommandApprovalMissing` | +| `ControlChannelReady` | At least one live target session correlates to an approved pairing. | `ControlChannelUnavailable` | + +A target may be a desktop, sandbox, VM, pod, browser, or another execution +surface. The profile does not impose product, tenant, or one-target-per-agent +semantics. Evaluation consumes a bounded activation snapshot; readiness polling +must not scan unbounded pairing or session stores. + +## Selection And Precedence + +Selection sources use this precedence: + +```text +gateway startup argument +> OPENCLAW_HOSTING_PROFILE +> openclaw.json +``` + +Configuration example: + +```json5 +{ + hosting: { + profile: "container", + }, +} +``` + +Equivalent startup selection: + +```bash +OPENCLAW_HOSTING_PROFILE=container openclaw gateway run +openclaw gateway run --hosting-profile container +``` + +An absent value means unprofiled operation; it must not imply `local`. Every +supplied value is validated, then the highest-precedence valid source wins. +Different valid lower-precedence values are ordinary overrides and do not fail +startup. Empty, malformed, or unknown explicit values fail validation before +destructive lifecycle actions. + +The effective result records the profile and winning selection source. A probe +may assert an expected profile, but that assertion does not select or mutate the +running profile. When supplied, mismatch or absence emits required +`ProfileExpectationMatches=False` with reason `ExpectedProfileMismatch` or +`ExpectedProfileNotSelected`. + +Profiles validate effective runtime state. They do not generate or repair the +underlying Gateway, proxy, plugin, model, node, or storage configuration. + +## Runtime Activation Identity + +Every profiled result is attributable to one activation: + +```ts +type RuntimeActivationSummary = { + runtimeId: string; + incarnationId: string; + profile: string; + configGeneration?: string; + hostIntegrationGeneration?: string; + restoreGeneration?: string; +}; +``` + +Launchers may provide identity through startup arguments, environment, or a +mounted activation descriptor. Local runs may receive generated defaults. +Explicit invalid identity must fail startup instead of silently falling back. + +The activation summary is redacted. Generation values reference contracts +owned by Managed Configuration, Hosted Integration, and Runtime State +Continuity; the profile does not copy their evidence or redefine their meaning. + +Logical runtime identity may survive replacement. Incarnation identity must be +unique for each process/container activation. OCC may supply these values, but +the OpenClaw runtime plane evaluates and reports the live activation. + +## Operator Profiles + +An operator profile extends exactly one standard profile and adds canonical +criterion IDs: + +```json5 +{ + hosting: { + profile: "acme/managed", + profiles: { + "acme/managed": { + extends: "container", + requiredCriteria: ["plugin.storage.backend"], + advisoryCriteria: ["plugin.metrics.exporter"], + }, + }, + }, +} +``` + +V1 operator profiles follow these rules: + +- `extends` names exactly one standard profile; +- required and advisory lists use RFC 0018 namespaced criterion IDs; +- inherited required conditions cannot be removed or weakened; +- the same ID cannot appear in both lists; +- standard profile IDs and core criterion IDs are reserved; +- unknown required provider IDs fail closed; and +- the operator or plugin owner owns added support semantics. + +OpenClaw release conformance covers the inherited standard baseline, not +operator additions. V1 does not permit operator-profile inheritance chains. + +## Host-Visible Result + +The canonical readiness result may add these optional v1 profile fields: + +```ts +type ProfiledReadinessResult = ReadinessResult & { + profileContractVersion: 1; + profile: string; + profileSource: "argument" | "environment" | "config"; + activation: RuntimeActivationSummary; + conformance?: HostingProfileConformanceSummary; +}; +``` + +For example, a selected container profile with a loopback-only listener returns +`503` and includes: + +```json +{ + "profileContractVersion": 1, + "profile": "container", + "profileSource": "config", + "ready": false, + "activation": { + "runtimeId": "worker-17", + "incarnationId": "01J...", + "profile": "container" + }, + "conditions": [ + { + "type": "ContainerStateReady", + "status": "False", + "requirement": "required", + "reason": "ContainerGatewayLoopback", + "message": "The effective Gateway listener is loopback-only." + } + ], + "failures": ["ContainerGatewayLoopback"], + "advisories": [] +} +``` + +After the listener satisfies the predicate, the same readiness endpoint returns +`200`. Hosts consume the canonical endpoint and do not need a profile-specific +probe API. + +Unauthenticated remote projections may redact profile source, activation, and +condition detail while preserving the correct status code. + +## Packaged Conformance + +A standard profile is an OpenClaw support promise only when the release process +tests the exact packaged artifact. The v1 record is: + +```ts +type HostingProfileConformanceRecord = { + schemaVersion: 1; + profileContractVersion: 1; + artifact: { + openclawVersion: string; + packageIdentity: string; + digest: string; + }; + profile: "local" | "container" | "reverse-proxy" | "node-mode"; + conditionContractVersion: number; + requiredConditionTypes: string[]; + result: "passed" | "failed"; + suiteIdentity: string; + completedAt: string; + provenance?: { + builder?: string; + sourceRevision?: string; + attestationRef?: string; + }; +}; + +type HostingProfileConformanceSummary = { + artifactDigest?: string; + profileContractVersion: number; + profile: string; + result: "passed" | "failed" | "unknown"; + conditionContractVersion?: number; +}; +``` + +Runtime readiness may read and project packaged conformance metadata. It must +not rerun release tests. Source and development runs may report conformance as +advisory `Unknown`. The record is release evidence, not by itself a security +attestation. A distribution that makes an authenticated provenance claim must +publish and verify a signed attestation referenced by `attestationRef`. + +If a host supplies an immutable expected artifact identity, a mismatch is a +required `ArtifactIdentityMatches=False` condition with reason +`ArtifactIdentityMismatch`; unavailable verification is required `Unknown` +with reason `ArtifactIdentityNotChecked`. The expectation must not be satisfied +by mutable version text alone. + +### Minimum V1 Matrix + +The packaged matrix must prove: + +- unchanged unprofiled readiness after upgrade; +- explicit `local` success and writable-workspace failure/recovery; +- `container` success and loopback-listener failure; +- `reverse-proxy` success, missing-auth failure, direct-ingress rejection, and + forged identity-header rejection; +- `node-mode` unpaired failure, wrong-target correlation failure, and + paired/approved recovery; +- activation identity presence and incarnation replacement; and +- exact profile condition sets, profile contract version, and expected-artifact + mismatch behavior; and +- agreement among `/ready`, `/readyz`, health, status, and any readiness CLI. + +Records must bind the exact artifact digest, profile ID, profile contract +version, condition contract version, required criterion set, suite identity, +completion time, and available build provenance. + +## Ownership + +OpenClaw owns: + +- standard profile IDs and definitions; +- profile-specific predicates and stable reasons; +- selection precedence and projection; +- activation identity semantics; and +- packaged conformance for the standard catalog. + +Hosts own: + +- profile selection; +- container and scheduler manifests; +- probe timing, retries, and restart policy; +- placement, routing, tenants, and rollout; +- telemetry sinks and fleet alerts; and +- support for operator-added criteria. + +## Conformance Checklist + +An implementation conforms to Hosting Profile v1 when it proves: + +- no profile is selected by default or by upgrade; +- each selection source works and precedence is deterministic; +- invalid explicit profile or identity fails startup validation; +- every standard profile composes the exact documented criteria; +- operator profiles are additive and cannot weaken their standard parent; +- profiled results identify logical runtime and unique incarnation; +- profile failures use stable reasons and canonical readiness aggregation; +- all host-visible surfaces describe the same activation and profile result; +- packaged evidence binds an immutable artifact and contract version; and +- unprofiled deployments retain RFC 0018 behavior without profile-only + conditions. From 6d2117892f743d6e15bd09e0bc7a763830c2d343 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Wed, 22 Jul 2026 18:19:49 -0700 Subject: [PATCH 10/52] docs(rfc): refresh hosting profiles implementation --- rfcs/0023-standard-hosting-profiles.md | 35 ++++++++++++++------------ 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index beaa2632..e09ca97f 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -417,24 +417,25 @@ generation-fenced safe destruction remain Runtime State Continuity concerns. After the readiness-only stack is established, the profile implementation is a single dependent series in [openclaw/openclaw#107765](https://github.com/openclaw/openclaw/pull/107765). -It is based on readiness head `17b34f792d8` from +It is based on readiness head `d1450aeb7f9` from [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -and contains eight profile-only commits: +and contains nine profile-only commits at exact head `e53d0d7dbfb`: | Commit | Intended scope | | --- | --- | -| `642bed18093` | Add selection, `local`, `container`, and `reverse-proxy` compositions and predicates. | -| `b9121934a7f` | Add product-neutral node pairing, target, approval, and control-channel conditions. | -| `2b10b218279` | Attribute profile results to logical runtime and incarnation IDs. | -| `81f787820da` | Demonstrate the profile matrix and proposed blocking package-acceptance gate. | -| `05bbe94f8d5` | Validate profile startup inputs before destructive lifecycle actions. | -| `ab612666315` | Prove writable host-provisioned workspace behavior and storage recovery. | -| `630684819c8` | Prove the existing node approval flow transitions node-mode to ready. | -| `f54affa3983` | Make profile activation explicit and prove unprofiled upgrade compatibility. | +| `773f55479f2` | Add selection, `local`, `container`, and `reverse-proxy` compositions and predicates. | +| `49b2d1600b3` | Add product-neutral node pairing, target, approval, and control-channel conditions. | +| `cc190ebc9bb` | Attribute profile results to logical runtime and incarnation IDs. | +| `bddc10acecd` | Demonstrate the profile matrix and proposed blocking package-acceptance gate. | +| `823d532cc55` | Validate profile startup inputs before destructive lifecycle actions. | +| `2ab70849ddb` | Prove writable host-provisioned workspace behavior and storage recovery. | +| `6f887976e8a` | Prove the existing node approval flow transitions node-mode to ready. | +| `3fb44ece8a0` | Make profile activation explicit and prove unprofiled upgrade compatibility. | +| `e53d0d7dbfb` | Document profile selection, predicates, host inputs, and support boundaries. | PR 107765 is a stacked upstream draft against `main`. Until PR 104018 lands, its aggregate GitHub diff includes the readiness dependency followed by the -eight profile commits. After PR 104018 lands, the same PR naturally reduces to +nine profile commits. After PR 104018 lands, the same PR naturally reduces to the profile-only diff. [Fork PR 94](https://github.com/giodl73-repo/openclaw/pull/94) preserves that profile-only comparison view in the meantime. Fork PRs [#18](https://github.com/giodl73-repo/openclaw/pull/18), @@ -443,11 +444,13 @@ preserves that profile-only comparison view in the meantime. Fork PRs [#21](https://github.com/giodl73-repo/openclaw/pull/21) expose the major design slices as review aids; they are not alternative landing requests. -The exact-head package-installed Docker matrix passes all four profiles plus -listener, trusted-proxy, node-approval, workspace-full, and recovery cases. -The proof begins with an unprofiled package that remains `200` without -`ProfileSelected` or `WorkspaceWritable`, then exercises each explicit profile. -The proof image is `sha256:20d507b613b346e1165add88234eb00390ea6d1b086970dd3589dd3f41654175`. +The refreshed stack passes 206 focused profile, Gateway, config, CLI, Docker-plan, +and release-wiring assertions; formatting and documentation indexing also pass. +A prior package-installed Docker matrix proved all four profiles plus listener, +trusted-proxy, node-approval, workspace-full, recovery, and unprofiled `200` +compatibility using image +`sha256:20d507b613b346e1165add88234eb00390ea6d1b086970dd3589dd3f41654175`. +Exact-head remote container proof must be refreshed before landing. ## Rationale From e49f619a5e4b0b7d533d750ce7df420fd7419084 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Wed, 22 Jul 2026 19:49:05 -0700 Subject: [PATCH 11/52] docs(rfc-0023): refresh implementation stack --- rfcs/0023-standard-hosting-profiles.md | 32 +++++++++++++++----------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index e09ca97f..0021e80c 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -417,21 +417,23 @@ generation-fenced safe destruction remain Runtime State Continuity concerns. After the readiness-only stack is established, the profile implementation is a single dependent series in [openclaw/openclaw#107765](https://github.com/openclaw/openclaw/pull/107765). -It is based on readiness head `d1450aeb7f9` from +It is based on readiness head `208dc2db604` from [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -and contains nine profile-only commits at exact head `e53d0d7dbfb`: +and contains eleven profile-only commits at exact head `41475969aec`: | Commit | Intended scope | | --- | --- | -| `773f55479f2` | Add selection, `local`, `container`, and `reverse-proxy` compositions and predicates. | -| `49b2d1600b3` | Add product-neutral node pairing, target, approval, and control-channel conditions. | -| `cc190ebc9bb` | Attribute profile results to logical runtime and incarnation IDs. | -| `bddc10acecd` | Demonstrate the profile matrix and proposed blocking package-acceptance gate. | -| `823d532cc55` | Validate profile startup inputs before destructive lifecycle actions. | -| `2ab70849ddb` | Prove writable host-provisioned workspace behavior and storage recovery. | -| `6f887976e8a` | Prove the existing node approval flow transitions node-mode to ready. | -| `3fb44ece8a0` | Make profile activation explicit and prove unprofiled upgrade compatibility. | -| `e53d0d7dbfb` | Document profile selection, predicates, host inputs, and support boundaries. | +| `d16b060e1be` | Add selection, `local`, `container`, and `reverse-proxy` compositions and predicates. | +| `cdb6bce28d1` | Add product-neutral node pairing, target, approval, and control-channel conditions. | +| `5fd9d831670` | Attribute profile results to logical runtime and incarnation IDs. | +| `bd4506e1009` | Demonstrate the profile matrix and proposed blocking package-acceptance gate. | +| `b4df03c8527` | Validate profile startup inputs before destructive lifecycle actions. | +| `fa3b5255a97` | Prove writable host-provisioned workspace behavior and storage recovery. | +| `5708f009c58` | Prove the existing node approval flow transitions node-mode to ready. | +| `a9a6c3a113` | Make profile activation explicit and prove unprofiled upgrade compatibility. | +| `c144faccbfa` | Document profile selection, predicates, host inputs, and support boundaries. | +| `c93b48bd9ab` | Align profile criteria and current repository contracts with the readiness stack. | +| `41475969aec` | Preserve optional-profile startup while applying profile-required criteria. | PR 107765 is a stacked upstream draft against `main`. Until PR 104018 lands, its aggregate GitHub diff includes the readiness dependency followed by the @@ -444,9 +446,11 @@ preserves that profile-only comparison view in the meantime. Fork PRs [#21](https://github.com/giodl73-repo/openclaw/pull/21) expose the major design slices as review aids; they are not alternative landing requests. -The refreshed stack passes 206 focused profile, Gateway, config, CLI, Docker-plan, -and release-wiring assertions; formatting and documentation indexing also pass. -A prior package-installed Docker matrix proved all four profiles plus listener, +The refreshed stack passes 204 focused profile, Gateway, config, CLI, +Docker-plan, and release-wiring assertions. Production typing, dead-export and +deprecation guards, changed-file lint, plugin-SDK surface checks, line-count +ratchets, and documentation indexing also pass. A prior package-installed +Docker matrix proved all four profiles plus listener, trusted-proxy, node-approval, workspace-full, recovery, and unprofiled `200` compatibility using image `sha256:20d507b613b346e1165add88234eb00390ea6d1b086970dd3589dd3f41654175`. From 3916d7cbedee1c73d4dab564c4dccf1cd81ab7cf Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Wed, 22 Jul 2026 19:58:49 -0700 Subject: [PATCH 12/52] docs(rfc-0023): record refreshed profile head --- rfcs/0023-standard-hosting-profiles.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 0021e80c..1843ba97 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -419,7 +419,7 @@ single dependent series in [openclaw/openclaw#107765](https://github.com/openclaw/openclaw/pull/107765). It is based on readiness head `208dc2db604` from [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -and contains eleven profile-only commits at exact head `41475969aec`: +and contains twelve profile-only commits at exact head `6d02550698f`: | Commit | Intended scope | | --- | --- | @@ -434,6 +434,7 @@ and contains eleven profile-only commits at exact head `41475969aec`: | `c144faccbfa` | Document profile selection, predicates, host inputs, and support boundaries. | | `c93b48bd9ab` | Align profile criteria and current repository contracts with the readiness stack. | | `41475969aec` | Preserve optional-profile startup while applying profile-required criteria. | +| `6d02550698f` | Satisfy current config-tier, import-cycle, and generated-protocol contracts. | PR 107765 is a stacked upstream draft against `main`. Until PR 104018 lands, its aggregate GitHub diff includes the readiness dependency followed by the From 639ff05b46fdb5ca53a1370e48e2ea62fd845c73 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Wed, 22 Jul 2026 20:15:22 -0700 Subject: [PATCH 13/52] docs(rfc-0023): restack on resilient readiness --- rfcs/0023-standard-hosting-profiles.md | 30 +++++++++++++------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 1843ba97..8bc5aa57 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -417,24 +417,24 @@ generation-fenced safe destruction remain Runtime State Continuity concerns. After the readiness-only stack is established, the profile implementation is a single dependent series in [openclaw/openclaw#107765](https://github.com/openclaw/openclaw/pull/107765). -It is based on readiness head `208dc2db604` from +It is based on readiness head `21cbc1bcf6c` from [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -and contains twelve profile-only commits at exact head `6d02550698f`: +and contains twelve profile-only commits at exact head `ac8e64e46f6`: | Commit | Intended scope | | --- | --- | -| `d16b060e1be` | Add selection, `local`, `container`, and `reverse-proxy` compositions and predicates. | -| `cdb6bce28d1` | Add product-neutral node pairing, target, approval, and control-channel conditions. | -| `5fd9d831670` | Attribute profile results to logical runtime and incarnation IDs. | -| `bd4506e1009` | Demonstrate the profile matrix and proposed blocking package-acceptance gate. | -| `b4df03c8527` | Validate profile startup inputs before destructive lifecycle actions. | -| `fa3b5255a97` | Prove writable host-provisioned workspace behavior and storage recovery. | -| `5708f009c58` | Prove the existing node approval flow transitions node-mode to ready. | -| `a9a6c3a113` | Make profile activation explicit and prove unprofiled upgrade compatibility. | -| `c144faccbfa` | Document profile selection, predicates, host inputs, and support boundaries. | -| `c93b48bd9ab` | Align profile criteria and current repository contracts with the readiness stack. | -| `41475969aec` | Preserve optional-profile startup while applying profile-required criteria. | -| `6d02550698f` | Satisfy current config-tier, import-cycle, and generated-protocol contracts. | +| `993e2e36640` | Add selection, `local`, `container`, and `reverse-proxy` compositions and predicates. | +| `f381eaf03fb` | Add product-neutral node pairing, target, approval, and control-channel conditions. | +| `3a4619bcc7c` | Attribute profile results to logical runtime and incarnation IDs. | +| `eda9ba49b6b` | Demonstrate the profile matrix and proposed blocking package-acceptance gate. | +| `4197676d67f` | Validate profile startup inputs before destructive lifecycle actions. | +| `19b416be648` | Prove writable host-provisioned workspace behavior and storage recovery. | +| `0954eb586c2` | Prove the existing node approval flow transitions node-mode to ready. | +| `0da071cc44b` | Make profile activation explicit and prove unprofiled upgrade compatibility. | +| `274c09a9bd8` | Document profile selection, predicates, host inputs, and support boundaries. | +| `44fb70aefc6` | Align profile criteria and current repository contracts with the readiness stack. | +| `5f854eb2a76` | Preserve optional-profile startup while applying profile-required criteria. | +| `ac8e64e46f6` | Satisfy current config-tier, import-cycle, and generated-protocol contracts. | PR 107765 is a stacked upstream draft against `main`. Until PR 104018 lands, its aggregate GitHub diff includes the readiness dependency followed by the @@ -447,7 +447,7 @@ preserves that profile-only comparison view in the meantime. Fork PRs [#21](https://github.com/giodl73-repo/openclaw/pull/21) expose the major design slices as review aids; they are not alternative landing requests. -The refreshed stack passes 204 focused profile, Gateway, config, CLI, +The refreshed stack passes 205 focused profile, Gateway, config, CLI, Docker-plan, and release-wiring assertions. Production typing, dead-export and deprecation guards, changed-file lint, plugin-SDK surface checks, line-count ratchets, and documentation indexing also pass. A prior package-installed From eb297f9fb7285f6f1e82b717891e768100ce0339 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Wed, 22 Jul 2026 20:20:37 -0700 Subject: [PATCH 14/52] docs(rfc-0023): record canonical node policy --- rfcs/0023-standard-hosting-profiles.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 8bc5aa57..efdd1584 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -419,7 +419,7 @@ single dependent series in [openclaw/openclaw#107765](https://github.com/openclaw/openclaw/pull/107765). It is based on readiness head `21cbc1bcf6c` from [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -and contains twelve profile-only commits at exact head `ac8e64e46f6`: +and contains thirteen profile-only commits at exact head `92eef761d99`: | Commit | Intended scope | | --- | --- | @@ -435,6 +435,7 @@ and contains twelve profile-only commits at exact head `ac8e64e46f6`: | `44fb70aefc6` | Align profile criteria and current repository contracts with the readiness stack. | | `5f854eb2a76` | Preserve optional-profile startup while applying profile-required criteria. | | `ac8e64e46f6` | Satisfy current config-tier, import-cycle, and generated-protocol contracts. | +| `92eef761d99` | Evaluate node-mode approval against the canonical node command policy. | PR 107765 is a stacked upstream draft against `main`. Until PR 104018 lands, its aggregate GitHub diff includes the readiness dependency followed by the @@ -447,7 +448,7 @@ preserves that profile-only comparison view in the meantime. Fork PRs [#21](https://github.com/giodl73-repo/openclaw/pull/21) expose the major design slices as review aids; they are not alternative landing requests. -The refreshed stack passes 205 focused profile, Gateway, config, CLI, +The refreshed stack passes 206 focused profile, Gateway, config, CLI, Docker-plan, and release-wiring assertions. Production typing, dead-export and deprecation guards, changed-file lint, plugin-SDK surface checks, line-count ratchets, and documentation indexing also pass. A prior package-installed From c0e00125288a963d7a1f913fb9fa8cbc72762e94 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Wed, 22 Jul 2026 20:25:12 -0700 Subject: [PATCH 15/52] docs(rfc-0023): record final restack --- rfcs/0023-standard-hosting-profiles.md | 30 +++++++++++++------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index efdd1584..884707a6 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -417,25 +417,25 @@ generation-fenced safe destruction remain Runtime State Continuity concerns. After the readiness-only stack is established, the profile implementation is a single dependent series in [openclaw/openclaw#107765](https://github.com/openclaw/openclaw/pull/107765). -It is based on readiness head `21cbc1bcf6c` from +It is based on readiness head `27fa73911d5` from [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -and contains thirteen profile-only commits at exact head `92eef761d99`: +and contains thirteen profile-only commits at exact head `963ce437219`: | Commit | Intended scope | | --- | --- | -| `993e2e36640` | Add selection, `local`, `container`, and `reverse-proxy` compositions and predicates. | -| `f381eaf03fb` | Add product-neutral node pairing, target, approval, and control-channel conditions. | -| `3a4619bcc7c` | Attribute profile results to logical runtime and incarnation IDs. | -| `eda9ba49b6b` | Demonstrate the profile matrix and proposed blocking package-acceptance gate. | -| `4197676d67f` | Validate profile startup inputs before destructive lifecycle actions. | -| `19b416be648` | Prove writable host-provisioned workspace behavior and storage recovery. | -| `0954eb586c2` | Prove the existing node approval flow transitions node-mode to ready. | -| `0da071cc44b` | Make profile activation explicit and prove unprofiled upgrade compatibility. | -| `274c09a9bd8` | Document profile selection, predicates, host inputs, and support boundaries. | -| `44fb70aefc6` | Align profile criteria and current repository contracts with the readiness stack. | -| `5f854eb2a76` | Preserve optional-profile startup while applying profile-required criteria. | -| `ac8e64e46f6` | Satisfy current config-tier, import-cycle, and generated-protocol contracts. | -| `92eef761d99` | Evaluate node-mode approval against the canonical node command policy. | +| `f3a6e854eee` | Add selection, `local`, `container`, and `reverse-proxy` compositions and predicates. | +| `25a7a5a61a9` | Add product-neutral node pairing, target, approval, and control-channel conditions. | +| `2bd38eaa76a` | Attribute profile results to logical runtime and incarnation IDs. | +| `aff71e14531` | Demonstrate the profile matrix and proposed blocking package-acceptance gate. | +| `d7867a2ae4b` | Validate profile startup inputs before destructive lifecycle actions. | +| `02d0073f5a6` | Prove writable host-provisioned workspace behavior and storage recovery. | +| `44f64a55545` | Prove the existing node approval flow transitions node-mode to ready. | +| `c0bb2fc92c1` | Make profile activation explicit and prove unprofiled upgrade compatibility. | +| `98e983d7c51` | Document profile selection, predicates, host inputs, and support boundaries. | +| `4bc6273391c` | Align profile criteria and current repository contracts with the readiness stack. | +| `76d93e38dcc` | Preserve optional-profile startup while applying profile-required criteria. | +| `4e9ddc6c2f1` | Satisfy current config-tier and import-cycle contracts. | +| `963ce437219` | Evaluate node-mode approval against the canonical node command policy. | PR 107765 is a stacked upstream draft against `main`. Until PR 104018 lands, its aggregate GitHub diff includes the readiness dependency followed by the From a0520117713e66271f244bbc432f3e903ad7ab5d Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Wed, 22 Jul 2026 20:33:30 -0700 Subject: [PATCH 16/52] docs(rfc-0023): refresh stacked implementation --- rfcs/0023-standard-hosting-profiles.md | 32 +++++++++++++------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 884707a6..b0ac0c25 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -417,29 +417,29 @@ generation-fenced safe destruction remain Runtime State Continuity concerns. After the readiness-only stack is established, the profile implementation is a single dependent series in [openclaw/openclaw#107765](https://github.com/openclaw/openclaw/pull/107765). -It is based on readiness head `27fa73911d5` from +It is based on readiness head `5e7a713545a` from [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -and contains thirteen profile-only commits at exact head `963ce437219`: +and contains thirteen profile-only commits at exact head `2336ee23999`: | Commit | Intended scope | | --- | --- | -| `f3a6e854eee` | Add selection, `local`, `container`, and `reverse-proxy` compositions and predicates. | -| `25a7a5a61a9` | Add product-neutral node pairing, target, approval, and control-channel conditions. | -| `2bd38eaa76a` | Attribute profile results to logical runtime and incarnation IDs. | -| `aff71e14531` | Demonstrate the profile matrix and proposed blocking package-acceptance gate. | -| `d7867a2ae4b` | Validate profile startup inputs before destructive lifecycle actions. | -| `02d0073f5a6` | Prove writable host-provisioned workspace behavior and storage recovery. | -| `44f64a55545` | Prove the existing node approval flow transitions node-mode to ready. | -| `c0bb2fc92c1` | Make profile activation explicit and prove unprofiled upgrade compatibility. | -| `98e983d7c51` | Document profile selection, predicates, host inputs, and support boundaries. | -| `4bc6273391c` | Align profile criteria and current repository contracts with the readiness stack. | -| `76d93e38dcc` | Preserve optional-profile startup while applying profile-required criteria. | -| `4e9ddc6c2f1` | Satisfy current config-tier and import-cycle contracts. | -| `963ce437219` | Evaluate node-mode approval against the canonical node command policy. | +| `1fa9428ebb8` | Add selection, `local`, `container`, and `reverse-proxy` compositions and predicates. | +| `32ebc761b1e` | Add product-neutral node pairing, target, approval, and control-channel conditions. | +| `ca4da0b3bfe` | Attribute profile results to logical runtime and incarnation IDs. | +| `ae634a05432` | Demonstrate the profile matrix and proposed blocking package-acceptance gate. | +| `388a894443a` | Validate profile startup inputs before destructive lifecycle actions. | +| `6265a75912c` | Prove writable host-provisioned workspace behavior and storage recovery. | +| `1048b52e937` | Prove the existing node approval flow transitions node-mode to ready. | +| `9ccaec363e4` | Make profile activation explicit and prove unprofiled upgrade compatibility. | +| `8681995fd94` | Document profile selection, predicates, host inputs, and support boundaries. | +| `f51a723ed36` | Align profile criteria and current repository contracts with the readiness stack. | +| `079f28e7a69` | Preserve optional-profile startup while applying profile-required criteria. | +| `bdef0fb3c2d` | Satisfy current config-tier and import-cycle contracts. | +| `2336ee23999` | Evaluate node-mode approval against the canonical node command policy. | PR 107765 is a stacked upstream draft against `main`. Until PR 104018 lands, its aggregate GitHub diff includes the readiness dependency followed by the -nine profile commits. After PR 104018 lands, the same PR naturally reduces to +thirteen profile commits. After PR 104018 lands, the same PR naturally reduces to the profile-only diff. [Fork PR 94](https://github.com/giodl73-repo/openclaw/pull/94) preserves that profile-only comparison view in the meantime. Fork PRs [#18](https://github.com/giodl73-repo/openclaw/pull/18), From 984cbfdbcce83a7312220226c212f05c8a442d2a Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Thu, 23 Jul 2026 08:29:01 -0700 Subject: [PATCH 17/52] docs(rfc-0023): narrow the v1 profile contract --- rfcs/0023-standard-hosting-profiles.md | 185 +++++++------------- rfcs/0023/hosting-profile-v1-spec.md | 226 ++++++++----------------- 2 files changed, 126 insertions(+), 285 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index b0ac0c25..3cdf9117 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -3,7 +3,7 @@ title: Standard Hosting Profiles authors: - Gio created: 2026-07-14 -last_updated: 2026-07-15 +last_updated: 2026-07-23 status: draft issue: rfc_pr: https://github.com/openclaw/rfcs/pull/37 @@ -16,8 +16,8 @@ rfc_pr: https://github.com/openclaw/rfcs/pull/37 Define a small catalog of named, release-tested OpenClaw runtime postures: `local`, `container`, `reverse-proxy`, and `node-mode`. A selected profile composes canonical readiness conditions into a support contract, identifies the -runtime activation being evaluated, and can be validated against packaged -release evidence. +runtime activation being evaluated, and has a matching packaged release +scenario. This RFC depends on the separate Readiness Conditions and Providers RFC. That RFC is directly usable: operators may explicitly select additional required or @@ -68,9 +68,7 @@ standard catalog. - Report the selected profile through readiness, health, and status. - Identify the logical runtime and unique process/container incarnation whose profile result is being reported. -- Let operator profiles extend, but never weaken, a standard profile. -- Bind packaged conformance evidence to an immutable OpenClaw artifact and - profile contract version. +- Exercise every standard profile through a packaged release scenario lane. - Keep host orchestration and OpenClaw runtime ownership separate. ## Non-Goals @@ -87,14 +85,16 @@ standard catalog. - Guarantee checkpoint durability, restore compatibility, or safe destruction. - Claim that every possible OpenClaw configuration belongs to a standard profile. +- Define named operator profiles, inheritance, host assertions, immutable + conformance records, or signed artifact attestations in V1. ## Proposal The implementer-facing v1 contract is captured in [`0023/hosting-profile-v1-spec.md`](0023/hosting-profile-v1-spec.md). This RFC remains the design rationale, support argument, and rollout plan; the sidecar is -the concise profile catalog, selection, activation, extension, projection, and -conformance reference for OpenClaw runtime and release implementations. +the concise profile catalog, selection, activation, projection, and packaged +scenario reference for OpenClaw runtime and release implementations. ### Dependency on canonical readiness @@ -117,8 +117,8 @@ RFC 0018 direct use: universal conditions + operator-selected criteria -> readiness RFC 0023 profile use: - universal conditions + standard profile preset + operator additions - -> readiness + OpenClaw support/conformance claim + universal conditions + standard profile preset + optional RFC 0018 additions + -> readiness + an OpenClaw-tested support posture ``` ### Standard profile catalog @@ -127,7 +127,7 @@ RFC 0023 profile use: | --- | --- | --- | | `local` | Explicit local or foreground Gateway posture | `ProfileSelected`, `RuntimeActivationIdentified`, `WorkspaceWritable` | | `container` | Gateway directly reachable through a container listener | `local` plus `ContainerStateReady` | -| `reverse-proxy` | Gateway behind a trusted identity proxy | `local` plus `TrustedProxyReady`; loopback remains valid for a same-host proxy | +| `reverse-proxy` | Gateway behind a trusted identity proxy | `local` plus `TrustedProxyReady`; loopback requires the explicit trusted-proxy loopback allowance | | `node-mode` | Gateway controlling one or more execution targets | `local` plus `NodePairingReady`, `ControlledTargetsReady`, `CommandApprovalReady`, `ControlChannelReady` | A profile names runtime posture, not packaging. Docker behind an identity proxy @@ -146,10 +146,10 @@ contract and existing OpenClaw runtime owners. | Condition | Profile | True when | Stable non-ready reasons | | --- | --- | --- | --- | -| `ProfileSelected` | All | Selection precedence resolves to a valid standard or configured operator profile. | Invalid explicit values fail startup validation. | -| `RuntimeActivationIdentified` | All | Non-empty logical-runtime and unique-incarnation identities are resolved. | `RuntimeIdentityInvalid`, `IncarnationIdentityInvalid`, `ActivationIdentityUnavailable` | -| `ContainerStateReady` | `container` | Effective Gateway mode is local and resolved listener host is not loopback. | `ContainerGatewayRemote`, `ContainerGatewayLoopback`, `ContainerBindNotResolved` | -| `TrustedProxyReady` | `reverse-proxy` | Auth mode is `trusted-proxy`, a user header and trusted source are configured, and active ingress honors asserted identity only from validated trusted sources. | `TrustedProxyAuthMissing`, `TrustedProxyHeaderMissing`, `TrustedProxySourcesMissing`, `TrustedProxyIngressUnsafe` | +| `ProfileSelected` | All | Selection precedence resolves to a valid standard profile. | Invalid explicit values fail startup validation. | +| `RuntimeActivationIdentified` | All | Non-empty logical-runtime and unique-incarnation identities are resolved. | Invalid explicit values fail startup validation. | +| `ContainerStateReady` | `container` | The resolved listener host is not loopback. | `ContainerGatewayLoopback` | +| `TrustedProxyReady` | `reverse-proxy` | Auth mode is `trusted-proxy`, a user header and trusted source are configured, and loopback sources are explicitly allowed. | `TrustedProxyAuthMissing`, `TrustedProxyHeaderMissing`, `TrustedProxySourcesMissing`, `TrustedProxyIngressUnsafe` | | `NodePairingReady` | `node-mode` | Pairing state is readable and contains an approved pairing. | `NodePairingUnavailable`, `NodePairingTimedOut`, `NodePairingPending`, `NodePairingMissing` | | `ControlledTargetsReady` | `node-mode` | At least one connected target is correlated to an approved pairing. | `ControlledTargetsDisconnected` | | `CommandApprovalReady` | `node-mode` | A connected paired target advertises a command permitted by effective grants. | `CommandApprovalMissing` | @@ -161,6 +161,10 @@ exactly one product or tenant. One correlated approved pairing, connected target, effective command grant, and live session must satisfy all four conditions; independent targets cannot satisfy different rows. +`TrustedProxyReady` validates the effective auth configuration. Existing +Gateway request handling remains responsible for rejecting forged or untrusted +identity ingress; readiness does not issue a synthetic request on every poll. + Common runtime conditions such as `ConfigLoaded`, `WorkspaceWritable`, `GatewayResponding`, and conditionally required plugin, secret, or model-route activation remain owned by readiness and their source subsystems. Profiles only @@ -200,9 +204,8 @@ openclaw gateway run --hosting-profile container When selected, the effective profile, selection source, and condition result are reported by readiness, health, and status. An unprofiled runtime omits -`ProfileSelected` and profile-only requirements. Hosts may assert an expected -profile when probing, but expectation is an assertion over the running result, -not another selection source. +`ProfileSelected`, activation identity, top-level profile fields, and +profile-only requirements. Profiles validate effective runtime state. They do not generate or repair the underlying Gateway, proxy, plugin, model, node, or storage config. @@ -215,8 +218,8 @@ resolves: - a logical runtime ID that may remain stable across process replacement; and - a unique incarnation ID for the current process/container activation. -Launchers may provide identities through startup arguments, environment, or a -mounted activation descriptor. Local runs receive safe generated defaults. +Launchers may provide identities through startup arguments or environment. +Local runs receive safe generated defaults. Invalid explicit identities fail startup rather than silently falling back. The activation summary is redacted and references, rather than copies, inputs @@ -226,51 +229,21 @@ owned by other contracts: type RuntimeActivationSummary = { runtimeId: string; incarnationId: string; - profile?: string; - configGeneration?: string; - hostIntegrationGeneration?: string; - restoreGeneration?: string; + profile: string; }; ``` -Managed Configuration, Hosted Integration, and Runtime State Continuity own -their generations and evidence. A profile only requires and reports the -resolved references needed for its support posture. - This is not an OCC instance resource. OCC may supply desired identity and profile selection, but OpenClaw evaluates the live activation in the runtime plane. -### Operator profiles - -An operator profile extends one standard profile and adds required or advisory -condition IDs: - -```json5 -{ - hosting: { - profile: "acme/managed", - profiles: { - "acme/managed": { - extends: "container", - requiredCriteria: ["plugin.storage.backend"], - advisoryCriteria: ["plugin.metrics.exporter"], - }, - }, - }, -} -``` - -V1 operator profiles are additive: - -- exactly one standard profile is inherited; -- inherited required conditions cannot be removed or weakened; -- standard profile IDs and core condition IDs are reserved; -- unknown required provider IDs fail closed; and -- the operator or plugin owner owns the added support promise. +### Operator extensions -OpenClaw supports and release-tests the inherited standard baseline. It does -not claim release conformance for operator-added conditions. +V1 supports only the four OpenClaw-owned standard profile names. Operators may +select additional required or advisory criteria through RFC 0018's +`gateway.readiness` config, including while a profile is selected. Named +operator profiles and inheritance are possible follow-up work, not an implied +V1 contract. ### Host-visible result @@ -283,11 +256,14 @@ HTTP/1.1 503 Service Unavailable ```json { + "profileContractVersion": 1, "profile": "container", + "profileSource": "config", "ready": false, "activation": { "runtimeId": "worker-17", - "incarnationId": "01J..." + "incarnationId": "01J...", + "profile": "container" }, "conditions": [ { @@ -306,42 +282,12 @@ After the listener becomes reachable, the same endpoint returns `200`. Docker, Kubernetes, systemd, or OCC can consume the ordinary readiness endpoint without interpreting a profile-specific API. -### Packaged profile conformance +### Packaged profile scenarios A standard profile is a support promise only if the release process tests it. -Conformance produces an immutable record bound to the exact package or image: - -```ts -type HostingProfileConformanceRecord = { - schemaVersion: 1; - profileContractVersion: 1; - artifact: { - openclawVersion: string; - packageIdentity: string; - digest: string; - }; - profile: "local" | "container" | "reverse-proxy" | "node-mode"; - conditionContractVersion: number; - requiredConditionTypes: string[]; - result: "passed" | "failed"; - suiteIdentity: string; - completedAt: string; - provenance?: { - builder?: string; - sourceRevision?: string; - attestationRef?: string; - }; -}; -``` - -Readiness may project artifact identity and matching profile-conformance status, -but it reads packaged metadata; it never reruns release tests. Source and -development runs may report conformance as advisory `Unknown`. - -If a host supplies an immutable expected artifact identity, mismatch is a -required `ArtifactIdentityMatches=False` readiness failure with reason -`ArtifactIdentityMismatch`. This prevents a different build from satisfying a -deployment's support claim. +V1 adds one Docker E2E lane to the release-check matrix. It starts the packaged +OpenClaw entrypoint and validates the ordinary canonical `/readyz` result; +runtime readiness does not rerun release tests or claim artifact attestation. The initial profile matrix must execute package-installed scenarios for: @@ -351,10 +297,10 @@ The initial profile matrix must execute package-installed scenarios for: - node-mode unpaired failure and paired/approved recovery; and - workspace-full failure and recovery without restart. -Making this matrix release-blocking is a governance decision attached to -accepting the profile contract. The draft conformance PR demonstrates the -blocking package-acceptance wiring so reviewers can evaluate the complete -support promise; it should not land ahead of the profile contract. +The implementation wires this lane into package acceptance. Upgrade survival, +cross-surface parity, direct-ingress security scenarios, immutable records, and +signed attestations can strengthen the support program later without expanding +the V1 runtime contract. ### Support ownership and compatibility @@ -364,7 +310,7 @@ OpenClaw owns: - profile-specific condition predicates and reasons; - selection precedence and result projection; - activation identity semantics; and -- packaged conformance for the standard catalog. +- the packaged scenario lane for the standard catalog. Hosts own: @@ -373,7 +319,7 @@ Hosts own: - probe timing, retries, and restart policy; - placement, routing, tenants, and rollout; - telemetry sinks and fleet alerts; and -- support for operator-added conditions. +- any additional operator-selected RFC 0018 criteria. Adding a required condition, changing a stable reason, or changing an advisory condition to required can alter host behavior and needs compatibility review, @@ -417,29 +363,20 @@ generation-fenced safe destruction remain Runtime State Continuity concerns. After the readiness-only stack is established, the profile implementation is a single dependent series in [openclaw/openclaw#107765](https://github.com/openclaw/openclaw/pull/107765). -It is based on readiness head `5e7a713545a` from +It is based on readiness head `788a58e612f` from [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -and contains thirteen profile-only commits at exact head `2336ee23999`: +and contains fifteen profile-only commits at exact head `9392d02b452`. -| Commit | Intended scope | +| Slice | Intended scope | | --- | --- | -| `1fa9428ebb8` | Add selection, `local`, `container`, and `reverse-proxy` compositions and predicates. | -| `32ebc761b1e` | Add product-neutral node pairing, target, approval, and control-channel conditions. | -| `ca4da0b3bfe` | Attribute profile results to logical runtime and incarnation IDs. | -| `ae634a05432` | Demonstrate the profile matrix and proposed blocking package-acceptance gate. | -| `388a894443a` | Validate profile startup inputs before destructive lifecycle actions. | -| `6265a75912c` | Prove writable host-provisioned workspace behavior and storage recovery. | -| `1048b52e937` | Prove the existing node approval flow transitions node-mode to ready. | -| `9ccaec363e4` | Make profile activation explicit and prove unprofiled upgrade compatibility. | -| `8681995fd94` | Document profile selection, predicates, host inputs, and support boundaries. | -| `f51a723ed36` | Align profile criteria and current repository contracts with the readiness stack. | -| `079f28e7a69` | Preserve optional-profile startup while applying profile-required criteria. | -| `bdef0fb3c2d` | Satisfy current config-tier and import-cycle contracts. | -| `2336ee23999` | Evaluate node-mode approval against the canonical node command policy. | +| Standard selection and predicates | Add opt-in selection, precedence, machine-readable projection, and `local`, `container`, and `reverse-proxy` conditions. | +| Node mode | Add product-neutral pairing, connected-target, canonical command-policy, and control-channel conditions. | +| Compatibility and safety | Keep unprofiled startup unchanged, validate profile-only identity only when selected, and bound profile evaluation. | +| Packaged scenarios | Exercise all four profiles, primary failures, node approval, workspace-full recovery, and unprofiled compatibility. | PR 107765 is a stacked upstream draft against `main`. Until PR 104018 lands, its aggregate GitHub diff includes the readiness dependency followed by the -thirteen profile commits. After PR 104018 lands, the same PR naturally reduces to +fifteen profile commits. After PR 104018 lands, the same PR naturally reduces to the profile-only diff. [Fork PR 94](https://github.com/giodl73-repo/openclaw/pull/94) preserves that profile-only comparison view in the meantime. Fork PRs [#18](https://github.com/giodl73-repo/openclaw/pull/18), @@ -448,10 +385,8 @@ preserves that profile-only comparison view in the meantime. Fork PRs [#21](https://github.com/giodl73-repo/openclaw/pull/21) expose the major design slices as review aids; they are not alternative landing requests. -The refreshed stack passes 206 focused profile, Gateway, config, CLI, -Docker-plan, and release-wiring assertions. Production typing, dead-export and -deprecation guards, changed-file lint, plugin-SDK surface checks, line-count -ratchets, and documentation indexing also pass. A prior package-installed +The refreshed stack passes 156 focused profile, Gateway, config, and CLI +assertions, production typing, and protocol generation/compatibility checks. A prior package-installed Docker matrix proved all four profiles plus listener, trusted-proxy, node-approval, workspace-full, recovery, and unprofiled `200` compatibility using image @@ -477,9 +412,9 @@ and release cost rather than debating the underlying readiness API again. ## Unresolved questions -- Should operator profiles be part of the first implementation or follow after - the standard catalog proves stable? -- Which activation references are required in V1 beyond runtime and - incarnation identity? -- Should packaged conformance be visible only through status, or also as - advisory conditions in readiness? +- Is `hosting.profile` the preferred config home for the opt-in standard + catalog? +- Should the packaged scenario lane be release-blocking immediately or begin as + an advisory release check? +- After the standard catalog proves stable, is there enough demand for named + operator profiles beyond direct RFC 0018 criterion selection? diff --git a/rfcs/0023/hosting-profile-v1-spec.md b/rfcs/0023/hosting-profile-v1-spec.md index b1e4484b..2328f82c 100644 --- a/rfcs/0023/hosting-profile-v1-spec.md +++ b/rfcs/0023/hosting-profile-v1-spec.md @@ -3,8 +3,8 @@ This document is the implementer-facing specification for RFC 0023, Standard Hosting Profiles. The RFC explains the motivation, support model, and rollout plan. This file defines the v1 standard profile catalog, condition composition, -selection precedence, activation identity, operator extension, host-visible -result, and packaged conformance contract. +selection precedence, activation identity, host-visible result, and packaged +scenario gate. Status: draft, tied to RFC 0023 and dependent on RFC 0018. @@ -17,9 +17,8 @@ This specification defines: - opt-in selection through config, environment, or startup arguments; - exact profile predicates and stable non-ready reasons; - logical runtime and unique incarnation identity; -- additive operator profiles; - readiness, health, and status projection; and -- packaged release conformance records and minimum scenarios. +- a packaged release scenario lane for the standard catalog. This specification does not define: @@ -28,6 +27,8 @@ This specification does not define: - scheduler retry intervals, placement, routing, tenants, or rollout; - OCC resources or the AgentHarness event protocol; - checkpoint durability or safe destruction; or +- operator-defined profiles, profile inheritance, host assertions, artifact + identity, or signed conformance records; or - support for arbitrary OpenClaw configurations outside the standard catalog. ## Dependencies @@ -42,9 +43,7 @@ runtime. Selecting a profile adds the contract in this specification. ## Terminology - **Standard profile**: an OpenClaw-owned, named runtime posture with stable - predicates and packaged release conformance. -- **Operator profile**: an operator-owned additive extension of exactly one - standard profile. + predicates and packaged release scenarios. - **Universal baseline**: RFC 0018 conditions that apply with or without a profile. - **Profile criterion**: a reusable readiness criterion selected by a profile. @@ -52,8 +51,6 @@ runtime. Selecting a profile adds the contract in this specification. container replacement. - **Incarnation ID**: identity unique to one running process or container activation. -- **Conformance record**: immutable evidence that one artifact passed one - standard profile contract version. ## Compatibility And Evolution @@ -65,22 +62,21 @@ Hosting Profile v1 uses these compatibility rules: selectors, and stable reasons are compatibility contracts; - adding or strengthening a required criterion changes host behavior and requires compatibility review, release notes, and conformance coverage; -- operator profiles may strengthen but never weaken a standard profile; - unknown explicit profile values fail startup validation; and - new standard profiles require a separately reviewable support posture and release conformance scenario. ## Standard Profile Catalog -The v1 standard catalog composes this exact ordered set of additional required -condition types over the RFC 0018 universal baseline: +The v1 standard catalog requires these conditions over the RFC 0018 universal +baseline: -| Profile ID | Runtime posture | Additional required condition types, in order | +| Profile ID | Runtime posture | Required profile criteria | | --- | --- | --- | -| `local` | Explicit local or foreground Gateway | `ProfileSelected`, `RuntimeActivationIdentified`, `WorkspaceWritable` | -| `container` | Gateway directly reachable through a container listener | `ProfileSelected`, `RuntimeActivationIdentified`, `WorkspaceWritable`, `ContainerStateReady` | -| `reverse-proxy` | Gateway behind a trusted identity proxy | `ProfileSelected`, `RuntimeActivationIdentified`, `WorkspaceWritable`, `TrustedProxyReady` | -| `node-mode` | Gateway controlling one or more paired execution targets | `ProfileSelected`, `RuntimeActivationIdentified`, `WorkspaceWritable`, `NodePairingReady`, `ControlledTargetsReady`, `CommandApprovalReady`, `ControlChannelReady` | +| `local` | Explicit local or foreground Gateway | `WorkspaceWritable`, `ProfileSelected`, `RuntimeActivationIdentified` | +| `container` | Gateway directly reachable through a container listener | `local` plus `ContainerStateReady` | +| `reverse-proxy` | Gateway behind a trusted identity proxy | `local` plus `TrustedProxyReady` | +| `node-mode` | Gateway controlling one or more paired execution targets | `local` plus `NodePairingReady`, `ControlledTargetsReady`, `CommandApprovalReady`, `ControlChannelReady` | A profile describes runtime posture, not packaging. A container behind an identity proxy selects `reverse-proxy`; a container with a directly reachable @@ -93,45 +89,34 @@ replaced, or weakened by a profile. `openclaw.workspace-writable`. The remaining additional condition types are profile-owned predicates and are not independently operator-selectable in v1. +Canonical condition ordering remains owned by RFC 0018: `ConfigLoaded` and +`WorkspaceWritable` precede `ProfileSelected`, `RuntimeActivationIdentified`, +and the profile-specific conditions listed above; `GatewayResponding` and +`PluginsLoaded` follow them. + ## Profile Criteria ### Profile Selection `ProfileSelected` is `True` when selection precedence resolves to a valid -standard or configured operator profile. Invalid explicit values fail startup -validation rather than becoming a running false condition. +standard profile. Invalid explicit values fail startup validation rather than +becoming a running false condition. ### Runtime Activation Identity `RuntimeActivationIdentified` is `True` when both logical runtime and unique incarnation identities are non-empty and valid. -Stable non-ready reasons are: - -- `RuntimeIdentityInvalid`; -- `IncarnationIdentityInvalid`; and -- `ActivationIdentityUnavailable`. - -### Host Assertions - -Hosts may assert expected profile and immutable artifact identity. These -conditions follow the standard profile set when configured: - -| Condition type | True when | Stable non-true reasons | -| --- | --- | --- | -| `ProfileExpectationMatches` | The selected profile equals the host assertion. | `ExpectedProfileMismatch`, `ExpectedProfileNotSelected` | -| `ArtifactIdentityMatches` | The running immutable artifact identity equals the host assertion. | `ArtifactIdentityMismatch`, `ArtifactIdentityNotChecked` | +Invalid explicit values fail startup validation, so V1 does not emit a running +non-ready activation condition. ### Container -`ContainerStateReady` is `True` when the effective Gateway mode is local and -the resolved listener host is not loopback. +`ContainerStateReady` is `True` when the resolved listener host is not loopback. Stable non-ready reasons are: -- `ContainerGatewayRemote`; -- `ContainerGatewayLoopback`; and -- `ContainerBindNotResolved`. +- `ContainerGatewayLoopback`. This criterion validates OpenClaw's effective listener state. It does not inspect Docker, Kubernetes, ECS, Nomad, or another scheduler API. @@ -143,18 +128,20 @@ inspect Docker, Kubernetes, ECS, Nomad, or another scheduler API. - effective auth mode is `trusted-proxy`; - a user identity header is configured; and - at least one trusted proxy source is configured; and -- the active Gateway ingress contract accepts asserted identity only from a - validated trusted source and does not honor a client-supplied identity header - on direct or untrusted ingress. +- when that source includes loopback, the explicit trusted-proxy loopback + allowance is enabled. Stable non-ready reasons are: - `TrustedProxyAuthMissing`; -- `TrustedProxyHeaderMissing`; and +- `TrustedProxyHeaderMissing`; - `TrustedProxySourcesMissing`; and - `TrustedProxyIngressUnsafe`. -Loopback is valid when a trusted proxy is colocated with the Gateway. +This readiness condition validates the effective auth configuration. Existing +Gateway trusted-proxy request handling remains responsible for rejecting +untrusted or forged identity ingress; readiness does not replay a request on +every poll. Loopback is valid only when a colocated proxy is explicitly allowed. ### Node Mode @@ -171,8 +158,9 @@ satisfy the set; independent targets cannot satisfy different rows. A target may be a desktop, sandbox, VM, pod, browser, or another execution surface. The profile does not impose product, tenant, or one-target-per-agent -semantics. Evaluation consumes a bounded activation snapshot; readiness polling -must not scan unbounded pairing or session stores. +semantics. Evaluation is bounded by the canonical readiness deadline and uses +the current pairing and connected-session state; it does not perform network +discovery or wait for a target during a readiness poll. ## Selection And Precedence @@ -201,17 +189,12 @@ OPENCLAW_HOSTING_PROFILE=container openclaw gateway run openclaw gateway run --hosting-profile container ``` -An absent value means unprofiled operation; it must not imply `local`. Every -supplied value is validated, then the highest-precedence valid source wins. -Different valid lower-precedence values are ordinary overrides and do not fail -startup. Empty, malformed, or unknown explicit values fail validation before -destructive lifecycle actions. +An absent value means unprofiled operation; it must not imply `local`. The +highest-precedence supplied source is validated and wins; shadowed +lower-precedence values are not evaluated. An empty, malformed, or unknown +winning value fails validation before destructive lifecycle actions. -The effective result records the profile and winning selection source. A probe -may assert an expected profile, but that assertion does not select or mutate the -running profile. When supplied, mismatch or absence emits required -`ProfileExpectationMatches=False` with reason `ExpectedProfileMismatch` or -`ExpectedProfileNotSelected`. +The effective result records the profile and winning selection source. Profiles validate effective runtime state. They do not generate or repair the underlying Gateway, proxy, plugin, model, node, or storage configuration. @@ -225,56 +208,24 @@ type RuntimeActivationSummary = { runtimeId: string; incarnationId: string; profile: string; - configGeneration?: string; - hostIntegrationGeneration?: string; - restoreGeneration?: string; }; ``` -Launchers may provide identity through startup arguments, environment, or a -mounted activation descriptor. Local runs may receive generated defaults. +Launchers may provide identity through startup arguments or environment. Local +runs may receive generated defaults. Explicit invalid identity must fail startup instead of silently falling back. -The activation summary is redacted. Generation values reference contracts -owned by Managed Configuration, Hosted Integration, and Runtime State -Continuity; the profile does not copy their evidence or redefine their meaning. - Logical runtime identity may survive replacement. Incarnation identity must be unique for each process/container activation. OCC may supply these values, but the OpenClaw runtime plane evaluates and reports the live activation. -## Operator Profiles +## Operator Extensions -An operator profile extends exactly one standard profile and adds canonical -criterion IDs: - -```json5 -{ - hosting: { - profile: "acme/managed", - profiles: { - "acme/managed": { - extends: "container", - requiredCriteria: ["plugin.storage.backend"], - advisoryCriteria: ["plugin.metrics.exporter"], - }, - }, - }, -} -``` - -V1 operator profiles follow these rules: - -- `extends` names exactly one standard profile; -- required and advisory lists use RFC 0018 namespaced criterion IDs; -- inherited required conditions cannot be removed or weakened; -- the same ID cannot appear in both lists; -- standard profile IDs and core criterion IDs are reserved; -- unknown required provider IDs fail closed; and -- the operator or plugin owner owns added support semantics. - -OpenClaw release conformance covers the inherited standard baseline, not -operator additions. V1 does not permit operator-profile inheritance chains. +V1 supports only the four OpenClaw-owned standard profile names. Operators may +add required or advisory RFC 0018 criteria directly through +`gateway.readiness`, including while a standard profile is selected. Named +operator profiles and inheritance may be proposed later; they are not part of +this contract and cannot be inferred from arbitrary config. ## Host-Visible Result @@ -286,7 +237,6 @@ type ProfiledReadinessResult = ReadinessResult & { profile: string; profileSource: "argument" | "environment" | "config"; activation: RuntimeActivationSummary; - conformance?: HostingProfileConformanceSummary; }; ``` @@ -325,73 +275,29 @@ probe API. Unauthenticated remote projections may redact profile source, activation, and condition detail while preserving the correct status code. -## Packaged Conformance - -A standard profile is an OpenClaw support promise only when the release process -tests the exact packaged artifact. The v1 record is: - -```ts -type HostingProfileConformanceRecord = { - schemaVersion: 1; - profileContractVersion: 1; - artifact: { - openclawVersion: string; - packageIdentity: string; - digest: string; - }; - profile: "local" | "container" | "reverse-proxy" | "node-mode"; - conditionContractVersion: number; - requiredConditionTypes: string[]; - result: "passed" | "failed"; - suiteIdentity: string; - completedAt: string; - provenance?: { - builder?: string; - sourceRevision?: string; - attestationRef?: string; - }; -}; - -type HostingProfileConformanceSummary = { - artifactDigest?: string; - profileContractVersion: number; - profile: string; - result: "passed" | "failed" | "unknown"; - conditionContractVersion?: number; -}; -``` - -Runtime readiness may read and project packaged conformance metadata. It must -not rerun release tests. Source and development runs may report conformance as -advisory `Unknown`. The record is release evidence, not by itself a security -attestation. A distribution that makes an authenticated provenance claim must -publish and verify a signed attestation referenced by `attestationRef`. +## Packaged Scenario Gate -If a host supplies an immutable expected artifact identity, a mismatch is a -required `ArtifactIdentityMatches=False` condition with reason -`ArtifactIdentityMismatch`; unavailable verification is required `Unknown` -with reason `ArtifactIdentityNotChecked`. The expectation must not be satisfied -by mutable version text alone. +A standard profile is a credible support promise only when the packaged +release path exercises it. V1 adds one Docker E2E lane to the release-check +matrix. The lane starts the packaged OpenClaw entrypoint and probes the same +canonical `/readyz` result used by hosts; runtime readiness does not rerun the +release tests or claim artifact attestation. ### Minimum V1 Matrix The packaged matrix must prove: -- unchanged unprofiled readiness after upgrade; +- unchanged unprofiled readiness; - explicit `local` success and writable-workspace failure/recovery; - `container` success and loopback-listener failure; -- `reverse-proxy` success, missing-auth failure, direct-ingress rejection, and - forged identity-header rejection; -- `node-mode` unpaired failure, wrong-target correlation failure, and - paired/approved recovery; -- activation identity presence and incarnation replacement; and -- exact profile condition sets, profile contract version, and expected-artifact - mismatch behavior; and -- agreement among `/ready`, `/readyz`, health, status, and any readiness CLI. - -Records must bind the exact artifact digest, profile ID, profile contract -version, condition contract version, required criterion set, suite identity, -completion time, and available build provenance. +- `reverse-proxy` success and missing-auth failure; +- `node-mode` unpaired/unapproved failure and paired/approved recovery; +- activation identity and machine-readable profile fields; and +- exact profile condition status and profile contract version on `/readyz`. + +Upgrade survival, direct-ingress security tests, cross-surface parity, immutable +artifact records, and signed attestations are valuable follow-up gates, not V1 +runtime semantics. ## Ownership @@ -401,7 +307,7 @@ OpenClaw owns: - profile-specific predicates and stable reasons; - selection precedence and projection; - activation identity semantics; and -- packaged conformance for the standard catalog. +- the packaged scenario lane for the standard catalog. Hosts own: @@ -410,7 +316,7 @@ Hosts own: - probe timing, retries, and restart policy; - placement, routing, tenants, and rollout; - telemetry sinks and fleet alerts; and -- support for operator-added criteria. +- any additional operator-selected RFC 0018 criteria. ## Conformance Checklist @@ -420,10 +326,10 @@ An implementation conforms to Hosting Profile v1 when it proves: - each selection source works and precedence is deterministic; - invalid explicit profile or identity fails startup validation; - every standard profile composes the exact documented criteria; -- operator profiles are additive and cannot weaken their standard parent; - profiled results identify logical runtime and unique incarnation; - profile failures use stable reasons and canonical readiness aggregation; - all host-visible surfaces describe the same activation and profile result; -- packaged evidence binds an immutable artifact and contract version; and +- the packaged scenario lane exercises every standard profile and its primary + failure/recovery path; and - unprofiled deployments retain RFC 0018 behavior without profile-only conditions. From f9b768cbf0a5df8a909a910c59af53c8706c7063 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Thu, 23 Jul 2026 08:30:11 -0700 Subject: [PATCH 18/52] docs(rfc-0023): refresh implementation head --- rfcs/0023-standard-hosting-profiles.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 3cdf9117..81ec5d36 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -363,9 +363,9 @@ generation-fenced safe destruction remain Runtime State Continuity concerns. After the readiness-only stack is established, the profile implementation is a single dependent series in [openclaw/openclaw#107765](https://github.com/openclaw/openclaw/pull/107765). -It is based on readiness head `788a58e612f` from +It is based on readiness head `a8e61ac0691` from [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -and contains fifteen profile-only commits at exact head `9392d02b452`. +and contains fifteen profile-only commits at exact head `218fff215e4`. | Slice | Intended scope | | --- | --- | From 1dd104ed3dbb641f83b0cc924b1aeb40ceb37b10 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Thu, 23 Jul 2026 09:17:04 -0700 Subject: [PATCH 19/52] docs(rfc-0023): harden profile observations --- rfcs/0023-standard-hosting-profiles.md | 6 +++--- rfcs/0023/hosting-profile-v1-spec.md | 13 +++++++++---- 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 81ec5d36..666b6a84 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -363,9 +363,9 @@ generation-fenced safe destruction remain Runtime State Continuity concerns. After the readiness-only stack is established, the profile implementation is a single dependent series in [openclaw/openclaw#107765](https://github.com/openclaw/openclaw/pull/107765). -It is based on readiness head `a8e61ac0691` from +It is based on readiness head `813104950f5` from [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -and contains fifteen profile-only commits at exact head `218fff215e4`. +and contains seventeen profile-only commits at exact head `d191c89203e`. | Slice | Intended scope | | --- | --- | @@ -376,7 +376,7 @@ and contains fifteen profile-only commits at exact head `218fff215e4`. PR 107765 is a stacked upstream draft against `main`. Until PR 104018 lands, its aggregate GitHub diff includes the readiness dependency followed by the -fifteen profile commits. After PR 104018 lands, the same PR naturally reduces to +seventeen profile commits. After PR 104018 lands, the same PR naturally reduces to the profile-only diff. [Fork PR 94](https://github.com/giodl73-repo/openclaw/pull/94) preserves that profile-only comparison view in the meantime. Fork PRs [#18](https://github.com/giodl73-repo/openclaw/pull/18), diff --git a/rfcs/0023/hosting-profile-v1-spec.md b/rfcs/0023/hosting-profile-v1-spec.md index 2328f82c..019ebee4 100644 --- a/rfcs/0023/hosting-profile-v1-spec.md +++ b/rfcs/0023/hosting-profile-v1-spec.md @@ -127,7 +127,8 @@ inspect Docker, Kubernetes, ECS, Nomad, or another scheduler API. - effective auth mode is `trusted-proxy`; - a user identity header is configured; and -- at least one trusted proxy source is configured; and +- at least one syntactically valid trusted proxy source is configured; and +- a loopback-only listener has a loopback trusted proxy source; and - when that source includes loopback, the explicit trusted-proxy loopback allowance is enabled. @@ -141,7 +142,9 @@ Stable non-ready reasons are: This readiness condition validates the effective auth configuration. Existing Gateway trusted-proxy request handling remains responsible for rejecting untrusted or forged identity ingress; readiness does not replay a request on -every poll. Loopback is valid only when a colocated proxy is explicitly allowed. +every poll. Source syntax and listener/source compatibility use the same network +matching semantics as request authentication. Loopback is valid only when a +colocated proxy is explicitly allowed. ### Node Mode @@ -159,8 +162,10 @@ satisfy the set; independent targets cannot satisfy different rows. A target may be a desktop, sandbox, VM, pod, browser, or another execution surface. The profile does not impose product, tenant, or one-target-per-agent semantics. Evaluation is bounded by the canonical readiness deadline and uses -the current pairing and connected-session state; it does not perform network -discovery or wait for a target during a readiness poll. +the current pairing generation and pairing-bound connected-session state; it +does not perform network discovery or wait for a target during a readiness poll. +Pairing-store reads remain single-flight after timeout, and store exceptions are +projected as stable redacted reasons rather than raw error text. ## Selection And Precedence From dac4c80a1f2037177fab79365d96278f1f93fabf Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Thu, 23 Jul 2026 09:53:24 -0700 Subject: [PATCH 20/52] docs(rfc-0023): clarify activation defaults --- rfcs/0023-standard-hosting-profiles.md | 3 ++- rfcs/0023/hosting-profile-v1-spec.md | 5 +++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 666b6a84..1244e897 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -219,7 +219,8 @@ resolves: - a unique incarnation ID for the current process/container activation. Launchers may provide identities through startup arguments or environment. -Local runs receive safe generated defaults. +Absent values receive runtime-owned defaults: the logical runtime ID is +`local`, and the incarnation ID is unique to the current process activation. Invalid explicit identities fail startup rather than silently falling back. The activation summary is redacted and references, rather than copies, inputs diff --git a/rfcs/0023/hosting-profile-v1-spec.md b/rfcs/0023/hosting-profile-v1-spec.md index 019ebee4..6ff93e2b 100644 --- a/rfcs/0023/hosting-profile-v1-spec.md +++ b/rfcs/0023/hosting-profile-v1-spec.md @@ -216,8 +216,9 @@ type RuntimeActivationSummary = { }; ``` -Launchers may provide identity through startup arguments or environment. Local -runs may receive generated defaults. +Launchers may provide identity through startup arguments or environment. +Absent values receive runtime-owned defaults: the logical runtime ID is +`local`, and the incarnation ID is unique to the current process activation. Explicit invalid identity must fail startup instead of silently falling back. Logical runtime identity may survive replacement. Incarnation identity must be From c84d0664297ae0e80022a2c5753039e680ef4abd Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Thu, 23 Jul 2026 10:03:33 -0700 Subject: [PATCH 21/52] docs(rfc-0023): refresh implementation stack --- rfcs/0023-standard-hosting-profiles.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 1244e897..84bb3fa6 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -364,20 +364,20 @@ generation-fenced safe destruction remain Runtime State Continuity concerns. After the readiness-only stack is established, the profile implementation is a single dependent series in [openclaw/openclaw#107765](https://github.com/openclaw/openclaw/pull/107765). -It is based on readiness head `813104950f5` from +It is based on readiness head `ac04dca2b21` from [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -and contains seventeen profile-only commits at exact head `d191c89203e`. +and contains eighteen profile-only commits at exact head `479ff9b4898`. | Slice | Intended scope | | --- | --- | | Standard selection and predicates | Add opt-in selection, precedence, machine-readable projection, and `local`, `container`, and `reverse-proxy` conditions. | | Node mode | Add product-neutral pairing, connected-target, canonical command-policy, and control-channel conditions. | -| Compatibility and safety | Keep unprofiled startup unchanged, validate profile-only identity only when selected, and bound profile evaluation. | +| Compatibility and safety | Keep unprofiled startup unchanged, validate profile-only identity only when selected, preserve attribution on failed evaluation, and bound pairing recovery work. | | Packaged scenarios | Exercise all four profiles, primary failures, node approval, workspace-full recovery, and unprofiled compatibility. | PR 107765 is a stacked upstream draft against `main`. Until PR 104018 lands, its aggregate GitHub diff includes the readiness dependency followed by the -seventeen profile commits. After PR 104018 lands, the same PR naturally reduces to +eighteen profile commits. After PR 104018 lands, the same PR naturally reduces to the profile-only diff. [Fork PR 94](https://github.com/giodl73-repo/openclaw/pull/94) preserves that profile-only comparison view in the meantime. Fork PRs [#18](https://github.com/giodl73-repo/openclaw/pull/18), From 22602eb734fe5ee20d917ab1187285c5a4aa199a Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Thu, 23 Jul 2026 10:05:39 -0700 Subject: [PATCH 22/52] docs(rfc-0023): specify bounded pairing recovery --- rfcs/0023/hosting-profile-v1-spec.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/rfcs/0023/hosting-profile-v1-spec.md b/rfcs/0023/hosting-profile-v1-spec.md index 6ff93e2b..6f8af621 100644 --- a/rfcs/0023/hosting-profile-v1-spec.md +++ b/rfcs/0023/hosting-profile-v1-spec.md @@ -164,8 +164,10 @@ surface. The profile does not impose product, tenant, or one-target-per-agent semantics. Evaluation is bounded by the canonical readiness deadline and uses the current pairing generation and pairing-bound connected-session state; it does not perform network discovery or wait for a target during a readiness poll. -Pairing-store reads remain single-flight after timeout, and store exceptions are -projected as stable redacted reasons rather than raw error text. +Pairing-store reads are single-flight until timeout. A later poll may start one +replacement read so a recovered store can become ready, but no more than two +reads may remain in flight. Store exceptions are projected as stable redacted +reasons rather than raw error text. ## Selection And Precedence From af93fb55c71611e750666818acf1268e6e02d184 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Thu, 23 Jul 2026 10:06:37 -0700 Subject: [PATCH 23/52] docs(rfc-0023): delimit proxy readiness --- rfcs/0023/hosting-profile-v1-spec.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/rfcs/0023/hosting-profile-v1-spec.md b/rfcs/0023/hosting-profile-v1-spec.md index 6f8af621..82786f1d 100644 --- a/rfcs/0023/hosting-profile-v1-spec.md +++ b/rfcs/0023/hosting-profile-v1-spec.md @@ -143,8 +143,12 @@ This readiness condition validates the effective auth configuration. Existing Gateway trusted-proxy request handling remains responsible for rejecting untrusted or forged identity ingress; readiness does not replay a request on every poll. Source syntax and listener/source compatibility use the same network -matching semantics as request authentication. Loopback is valid only when a -colocated proxy is explicitly allowed. +matching semantics as request authentication. `True` means the static +configuration contains a usable source range for the listener topology; it +does not guarantee that every address in that range is an eligible request +source. Request-time authentication still rejects the Gateway's own local +interface addresses and applies required-header and identity checks. Loopback +is valid only when a colocated proxy is explicitly allowed. ### Node Mode From 562fbec7f29735984ebc50efbbc5a379d922e536 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Thu, 23 Jul 2026 10:07:59 -0700 Subject: [PATCH 24/52] docs(rfc-0023): refresh exact profile head --- rfcs/0023-standard-hosting-profiles.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 84bb3fa6..8a75454c 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -366,7 +366,7 @@ single dependent series in [openclaw/openclaw#107765](https://github.com/openclaw/openclaw/pull/107765). It is based on readiness head `ac04dca2b21` from [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -and contains eighteen profile-only commits at exact head `479ff9b4898`. +and contains nineteen profile-only commits at exact head `6f9c158509b`. | Slice | Intended scope | | --- | --- | @@ -377,7 +377,7 @@ and contains eighteen profile-only commits at exact head `479ff9b4898`. PR 107765 is a stacked upstream draft against `main`. Until PR 104018 lands, its aggregate GitHub diff includes the readiness dependency followed by the -eighteen profile commits. After PR 104018 lands, the same PR naturally reduces to +nineteen profile commits. After PR 104018 lands, the same PR naturally reduces to the profile-only diff. [Fork PR 94](https://github.com/giodl73-repo/openclaw/pull/94) preserves that profile-only comparison view in the meantime. Fork PRs [#18](https://github.com/giodl73-repo/openclaw/pull/18), From 383a2cd87eb1048ba7e64cda0abaf8db675bef57 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Thu, 23 Jul 2026 10:11:48 -0700 Subject: [PATCH 25/52] docs(rfc-0023): refresh readiness base --- rfcs/0023-standard-hosting-profiles.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 8a75454c..a07526f9 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -364,9 +364,9 @@ generation-fenced safe destruction remain Runtime State Continuity concerns. After the readiness-only stack is established, the profile implementation is a single dependent series in [openclaw/openclaw#107765](https://github.com/openclaw/openclaw/pull/107765). -It is based on readiness head `ac04dca2b21` from +It is based on readiness head `8fbc1210762` from [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -and contains nineteen profile-only commits at exact head `6f9c158509b`. +and contains nineteen profile-only commits at exact head `864c8d25459`. | Slice | Intended scope | | --- | --- | From 68cad72c5e528300b9d48814f10df5e3955ba85e Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Thu, 23 Jul 2026 10:23:06 -0700 Subject: [PATCH 26/52] docs(rfc-0023): refresh implementation heads --- rfcs/0023-standard-hosting-profiles.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index a07526f9..75a3d3df 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -364,9 +364,9 @@ generation-fenced safe destruction remain Runtime State Continuity concerns. After the readiness-only stack is established, the profile implementation is a single dependent series in [openclaw/openclaw#107765](https://github.com/openclaw/openclaw/pull/107765). -It is based on readiness head `8fbc1210762` from +It is based on readiness head `c1919669c3f` from [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -and contains nineteen profile-only commits at exact head `864c8d25459`. +and contains nineteen profile-only commits at exact head `40b5b2e59d9`. | Slice | Intended scope | | --- | --- | From 756a7b91bb8f0ed06cc9053de41a326ab631f7cf Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Fri, 24 Jul 2026 14:56:42 -0700 Subject: [PATCH 27/52] docs(rfc-0023): compose core readiness criteria --- rfcs/0023-standard-hosting-profiles.md | 41 ++++++++++++++------------ rfcs/0023/hosting-profile-v1-spec.md | 21 ++++++++----- 2 files changed, 36 insertions(+), 26 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 75a3d3df..90d10916 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -165,10 +165,13 @@ conditions; independent targets cannot satisfy different rows. Gateway request handling remains responsible for rejecting forged or untrusted identity ingress; readiness does not issue a synthetic request on every poll. -Common runtime conditions such as `ConfigLoaded`, `WorkspaceWritable`, -`GatewayResponding`, and conditionally required plugin, secret, or model-route -activation remain owned by readiness and their source subsystems. Profiles only -declare when they are required for the supported posture. +Common runtime conditions remain owned by readiness and their source +subsystems. Every selected profile requires current config, usable model +routing/auth, resolved secrets, writable workspace, session storage, context +engine, tool catalog, configured MCP/sandbox/harness capability, and successful +plugin activation. State, delivery-runtime, and scheduler conditions are +selected as advisory diagnostics. Profiles only declare requirement; they do +not implement or invoke these observations. ### Selection and precedence @@ -363,10 +366,12 @@ generation-fenced safe destruction remain Runtime State Continuity concerns. After the readiness-only stack is established, the profile implementation is a single dependent series in -[openclaw/openclaw#107765](https://github.com/openclaw/openclaw/pull/107765). -It is based on readiness head `c1919669c3f` from +[openclaw/openclaw#113422](https://github.com/openclaw/openclaw/pull/113422). +It depends on the readiness framework in [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -and contains nineteen profile-only commits at exact head `40b5b2e59d9`. +and the core-owner criteria in +[openclaw/openclaw#113421](https://github.com/openclaw/openclaw/pull/113421). +The exact profile head is `fcf4100bdcb`. | Slice | Intended scope | | --- | --- | @@ -375,24 +380,22 @@ and contains nineteen profile-only commits at exact head `40b5b2e59d9`. | Compatibility and safety | Keep unprofiled startup unchanged, validate profile-only identity only when selected, preserve attribution on failed evaluation, and bound pairing recovery work. | | Packaged scenarios | Exercise all four profiles, primary failures, node approval, workspace-full recovery, and unprofiled compatibility. | -PR 107765 is a stacked upstream draft against `main`. Until PR 104018 lands, -its aggregate GitHub diff includes the readiness dependency followed by the -nineteen profile commits. After PR 104018 lands, the same PR naturally reduces to -the profile-only diff. [Fork PR 94](https://github.com/giodl73-repo/openclaw/pull/94) -preserves that profile-only comparison view in the meantime. Fork PRs +PR 113422 is a stacked upstream draft against `main`. Until PRs 104018 and +113421 land, its aggregate GitHub diff includes both dependencies followed by +the profile commits. After both land, the same PR reduces to the profile-only +diff. [Fork PR 157](https://github.com/giodl73-repo/openclaw/pull/157) +preserves that exact profile-only comparison view. Fork PRs [#18](https://github.com/giodl73-repo/openclaw/pull/18), [#19](https://github.com/giodl73-repo/openclaw/pull/19), [#42](https://github.com/giodl73-repo/openclaw/pull/42), and [#21](https://github.com/giodl73-repo/openclaw/pull/21) expose the major design slices as review aids; they are not alternative landing requests. -The refreshed stack passes 156 focused profile, Gateway, config, and CLI -assertions, production typing, and protocol generation/compatibility checks. A prior package-installed -Docker matrix proved all four profiles plus listener, -trusted-proxy, node-approval, workspace-full, recovery, and unprofiled `200` -compatibility using image -`sha256:20d507b613b346e1165add88234eb00390ea6d1b086970dd3589dd3f41654175`. -Exact-head remote container proof must be refreshed before landing. +The refreshed stack passes focused profile, readiness, Gateway, config-help, +CLI, and Docker-plan tests; type-aware lint, formatting, and independent review +are clean. Package build and tarball-integrity stages pass. The exact-head +package-installed Docker matrix remains a landing gate because the available +local Docker Linux engine did not become ready. ## Rationale diff --git a/rfcs/0023/hosting-profile-v1-spec.md b/rfcs/0023/hosting-profile-v1-spec.md index 82786f1d..f900ed1b 100644 --- a/rfcs/0023/hosting-profile-v1-spec.md +++ b/rfcs/0023/hosting-profile-v1-spec.md @@ -73,7 +73,7 @@ baseline: | Profile ID | Runtime posture | Required profile criteria | | --- | --- | --- | -| `local` | Explicit local or foreground Gateway | `WorkspaceWritable`, `ProfileSelected`, `RuntimeActivationIdentified` | +| `local` | Explicit local or foreground Gateway | Shared required criteria, `ProfileSelected`, `RuntimeActivationIdentified` | | `container` | Gateway directly reachable through a container listener | `local` plus `ContainerStateReady` | | `reverse-proxy` | Gateway behind a trusted identity proxy | `local` plus `TrustedProxyReady` | | `node-mode` | Gateway controlling one or more paired execution targets | `local` plus `NodePairingReady`, `ControlledTargetsReady`, `CommandApprovalReady`, `ControlChannelReady` | @@ -85,14 +85,21 @@ listener selects `container`. The RFC 0018 universal baseline remains required and cannot be removed, replaced, or weakened by a profile. -`WorkspaceWritable` is selected through the RFC 0018 criterion ID -`openclaw.workspace-writable`. The remaining additional condition types are -profile-owned predicates and are not independently operator-selectable in v1. - -Canonical condition ordering remains owned by RFC 0018: `ConfigLoaded` and +The shared required criteria are `openclaw.config-current`, +`openclaw.model-route-ready`, `openclaw.secrets-ready`, +`openclaw.workspace-writable`, `openclaw.session-storage-ready`, +`openclaw.context-engine-ready`, `openclaw.tool-catalog-ready`, +`openclaw.mcp-runtime-ready`, `openclaw.sandbox-ready`, and +`openclaw.harness-ready`. A selected profile also promotes `PluginsLoaded` to +required. It selects `openclaw.state-ready`, +`openclaw.delivery-runtime-ready`, and `openclaw.scheduler-ready` as advisory. +The remaining additional condition types are profile-owned predicates and are +not independently operator-selectable in v1. + +Canonical condition ordering remains owned by RFC 0018. `ConfigLoaded` and `WorkspaceWritable` precede `ProfileSelected`, `RuntimeActivationIdentified`, and the profile-specific conditions listed above; `GatewayResponding` and -`PluginsLoaded` follow them. +`PluginsLoaded` follow them, followed by the remaining selected criteria. ## Profile Criteria From 5cec4cd9dbf8b6795329e0c1d0a3c4e50ba76f98 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Fri, 24 Jul 2026 16:05:30 -0700 Subject: [PATCH 28/52] docs(rfc-0023): compose canonical profile criteria --- rfcs/0023-standard-hosting-profiles.md | 12 +++++++----- rfcs/0023/hosting-profile-v1-spec.md | 7 ++++--- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 90d10916..eff07982 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -167,11 +167,13 @@ identity ingress; readiness does not issue a synthetic request on every poll. Common runtime conditions remain owned by readiness and their source subsystems. Every selected profile requires current config, usable model -routing/auth, resolved secrets, writable workspace, session storage, context -engine, tool catalog, configured MCP/sandbox/harness capability, and successful -plugin activation. State, delivery-runtime, and scheduler conditions are -selected as advisory diagnostics. Profiles only declare requirement; they do -not implement or invoke these observations. +routing/auth, successful plugin activation, resolved secrets, writable +workspace, session storage, context engine, tool catalog, and configured +MCP/sandbox/harness capability. Event-loop health, state, delivery-runtime, and +scheduler conditions are selected as advisory diagnostics. Profiles select the +ordinary RFC 0018 IDs `openclaw.plugins-loaded` and +`openclaw.event-loop-healthy`; they do not implement special profile-only +versions of those observations. ### Selection and precedence diff --git a/rfcs/0023/hosting-profile-v1-spec.md b/rfcs/0023/hosting-profile-v1-spec.md index f900ed1b..a1593967 100644 --- a/rfcs/0023/hosting-profile-v1-spec.md +++ b/rfcs/0023/hosting-profile-v1-spec.md @@ -86,12 +86,13 @@ The RFC 0018 universal baseline remains required and cannot be removed, replaced, or weakened by a profile. The shared required criteria are `openclaw.config-current`, -`openclaw.model-route-ready`, `openclaw.secrets-ready`, +`openclaw.model-route-ready`, `openclaw.plugins-loaded`, +`openclaw.secrets-ready`, `openclaw.workspace-writable`, `openclaw.session-storage-ready`, `openclaw.context-engine-ready`, `openclaw.tool-catalog-ready`, `openclaw.mcp-runtime-ready`, `openclaw.sandbox-ready`, and -`openclaw.harness-ready`. A selected profile also promotes `PluginsLoaded` to -required. It selects `openclaw.state-ready`, +`openclaw.harness-ready`. It selects `openclaw.event-loop-healthy`, +`openclaw.state-ready`, `openclaw.delivery-runtime-ready`, and `openclaw.scheduler-ready` as advisory. The remaining additional condition types are profile-owned predicates and are not independently operator-selectable in v1. From 756cb80526e1489248922fe7989efc58482dda53 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 25 Jul 2026 10:01:38 -0700 Subject: [PATCH 29/52] docs(rfc-0023): refresh implementation stack --- rfcs/0023-standard-hosting-profiles.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index eff07982..40839e13 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -371,9 +371,10 @@ single dependent series in [openclaw/openclaw#113422](https://github.com/openclaw/openclaw/pull/113422). It depends on the readiness framework in [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) +at exact head `f1af3de0a9b1` and the core-owner criteria in -[openclaw/openclaw#113421](https://github.com/openclaw/openclaw/pull/113421). -The exact profile head is `fcf4100bdcb`. +[openclaw/openclaw#113421](https://github.com/openclaw/openclaw/pull/113421) +at exact head `785a11b05e9c`. The exact profile head is `eca79f34395c`. | Slice | Intended scope | | --- | --- | From fd4225cbaed0377c4e70d82b0e749c34ee688817 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 25 Jul 2026 10:19:59 -0700 Subject: [PATCH 30/52] docs(rfc-0023): advance rebased implementation heads --- rfcs/0023-standard-hosting-profiles.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 40839e13..aa7f16a3 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -371,10 +371,10 @@ single dependent series in [openclaw/openclaw#113422](https://github.com/openclaw/openclaw/pull/113422). It depends on the readiness framework in [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -at exact head `f1af3de0a9b1` +at exact head `5861bcd70c6a` and the core-owner criteria in [openclaw/openclaw#113421](https://github.com/openclaw/openclaw/pull/113421) -at exact head `785a11b05e9c`. The exact profile head is `eca79f34395c`. +at exact head `ce9ef81b24d6`. The exact profile head is `17149d7ecf15`. | Slice | Intended scope | | --- | --- | From dcfb7cfea08b46f07efa908d6ac1d9a6d540263e Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 25 Jul 2026 16:30:11 -0700 Subject: [PATCH 31/52] docs(rfc-0023): reuse readiness subject identity --- rfcs/0023-standard-hosting-profiles.md | 94 +++--- rfcs/0023/hosting-profile-v1-spec.md | 430 +++++++++++-------------- 2 files changed, 231 insertions(+), 293 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index aa7f16a3..99c790c2 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -3,7 +3,7 @@ title: Standard Hosting Profiles authors: - Gio created: 2026-07-14 -last_updated: 2026-07-23 +last_updated: 2026-07-25 status: draft issue: rfc_pr: https://github.com/openclaw/rfcs/pull/37 @@ -16,7 +16,7 @@ rfc_pr: https://github.com/openclaw/rfcs/pull/37 Define a small catalog of named, release-tested OpenClaw runtime postures: `local`, `container`, `reverse-proxy`, and `node-mode`. A selected profile composes canonical readiness conditions into a support contract, identifies the -runtime activation being evaluated, and has a matching packaged release +profile and runtime subjects being evaluated, and has a matching packaged release scenario. This RFC depends on the separate Readiness Conditions and Providers RFC. That @@ -48,7 +48,7 @@ Standard profiles turn that open-ended claim into a small product contract: OpenClaw supports these named runtime postures. Each posture composes stable readiness conditions. Each release executes the matching conformance scenarios. -The running process reports which posture and activation it represents. +The running process reports which posture and observed subjects it represents. ``` This helps maintainers reproduce issues against a supported subset without @@ -66,8 +66,8 @@ standard catalog. - Compose profiles from reusable canonical readiness conditions. - Define exact predicates and stable reasons for profile-specific conditions. - Report the selected profile through readiness, health, and status. -- Identify the logical runtime and unique process/container incarnation whose - profile result is being reported. +- Attribute profile and topology conditions to the shared readiness subjects + defined by RFC 0018. - Exercise every standard profile through a packaged release scenario lane. - Keep host orchestration and OpenClaw runtime ownership separate. @@ -85,7 +85,8 @@ standard catalog. - Guarantee checkpoint durability, restore compatibility, or safe destruction. - Claim that every possible OpenClaw configuration belongs to a standard profile. -- Define named operator profiles, inheritance, host assertions, immutable +- Define a second runtime-activation identity envelope, named operator + profiles, inheritance, host assertions, immutable conformance records, or signed artifact attestations in V1. ## Proposal @@ -93,7 +94,7 @@ standard catalog. The implementer-facing v1 contract is captured in [`0023/hosting-profile-v1-spec.md`](0023/hosting-profile-v1-spec.md). This RFC remains the design rationale, support argument, and rollout plan; the sidecar is -the concise profile catalog, selection, activation, projection, and packaged +the concise profile catalog, selection, subject attribution, projection, and packaged scenario reference for OpenClaw runtime and release implementations. ### Dependency on canonical readiness @@ -125,7 +126,7 @@ RFC 0023 profile use: | Profile | Runtime posture | Additional required condition types | | --- | --- | --- | -| `local` | Explicit local or foreground Gateway posture | `ProfileSelected`, `RuntimeActivationIdentified`, `WorkspaceWritable` | +| `local` | Explicit local or foreground Gateway posture | `ProfileSelected`, `WorkspaceWritable` | | `container` | Gateway directly reachable through a container listener | `local` plus `ContainerStateReady` | | `reverse-proxy` | Gateway behind a trusted identity proxy | `local` plus `TrustedProxyReady`; loopback requires the explicit trusted-proxy loopback allowance | | `node-mode` | Gateway controlling one or more execution targets | `local` plus `NodePairingReady`, `ControlledTargetsReady`, `CommandApprovalReady`, `ControlChannelReady` | @@ -147,7 +148,6 @@ contract and existing OpenClaw runtime owners. | Condition | Profile | True when | Stable non-ready reasons | | --- | --- | --- | --- | | `ProfileSelected` | All | Selection precedence resolves to a valid standard profile. | Invalid explicit values fail startup validation. | -| `RuntimeActivationIdentified` | All | Non-empty logical-runtime and unique-incarnation identities are resolved. | Invalid explicit values fail startup validation. | | `ContainerStateReady` | `container` | The resolved listener host is not loopback. | `ContainerGatewayLoopback` | | `TrustedProxyReady` | `reverse-proxy` | Auth mode is `trusted-proxy`, a user header and trusted source are configured, and loopback sources are explicitly allowed. | `TrustedProxyAuthMissing`, `TrustedProxyHeaderMissing`, `TrustedProxySourcesMissing`, `TrustedProxyIngressUnsafe` | | `NodePairingReady` | `node-mode` | Pairing state is readable and contains an approved pairing. | `NodePairingUnavailable`, `NodePairingTimedOut`, `NodePairingPending`, `NodePairingMissing` | @@ -209,39 +209,30 @@ openclaw gateway run --hosting-profile container When selected, the effective profile, selection source, and condition result are reported by readiness, health, and status. An unprofiled runtime omits -`ProfileSelected`, activation identity, top-level profile fields, and +`ProfileSelected`, profile identity, top-level profile fields, and profile-only requirements. Profiles validate effective runtime state. They do not generate or repair the underlying Gateway, proxy, plugin, model, node, or storage config. -### Runtime activation identity +### Readiness subject attribution -A readiness result must be attributable to one runtime activation. OpenClaw -resolves: +Profiles use RFC 0018's identity package instead of defining another runtime +identity. A profiled result declares `openclaw/hosting-profile/selected` with +the selected profile as its opaque ID and the profile contract version as its +generation. `ProfileSelected` targets that subject. Topology-specific +conditions target the Gateway or node-controller subject and relate back to +the selected profile. -- a logical runtime ID that may remain stable across process replacement; and -- a unique incarnation ID for the current process/container activation. +Node mode additionally declares `openclaw/nodes/managed` and bounded child +subjects for the paired nodes observed during that evaluation. Its aggregate +conditions use the controller as their primary subject and list observed nodes +as related subjects. Repeated results can therefore distinguish a changed +condition from a replaced Gateway, changed profile, or changed node set. -Launchers may provide identities through startup arguments or environment. -Absent values receive runtime-owned defaults: the logical runtime ID is -`local`, and the incarnation ID is unique to the current process activation. -Invalid explicit identities fail startup rather than silently falling back. - -The activation summary is redacted and references, rather than copies, inputs -owned by other contracts: - -```ts -type RuntimeActivationSummary = { - runtimeId: string; - incarnationId: string; - profile: string; -}; -``` - -This is not an OCC instance resource. OCC may supply desired identity and -profile selection, but OpenClaw evaluates the live activation in the runtime -plane. +The Gateway serving-lifecycle ID remains RFC 0018's concern. Hosts may supply +its opaque ID through `OPENCLAW_INSTANCE_ID`; otherwise OpenClaw generates it. +Profiles do not add `runtimeId`, `incarnationId`, or an activation envelope. ### Operator extensions @@ -266,14 +257,23 @@ HTTP/1.1 503 Service Unavailable "profile": "container", "profileSource": "config", "ready": false, - "activation": { - "runtimeId": "worker-17", - "incarnationId": "01J...", - "profile": "container" + "identity": { + "producerRef": "openclaw/gateway/current", + "subjects": [ + { + "ref": "openclaw/hosting-profile/selected", + "kind": "openclaw.hosting-profile", + "id": "container", + "generation": "1", + "parentRef": "openclaw/gateway/current" + } + ] }, "conditions": [ { "type": "ContainerStateReady", + "subjectRef": "openclaw/gateway/current", + "relatedSubjectRefs": ["openclaw/hosting-profile/selected"], "status": "False", "requirement": "required", "reason": "ContainerGatewayLoopback", @@ -315,7 +315,7 @@ OpenClaw owns: - standard profile names and definitions; - profile-specific condition predicates and reasons; - selection precedence and result projection; -- activation identity semantics; and +- profile subject attribution semantics; and - the packaged scenario lane for the standard catalog. Hosts own: @@ -333,9 +333,9 @@ release notes, and conformance coverage. ### OCC and AgentHarness alignment -OCC may compile desired state into OpenClaw config, profile selection, runtime -identity, and host policy. The runtime plane still evaluates readiness and -reports the live activation. +OCC may compile desired state into OpenClaw config, profile selection, Gateway +instance identity, and host policy. The runtime plane still evaluates +readiness and reports the live subjects. AgentHarness owns harness execution events. Hosting profiles do not carry assistant deltas, tool frames, approvals, patches, compaction events, or @@ -343,10 +343,10 @@ harness protocol frames. ```text OCC/control plane - -> desired runtime identity and profile + -> desired Gateway identity and profile OpenClaw/runtime plane - -> live activation + -> live Gateway, profile, and topology subjects -> canonical readiness conditions -> selected profile result @@ -371,10 +371,10 @@ single dependent series in [openclaw/openclaw#113422](https://github.com/openclaw/openclaw/pull/113422). It depends on the readiness framework in [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -at exact head `5861bcd70c6a` +at exact head `13b0acaa00f3` and the core-owner criteria in [openclaw/openclaw#113421](https://github.com/openclaw/openclaw/pull/113421) -at exact head `ce9ef81b24d6`. The exact profile head is `17149d7ecf15`. +at exact head `dbd540b18a0b`. The exact profile head is `fb1e60db1795`. | Slice | Intended scope | | --- | --- | @@ -408,7 +408,7 @@ reports, executable release evidence, and clear responsibility without taking configuration freedom away from operators. Profiles belong in OpenClaw because only the runtime can define the predicates -that mean its Gateway, proxy, node, plugin, and activation state satisfy a +that mean its Gateway, proxy, node, plugin, and observed state satisfy a supported posture. Hosts should select and operationalize the posture, not reverse-engineer its internal readiness semantics. diff --git a/rfcs/0023/hosting-profile-v1-spec.md b/rfcs/0023/hosting-profile-v1-spec.md index a1593967..cd4b915f 100644 --- a/rfcs/0023/hosting-profile-v1-spec.md +++ b/rfcs/0023/hosting-profile-v1-spec.md @@ -1,10 +1,8 @@ # Standard Hosting Profile v1 Specification -This document is the implementer-facing specification for RFC 0023, Standard -Hosting Profiles. The RFC explains the motivation, support model, and rollout -plan. This file defines the v1 standard profile catalog, condition composition, -selection precedence, activation identity, host-visible result, and packaged -scenario gate. +This is the implementer-facing specification for RFC 0023. It defines the v1 +standard profile catalog, selection precedence, readiness composition, subject +attribution, host-visible projection, and packaged release scenarios. Status: draft, tied to RFC 0023 and dependent on RFC 0018. @@ -12,186 +10,87 @@ Status: draft, tied to RFC 0023 and dependent on RFC 0018. This specification defines: -- the `local`, `container`, `reverse-proxy`, and `node-mode` standard profiles; -- composition over canonical readiness criteria from RFC 0018; -- opt-in selection through config, environment, or startup arguments; +- the `local`, `container`, `reverse-proxy`, and `node-mode` profiles; +- composition over RFC 0018 readiness criteria; +- opt-in selection through config, environment, or startup argument; - exact profile predicates and stable non-ready reasons; -- logical runtime and unique incarnation identity; +- attribution through the RFC 0018 readiness identity package; - readiness, health, and status projection; and -- a packaged release scenario lane for the standard catalog. +- packaged release scenarios for the standard catalog. -This specification does not define: - -- the readiness condition schema or plugin provider API; -- config generation, merge, repair, or policy enforcement; -- scheduler retry intervals, placement, routing, tenants, or rollout; -- OCC resources or the AgentHarness event protocol; -- checkpoint durability or safe destruction; or -- operator-defined profiles, profile inheritance, host assertions, artifact - identity, or signed conformance records; or -- support for arbitrary OpenClaw configurations outside the standard catalog. +It does not define a second readiness evaluator, runtime-activation envelope, +config repair system, scheduler policy, OCC resource, AgentHarness protocol, +continuity contract, operator-defined profile, or arbitrary OpenClaw support +promise. ## Dependencies -This specification requires the canonical condition, aggregation, bounded -evaluation, and projection contract defined by RFC 0018. Profiles are data that -select and classify reusable criteria. They do not define a second evaluator. - -An implementation that has no selected profile remains a valid RFC 0018 -runtime. Selecting a profile adds the contract in this specification. - -## Terminology - -- **Standard profile**: an OpenClaw-owned, named runtime posture with stable - predicates and packaged release scenarios. -- **Universal baseline**: RFC 0018 conditions that apply with or without a - profile. -- **Profile criterion**: a reusable readiness criterion selected by a profile. -- **Logical runtime ID**: identity that may remain stable across process or - container replacement. -- **Incarnation ID**: identity unique to one running process or container - activation. +RFC 0018 owns condition shape, subjects, aggregation, deadlines, provider +bounds, fail-closed behavior, and host-visible projection. Profiles are data +that select reusable criteria and add a small set of runtime-owned predicates. -## Compatibility And Evolution +An unprofiled RFC 0018 runtime remains conformant. Selecting a profile opts into +this specification. -Hosting Profile v1 uses these compatibility rules: +## Compatibility -- profile selection is optional and opt-in; -- an upgrade must not select a profile for an existing unprofiled deployment; -- standard profile IDs, predicates, required condition types and criterion - selectors, and stable reasons are compatibility contracts; -- adding or strengthening a required criterion changes host behavior and - requires compatibility review, release notes, and conformance coverage; -- unknown explicit profile values fail startup validation; and -- new standard profiles require a separately reviewable support posture and - release conformance scenario. +- Selection is optional and opt-in. +- Upgrade must not select a profile for an unprofiled deployment. +- Profile IDs, predicates, required criteria, and stable reasons are contracts. +- Strengthening a required criterion requires compatibility review, release + notes, and conformance coverage. +- An invalid explicit profile fails startup validation. +- A new standard profile requires a distinct support posture and packaged + conformance scenario. -## Standard Profile Catalog +## Standard Catalog -The v1 standard catalog requires these conditions over the RFC 0018 universal -baseline: - -| Profile ID | Runtime posture | Required profile criteria | +| Profile ID | Runtime posture | Required profile conditions | | --- | --- | --- | -| `local` | Explicit local or foreground Gateway | Shared required criteria, `ProfileSelected`, `RuntimeActivationIdentified` | -| `container` | Gateway directly reachable through a container listener | `local` plus `ContainerStateReady` | +| `local` | Local or foreground Gateway | `ProfileSelected` | +| `container` | Directly reachable container listener | `local` plus `ContainerStateReady` | | `reverse-proxy` | Gateway behind a trusted identity proxy | `local` plus `TrustedProxyReady` | -| `node-mode` | Gateway controlling one or more paired execution targets | `local` plus `NodePairingReady`, `ControlledTargetsReady`, `CommandApprovalReady`, `ControlChannelReady` | +| `node-mode` | Gateway controlling paired execution targets | `local` plus `NodePairingReady`, `ControlledTargetsReady`, `CommandApprovalReady`, `ControlChannelReady` | A profile describes runtime posture, not packaging. A container behind an -identity proxy selects `reverse-proxy`; a container with a directly reachable -listener selects `container`. - -The RFC 0018 universal baseline remains required and cannot be removed, -replaced, or weakened by a profile. - -The shared required criteria are `openclaw.config-current`, -`openclaw.model-route-ready`, `openclaw.plugins-loaded`, -`openclaw.secrets-ready`, -`openclaw.workspace-writable`, `openclaw.session-storage-ready`, -`openclaw.context-engine-ready`, `openclaw.tool-catalog-ready`, -`openclaw.mcp-runtime-ready`, `openclaw.sandbox-ready`, and -`openclaw.harness-ready`. It selects `openclaw.event-loop-healthy`, -`openclaw.state-ready`, -`openclaw.delivery-runtime-ready`, and `openclaw.scheduler-ready` as advisory. -The remaining additional condition types are profile-owned predicates and are -not independently operator-selectable in v1. - -Canonical condition ordering remains owned by RFC 0018. `ConfigLoaded` and -`WorkspaceWritable` precede `ProfileSelected`, `RuntimeActivationIdentified`, -and the profile-specific conditions listed above; `GatewayResponding` and -`PluginsLoaded` follow them, followed by the remaining selected criteria. - -## Profile Criteria - -### Profile Selection +identity proxy selects `reverse-proxy`; a directly reachable container selects +`container`. -`ProfileSelected` is `True` when selection precedence resolves to a valid -standard profile. Invalid explicit values fail startup validation rather than -becoming a running false condition. +Every profile selects these RFC 0018 criteria as required: -### Runtime Activation Identity +- `openclaw.config-current`; +- `openclaw.model-route-ready`; +- `openclaw.plugins-loaded`; +- `openclaw.secrets-ready`; +- `openclaw.workspace-writable`; +- `openclaw.session-storage-ready`; +- `openclaw.context-engine-ready`; +- `openclaw.tool-catalog-ready`; +- `openclaw.mcp-runtime-ready`; +- `openclaw.sandbox-ready`; and +- `openclaw.harness-ready`. -`RuntimeActivationIdentified` is `True` when both logical runtime and unique -incarnation identities are non-empty and valid. +Every profile selects these as advisory: -Invalid explicit values fail startup validation, so V1 does not emit a running -non-ready activation condition. +- `openclaw.event-loop-healthy`; +- `openclaw.state-ready`; +- `openclaw.delivery-runtime-ready`; and +- `openclaw.scheduler-ready`. -### Container +The RFC 0018 universal Gateway lifecycle baseline remains in force and cannot +be removed or weakened by a profile. -`ContainerStateReady` is `True` when the resolved listener host is not loopback. - -Stable non-ready reasons are: - -- `ContainerGatewayLoopback`. - -This criterion validates OpenClaw's effective listener state. It does not -inspect Docker, Kubernetes, ECS, Nomad, or another scheduler API. - -### Reverse Proxy - -`TrustedProxyReady` is `True` when: +## Selection -- effective auth mode is `trusted-proxy`; -- a user identity header is configured; and -- at least one syntactically valid trusted proxy source is configured; and -- a loopback-only listener has a loopback trusted proxy source; and -- when that source includes loopback, the explicit trusted-proxy loopback - allowance is enabled. - -Stable non-ready reasons are: - -- `TrustedProxyAuthMissing`; -- `TrustedProxyHeaderMissing`; -- `TrustedProxySourcesMissing`; and -- `TrustedProxyIngressUnsafe`. - -This readiness condition validates the effective auth configuration. Existing -Gateway trusted-proxy request handling remains responsible for rejecting -untrusted or forged identity ingress; readiness does not replay a request on -every poll. Source syntax and listener/source compatibility use the same network -matching semantics as request authentication. `True` means the static -configuration contains a usable source range for the listener topology; it -does not guarantee that every address in that range is an eligible request -source. Request-time authentication still rejects the Gateway's own local -interface addresses and applies required-header and identity checks. Loopback -is valid only when a colocated proxy is explicitly allowed. - -### Node Mode - -The node-mode profile requires all four criteria below. One correlated approved -pairing, connected target, effective command grant, and live target session must -satisfy the set; independent targets cannot satisfy different rows. - -| Condition type | True when | Stable non-ready reasons | -| --- | --- | --- | -| `NodePairingReady` | Pairing state is readable and contains an approved pairing. | `NodePairingUnavailable`, `NodePairingTimedOut`, `NodePairingPending`, `NodePairingMissing` | -| `ControlledTargetsReady` | At least one connected target correlates to an approved pairing. | `ControlledTargetsDisconnected` | -| `CommandApprovalReady` | A connected paired target advertises a command permitted by effective grants. | `CommandApprovalMissing` | -| `ControlChannelReady` | At least one live target session correlates to an approved pairing. | `ControlChannelUnavailable` | - -A target may be a desktop, sandbox, VM, pod, browser, or another execution -surface. The profile does not impose product, tenant, or one-target-per-agent -semantics. Evaluation is bounded by the canonical readiness deadline and uses -the current pairing generation and pairing-bound connected-session state; it -does not perform network discovery or wait for a target during a readiness poll. -Pairing-store reads are single-flight until timeout. A later poll may start one -replacement read so a recovered store can become ready, but no more than two -reads may remain in flight. Store exceptions are projected as stable redacted -reasons rather than raw error text. - -## Selection And Precedence - -Selection sources use this precedence: +Selection precedence is: ```text gateway startup argument > OPENCLAW_HOSTING_PROFILE -> openclaw.json +> openclaw.json hosting.profile ``` -Configuration example: +Examples: ```json5 { @@ -201,67 +100,113 @@ Configuration example: } ``` -Equivalent startup selection: - ```bash OPENCLAW_HOSTING_PROFILE=container openclaw gateway run openclaw gateway run --hosting-profile container ``` -An absent value means unprofiled operation; it must not imply `local`. The -highest-precedence supplied source is validated and wins; shadowed -lower-precedence values are not evaluated. An empty, malformed, or unknown -winning value fails validation before destructive lifecycle actions. +An absent value means unprofiled operation, not `local`. The winning value is +validated before destructive lifecycle actions. The effective result records +the profile and selection source. -The effective result records the profile and winning selection source. +## Profile Predicates -Profiles validate effective runtime state. They do not generate or repair the -underlying Gateway, proxy, plugin, model, node, or storage configuration. +### Profile Selection -## Runtime Activation Identity +`ProfileSelected` is `True` when precedence resolves to a valid standard +profile. Invalid explicit values fail startup rather than becoming a running +false condition. -Every profiled result is attributable to one activation: +### Container + +`ContainerStateReady` is `True` when the effective listener is not loopback. +Its stable false reason is `ContainerGatewayLoopback`. It inspects OpenClaw's +listener state, not a container scheduler API. + +### Reverse Proxy + +`TrustedProxyReady` is `True` when: + +- auth mode is `trusted-proxy`; +- a user identity header is configured; +- at least one valid trusted source is configured; +- a loopback listener has a loopback trusted source; and +- use of a loopback source is explicitly allowed. + +Stable false reasons are `TrustedProxyAuthMissing`, +`TrustedProxyHeaderMissing`, `TrustedProxySourcesMissing`, and +`TrustedProxyIngressUnsafe`. + +This validates effective static auth configuration. Request-time Gateway auth +continues to reject untrusted sources and forged identity headers. + +### Node Mode + +One correlated approved pairing, connected target, effective command grant, +and live session must satisfy all four predicates. Separate targets cannot +satisfy different rows. + +| Condition | True when | Stable non-ready reasons | +| --- | --- | --- | +| `NodePairingReady` | Pairing state is readable and contains an approved pairing. | `NodePairingUnavailable`, `NodePairingTimedOut`, `NodePairingPending`, `NodePairingMissing` | +| `ControlledTargetsReady` | A connected target correlates to an approved pairing generation. | `ControlledTargetsDisconnected` | +| `CommandApprovalReady` | A connected paired target advertises a command allowed by effective grants. | `CommandApprovalMissing` | +| `ControlChannelReady` | A live target session correlates to an approved pairing. | `ControlChannelUnavailable` | + +Evaluation uses current cached runtime and pairing state. It does not perform +network discovery or wait for a target. Pairing reads are bounded, +single-flight, and limited to two unresolved generations after timeout. + +## Subject Attribution + +Profiles reuse the RFC 0018 identity package. They do not define `runtimeId`, +`incarnationId`, or another activation object. + +Every selected profile declares: ```ts -type RuntimeActivationSummary = { - runtimeId: string; - incarnationId: string; - profile: string; -}; +{ + ref: "openclaw/hosting-profile/selected"; + kind: "openclaw.hosting-profile"; + id: "local" | "container" | "reverse-proxy" | "node-mode"; + generation: "1"; + parentRef: "openclaw/gateway/current"; +} ``` -Launchers may provide identity through startup arguments or environment. -Absent values receive runtime-owned defaults: the logical runtime ID is -`local`, and the incarnation ID is unique to the current process activation. -Explicit invalid identity must fail startup instead of silently falling back. +`ProfileSelected` targets this subject. Container and proxy conditions target +the Gateway and include the profile subject in `relatedSubjectRefs`. -Logical runtime identity may survive replacement. Incarnation identity must be -unique for each process/container activation. OCC may supply these values, but -the OpenClaw runtime plane evaluates and reports the live activation. +Node mode also declares: -## Operator Extensions +- `openclaw/nodes/managed`, kind `openclaw.node-controller`, parented by the + Gateway; and +- a bounded child subject for each paired node observed during evaluation, + with its pairing generation when available. + +Node-mode aggregate conditions target `openclaw/nodes/managed` and list the +observed node subjects as related subjects. Node IDs must not be copied into a +subject ref; implementations use a deterministic bounded opaque key. -V1 supports only the four OpenClaw-owned standard profile names. Operators may -add required or advisory RFC 0018 criteria directly through -`gateway.readiness`, including while a standard profile is selected. Named -operator profiles and inheritance may be proposed later; they are not part of -this contract and cannot be inferred from arbitrary config. +The Gateway serving-lifecycle identity is owned by RFC 0018. A host may supply +`OPENCLAW_INSTANCE_ID`; otherwise OpenClaw generates the Gateway ID. It remains +stable across repeated readiness evaluations, config reload, and drain, and +changes after process restart. ## Host-Visible Result -The canonical readiness result may add these optional v1 profile fields: +A profiled canonical result adds: ```ts type ProfiledReadinessResult = ReadinessResult & { profileContractVersion: 1; - profile: string; + profile: "local" | "container" | "reverse-proxy" | "node-mode"; profileSource: "argument" | "environment" | "config"; - activation: RuntimeActivationSummary; }; ``` -For example, a selected container profile with a loopback-only listener returns -`503` and includes: +The identity package carries runtime attribution. For example, a container +profile with a loopback listener returns `503`: ```json { @@ -269,14 +214,23 @@ For example, a selected container profile with a loopback-only listener returns "profile": "container", "profileSource": "config", "ready": false, - "activation": { - "runtimeId": "worker-17", - "incarnationId": "01J...", - "profile": "container" + "identity": { + "producerRef": "openclaw/gateway/current", + "subjects": [ + { + "ref": "openclaw/hosting-profile/selected", + "kind": "openclaw.hosting-profile", + "id": "container", + "generation": "1", + "parentRef": "openclaw/gateway/current" + } + ] }, "conditions": [ { "type": "ContainerStateReady", + "subjectRef": "openclaw/gateway/current", + "relatedSubjectRefs": ["openclaw/hosting-profile/selected"], "status": "False", "requirement": "required", "reason": "ContainerGatewayLoopback", @@ -288,68 +242,52 @@ For example, a selected container profile with a loopback-only listener returns } ``` -After the listener satisfies the predicate, the same readiness endpoint returns -`200`. Hosts consume the canonical endpoint and do not need a profile-specific -probe API. +After the listener satisfies the predicate, the same endpoint returns `200`. +Hosts use canonical readiness and do not need a profile-specific probe API. +If evaluation times out or throws, the result remains `503` and retains the +selected profile metadata and profile subject. -Unauthenticated remote projections may redact profile source, activation, and -condition detail while preserving the correct status code. - -## Packaged Scenario Gate +## Operator Extensions -A standard profile is a credible support promise only when the packaged -release path exercises it. V1 adds one Docker E2E lane to the release-check -matrix. The lane starts the packaged OpenClaw entrypoint and probes the same -canonical `/readyz` result used by hosts; runtime readiness does not rerun the -release tests or claim artifact attestation. +V1 supports only the four standard names. Operators may add required or +advisory RFC 0018 criteria directly through `gateway.readiness`, including +while a profile is selected. Named operator profiles and inheritance are not +part of V1. -### Minimum V1 Matrix +## Packaged Scenario Gate -The packaged matrix must prove: +The package-installed Docker lane probes the same canonical `/readyz` result +used by hosts. It must prove: -- unchanged unprofiled readiness; -- explicit `local` success and writable-workspace failure/recovery; -- `container` success and loopback-listener failure; +- unchanged unprofiled behavior; +- explicit `local` success and workspace failure/recovery; +- `container` success and loopback failure; - `reverse-proxy` success and missing-auth failure; - `node-mode` unpaired/unapproved failure and paired/approved recovery; -- activation identity and machine-readable profile fields; and -- exact profile condition status and profile contract version on `/readyz`. +- stable profile metadata and subject attribution; and +- exact condition status and profile contract version. -Upgrade survival, direct-ingress security tests, cross-surface parity, immutable -artifact records, and signed attestations are valuable follow-up gates, not V1 -runtime semantics. +Upgrade survival, direct-ingress security, immutable records, and signed +attestations are follow-up gates, not V1 runtime semantics. ## Ownership -OpenClaw owns: - -- standard profile IDs and definitions; -- profile-specific predicates and stable reasons; -- selection precedence and projection; -- activation identity semantics; and -- the packaged scenario lane for the standard catalog. - -Hosts own: - -- profile selection; -- container and scheduler manifests; -- probe timing, retries, and restart policy; -- placement, routing, tenants, and rollout; -- telemetry sinks and fleet alerts; and -- any additional operator-selected RFC 0018 criteria. +OpenClaw owns profile IDs, predicates, reasons, precedence, subject attribution, +projection, and packaged scenarios. Hosts own selection, manifests, probe +timing, restart policy, placement, tenants, rollout, telemetry, and additional +operator-selected RFC 0018 criteria. ## Conformance Checklist -An implementation conforms to Hosting Profile v1 when it proves: - -- no profile is selected by default or by upgrade; -- each selection source works and precedence is deterministic; -- invalid explicit profile or identity fails startup validation; -- every standard profile composes the exact documented criteria; -- profiled results identify logical runtime and unique incarnation; -- profile failures use stable reasons and canonical readiness aggregation; -- all host-visible surfaces describe the same activation and profile result; -- the packaged scenario lane exercises every standard profile and its primary - failure/recovery path; and -- unprofiled deployments retain RFC 0018 behavior without profile-only - conditions. +- No profile is selected by default or upgrade. +- Every selection source works with deterministic precedence. +- Invalid explicit profiles fail startup validation. +- Every profile composes the documented criteria. +- Every profiled result identifies its profile through metadata and subjects. +- Node conditions identify the observed controller and related node set. +- Profile failures use stable reasons and canonical aggregation. +- Timeout and exception results remain bounded, fail closed, and retain profile + attribution. +- Readiness, health, and status project the same profile result. +- Packaged scenarios exercise each profile's primary success and recovery path. +- Unprofiled deployments retain RFC 0018 behavior. From 74fad052559b57c73d3c1434ca085b33193087cf Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 25 Jul 2026 16:47:23 -0700 Subject: [PATCH 32/52] docs(rfc-0023): advance profile implementation head --- rfcs/0023-standard-hosting-profiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 99c790c2..2ef9aa9a 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -374,7 +374,7 @@ It depends on the readiness framework in at exact head `13b0acaa00f3` and the core-owner criteria in [openclaw/openclaw#113421](https://github.com/openclaw/openclaw/pull/113421) -at exact head `dbd540b18a0b`. The exact profile head is `fb1e60db1795`. +at exact head `dbd540b18a0b`. The exact profile head is `b58e109a11e2`. | Slice | Intended scope | | --- | --- | From bd813ef3bc8e36846144fdc0368ee277dbe469bf Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 25 Jul 2026 17:22:39 -0700 Subject: [PATCH 33/52] docs(rfc-0023): track latest main restack --- rfcs/0023-standard-hosting-profiles.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 2ef9aa9a..dde8e89a 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -371,10 +371,10 @@ single dependent series in [openclaw/openclaw#113422](https://github.com/openclaw/openclaw/pull/113422). It depends on the readiness framework in [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -at exact head `13b0acaa00f3` +at exact head `ddadb96d0f64` and the core-owner criteria in [openclaw/openclaw#113421](https://github.com/openclaw/openclaw/pull/113421) -at exact head `dbd540b18a0b`. The exact profile head is `b58e109a11e2`. +at exact head `822d5a20d959`. The exact profile head is `39d77d139e38`. | Slice | Intended scope | | --- | --- | From 170719c2d3ea57f81421acd6f84ca419a4589fa9 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 25 Jul 2026 17:44:00 -0700 Subject: [PATCH 34/52] docs(rfc-0023): record current-main implementation heads --- rfcs/0023-standard-hosting-profiles.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index dde8e89a..0690c58c 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -371,10 +371,10 @@ single dependent series in [openclaw/openclaw#113422](https://github.com/openclaw/openclaw/pull/113422). It depends on the readiness framework in [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -at exact head `ddadb96d0f64` +at exact head `e5834f2a18e7` and the core-owner criteria in [openclaw/openclaw#113421](https://github.com/openclaw/openclaw/pull/113421) -at exact head `822d5a20d959`. The exact profile head is `39d77d139e38`. +at exact head `24970fe0ee47`. The exact profile head is `fdbaef42e87e`. | Slice | Intended scope | | --- | --- | From 557611e68d8f0f8fe867c24ac0d89c346d4845de Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 25 Jul 2026 18:19:29 -0700 Subject: [PATCH 35/52] docs(rfc-0023): refresh implementation stack --- rfcs/0023-standard-hosting-profiles.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 0690c58c..bfc3e180 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -371,10 +371,10 @@ single dependent series in [openclaw/openclaw#113422](https://github.com/openclaw/openclaw/pull/113422). It depends on the readiness framework in [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -at exact head `e5834f2a18e7` +at exact head `c65456659cfd` and the core-owner criteria in [openclaw/openclaw#113421](https://github.com/openclaw/openclaw/pull/113421) -at exact head `24970fe0ee47`. The exact profile head is `fdbaef42e87e`. +at exact head `2b32ecce5745`. The exact profile head is `810a9fe7dfbe`. | Slice | Intended scope | | --- | --- | From 01e1e895a6ab7748c7d9dfc485a724ecb47b459b Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 25 Jul 2026 18:34:50 -0700 Subject: [PATCH 36/52] docs(rfc-0023): align final hosting heads --- rfcs/0023-standard-hosting-profiles.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index bfc3e180..0c72cbc2 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -371,10 +371,10 @@ single dependent series in [openclaw/openclaw#113422](https://github.com/openclaw/openclaw/pull/113422). It depends on the readiness framework in [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -at exact head `c65456659cfd` +at exact head `57d627464a23` and the core-owner criteria in [openclaw/openclaw#113421](https://github.com/openclaw/openclaw/pull/113421) -at exact head `2b32ecce5745`. The exact profile head is `810a9fe7dfbe`. +at exact head `9257236adfa5`. The exact profile head is `f9fa47f8c03b`. | Slice | Intended scope | | --- | --- | From 32f269ce5ff111d5ef2043a6e13d5e8c1f549bcb Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 25 Jul 2026 18:48:20 -0700 Subject: [PATCH 37/52] docs(rfc-0023): align final hosting stack --- rfcs/0023-standard-hosting-profiles.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 0c72cbc2..9f6067d8 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -371,10 +371,10 @@ single dependent series in [openclaw/openclaw#113422](https://github.com/openclaw/openclaw/pull/113422). It depends on the readiness framework in [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -at exact head `57d627464a23` +at exact head `ca05a31a9b73` and the core-owner criteria in [openclaw/openclaw#113421](https://github.com/openclaw/openclaw/pull/113421) -at exact head `9257236adfa5`. The exact profile head is `f9fa47f8c03b`. +at exact head `0baf0be2c17e`. The exact profile head is `a601aaab42bf`. | Slice | Intended scope | | --- | --- | From e413dd4bc5d415d640bc9edd9603fce6d9812b23 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 25 Jul 2026 18:56:15 -0700 Subject: [PATCH 38/52] docs(rfc-0023): refresh dependent stack heads --- rfcs/0023-standard-hosting-profiles.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 9f6067d8..463a6dd3 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -371,10 +371,10 @@ single dependent series in [openclaw/openclaw#113422](https://github.com/openclaw/openclaw/pull/113422). It depends on the readiness framework in [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -at exact head `ca05a31a9b73` +at exact head `28ad0cf76fa9` and the core-owner criteria in [openclaw/openclaw#113421](https://github.com/openclaw/openclaw/pull/113421) -at exact head `0baf0be2c17e`. The exact profile head is `a601aaab42bf`. +at exact head `debd3a56a098`. The exact profile head is `812d61a2b473`. | Slice | Intended scope | | --- | --- | From f51a42d757ee8a4bccb115b080ac8a1e38db47b6 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sat, 25 Jul 2026 22:05:59 -0700 Subject: [PATCH 39/52] docs(rfc-0023): align profiles with readiness identity --- rfcs/0023-standard-hosting-profiles.md | 4 +-- rfcs/0023/hosting-profile-v1-spec.md | 37 ++++++++++++++++++-------- 2 files changed, 28 insertions(+), 13 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 463a6dd3..6991ccf2 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -371,10 +371,10 @@ single dependent series in [openclaw/openclaw#113422](https://github.com/openclaw/openclaw/pull/113422). It depends on the readiness framework in [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -at exact head `28ad0cf76fa9` +at exact head `673e7a8c1ef2` and the core-owner criteria in [openclaw/openclaw#113421](https://github.com/openclaw/openclaw/pull/113421) -at exact head `debd3a56a098`. The exact profile head is `812d61a2b473`. +at exact head `c398dd2c204c`. The exact profile head is `d0522c50b41f`. | Slice | Intended scope | | --- | --- | diff --git a/rfcs/0023/hosting-profile-v1-spec.md b/rfcs/0023/hosting-profile-v1-spec.md index cd4b915f..5678a543 100644 --- a/rfcs/0023/hosting-profile-v1-spec.md +++ b/rfcs/0023/hosting-profile-v1-spec.md @@ -169,29 +169,33 @@ Every selected profile declares: ref: "openclaw/hosting-profile/selected"; kind: "openclaw.hosting-profile"; id: "local" | "container" | "reverse-proxy" | "node-mode"; - generation: "1"; parentRef: "openclaw/gateway/current"; } ``` `ProfileSelected` targets this subject. Container and proxy conditions target -the Gateway and include the profile subject in `relatedSubjectRefs`. +the Gateway and include the profile subject in `relatedSubjectRefs`. The +profile contract version is result metadata, not a generation of the selected +profile object. Node mode also declares: - `openclaw/nodes/managed`, kind `openclaw.node-controller`, parented by the Gateway; and -- a bounded child subject for each paired node observed during evaluation, - with its pairing generation when available. +- a deterministic subset of at most 16 paired node subjects observed during + evaluation, with a one-way fingerprint of pairing generation when available. Node-mode aggregate conditions target `openclaw/nodes/managed` and list the -observed node subjects as related subjects. Node IDs must not be copied into a -subject ref; implementations use a deterministic bounded opaque key. +observed node subjects as related subjects. Aggregate counts cover the complete +paired-node set even when related subjects are truncated. Node IDs must not be +copied into a subject ref; implementations use a deterministic bounded opaque +key and prioritize actionable disconnected subjects. -The Gateway serving-lifecycle identity is owned by RFC 0018. A host may supply -`OPENCLAW_INSTANCE_ID`; otherwise OpenClaw generates the Gateway ID. It remains -stable across repeated readiness evaluations, config reload, and drain, and -changes after process restart. +Gateway, process, and optional host-workload identities are owned by RFC 0018. +OpenClaw generates a Gateway ID at every serving-lifecycle start and a process +ID at process start. `OPENCLAW_INSTANCE_ID`, when supplied, becomes only a +fingerprinted host-workload subject; it never overrides either generated child +identity. ## Host-Visible Result @@ -210,6 +214,7 @@ profile with a loopback listener returns `503`: ```json { + "contractVersion": 1, "profileContractVersion": 1, "profile": "container", "profileSource": "config", @@ -217,11 +222,21 @@ profile with a loopback listener returns `503`: "identity": { "producerRef": "openclaw/gateway/current", "subjects": [ + { + "ref": "openclaw/process/current", + "kind": "openclaw.process", + "id": "process-opaque-id" + }, + { + "ref": "openclaw/gateway/current", + "kind": "openclaw.gateway", + "id": "gateway-opaque-id", + "parentRef": "openclaw/process/current" + }, { "ref": "openclaw/hosting-profile/selected", "kind": "openclaw.hosting-profile", "id": "container", - "generation": "1", "parentRef": "openclaw/gateway/current" } ] From df9dfc4d93e8f001f54b4ade79821d5dc70bf304 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sun, 26 Jul 2026 05:29:21 -0700 Subject: [PATCH 40/52] docs(rfc-0023): refresh implementation heads --- rfcs/0023-standard-hosting-profiles.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 6991ccf2..67e7db99 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -371,10 +371,10 @@ single dependent series in [openclaw/openclaw#113422](https://github.com/openclaw/openclaw/pull/113422). It depends on the readiness framework in [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -at exact head `673e7a8c1ef2` +at exact head `64bba7771598` and the core-owner criteria in [openclaw/openclaw#113421](https://github.com/openclaw/openclaw/pull/113421) -at exact head `c398dd2c204c`. The exact profile head is `d0522c50b41f`. +at exact head `25026844df5a`. The exact profile head is `0c237fa0c43a`. | Slice | Intended scope | | --- | --- | From faecba619e6bad69ddaafa70fc09b77acd5ef4b5 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sun, 26 Jul 2026 05:49:09 -0700 Subject: [PATCH 41/52] docs(rfc-0023): refresh implementation heads --- rfcs/0023-standard-hosting-profiles.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 67e7db99..ce6a6b8c 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -371,10 +371,10 @@ single dependent series in [openclaw/openclaw#113422](https://github.com/openclaw/openclaw/pull/113422). It depends on the readiness framework in [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -at exact head `64bba7771598` +at exact head `e94bea556ef5` and the core-owner criteria in [openclaw/openclaw#113421](https://github.com/openclaw/openclaw/pull/113421) -at exact head `25026844df5a`. The exact profile head is `0c237fa0c43a`. +at exact head `ecbf85a22d04`. The exact profile head is `8c148512df82`. | Slice | Intended scope | | --- | --- | From f5a7c277b00359bc3785f3fde4bcd187d5c0ae63 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sun, 26 Jul 2026 06:45:53 -0700 Subject: [PATCH 42/52] docs(rfc-0023): refresh implementation heads --- rfcs/0023-standard-hosting-profiles.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index ce6a6b8c..b76b85c7 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -371,10 +371,10 @@ single dependent series in [openclaw/openclaw#113422](https://github.com/openclaw/openclaw/pull/113422). It depends on the readiness framework in [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -at exact head `e94bea556ef5` +at exact head `78bb3d052979` and the core-owner criteria in [openclaw/openclaw#113421](https://github.com/openclaw/openclaw/pull/113421) -at exact head `ecbf85a22d04`. The exact profile head is `8c148512df82`. +at exact head `3f83761d559d`. The exact profile head is `e36be45e0b63`. | Slice | Intended scope | | --- | --- | From 4933f39282d84bba342655023ec5d10dd2fba4b5 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sun, 26 Jul 2026 06:53:44 -0700 Subject: [PATCH 43/52] docs(rfc-0023): align canonical CI heads --- rfcs/0023-standard-hosting-profiles.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index b76b85c7..6021fce3 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -371,10 +371,10 @@ single dependent series in [openclaw/openclaw#113422](https://github.com/openclaw/openclaw/pull/113422). It depends on the readiness framework in [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -at exact head `78bb3d052979` +at exact head `6dce3555a511` and the core-owner criteria in [openclaw/openclaw#113421](https://github.com/openclaw/openclaw/pull/113421) -at exact head `3f83761d559d`. The exact profile head is `e36be45e0b63`. +at exact head `3a450e8625a7`. The exact profile head is `7dd5bbd26b98`. | Slice | Intended scope | | --- | --- | From e2721ab02395dc2e417174659b1d2a167f7cca20 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sun, 26 Jul 2026 11:31:08 -0700 Subject: [PATCH 44/52] docs: record hosting profile package proof --- rfcs/0023-standard-hosting-profiles.md | 17 ++++++++++------- rfcs/0023/hosting-profile-v1-spec.md | 2 ++ 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 6021fce3..d895f54a 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -374,14 +374,14 @@ It depends on the readiness framework in at exact head `6dce3555a511` and the core-owner criteria in [openclaw/openclaw#113421](https://github.com/openclaw/openclaw/pull/113421) -at exact head `3a450e8625a7`. The exact profile head is `7dd5bbd26b98`. +at exact head `9cc02c5d89c`. The exact profile head is `e9c1988c5e59`. | Slice | Intended scope | | --- | --- | | Standard selection and predicates | Add opt-in selection, precedence, machine-readable projection, and `local`, `container`, and `reverse-proxy` conditions. | | Node mode | Add product-neutral pairing, connected-target, canonical command-policy, and control-channel conditions. | | Compatibility and safety | Keep unprofiled startup unchanged, validate profile-only identity only when selected, preserve attribution on failed evaluation, and bound pairing recovery work. | -| Packaged scenarios | Exercise all four profiles, primary failures, node approval, workspace-full recovery, and unprofiled compatibility. | +| Packaged scenarios | Exercise all four profiles, primary failures, node approval, workspace-full recovery, unprofiled compatibility, repeated-poll identity, and container-restart renewal boundaries. | PR 113422 is a stacked upstream draft against `main`. Until PRs 104018 and 113421 land, its aggregate GitHub diff includes both dependencies followed by @@ -394,11 +394,14 @@ preserves that exact profile-only comparison view. Fork PRs [#21](https://github.com/giodl73-repo/openclaw/pull/21) expose the major design slices as review aids; they are not alternative landing requests. -The refreshed stack passes focused profile, readiness, Gateway, config-help, -CLI, and Docker-plan tests; type-aware lint, formatting, and independent review -are clean. Package build and tarball-integrity stages pass. The exact-head -package-installed Docker matrix remains a landing gate because the available -local Docker Linux engine did not become ready. +The refreshed stack passes 120 focused profile, readiness, selection, and +Gateway assertions; type-aware lint, formatting, shell syntax, and diff checks +are clean. The +[exact-head package-installed Docker matrix](https://github.com/giodl73-repo/openclaw/actions/runs/30214165737) +passes on GitHub-hosted Actions at `e9c1988c5e59` using an immutable no-push +package/image artifact. It proves unprofiled compatibility, all four profiles, +expected failures, node approval, workspace recovery, stable repeated polls, +and host-stable/process-and-Gateway-rotating container restart identity. ## Rationale diff --git a/rfcs/0023/hosting-profile-v1-spec.md b/rfcs/0023/hosting-profile-v1-spec.md index 5678a543..6520ba08 100644 --- a/rfcs/0023/hosting-profile-v1-spec.md +++ b/rfcs/0023/hosting-profile-v1-spec.md @@ -280,6 +280,8 @@ used by hosts. It must prove: - `reverse-proxy` success and missing-auth failure; - `node-mode` unpaired/unapproved failure and paired/approved recovery; - stable profile metadata and subject attribution; and +- stable host/profile identity plus renewed process and Gateway identity when + the same host workload restarts; and - exact condition status and profile contract version. Upgrade survival, direct-ingress security, immutable records, and signed From 6a6ebf2b0a2e86d91240dbfa40e463cbe3c16166 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Sun, 26 Jul 2026 15:08:10 -0700 Subject: [PATCH 45/52] docs(profiles): define conformance facilities roadmap --- rfcs/0023-standard-hosting-profiles.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index d895f54a..ee21c0a4 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -403,6 +403,27 @@ package/image artifact. It proves unprofiled compatibility, all four profiles, expected failures, node approval, workspace recovery, stable repeated polls, and host-stable/process-and-Gateway-rotating container restart identity. +#### Operator and conformance facilities roadmap + +The standard catalog becomes easier to support when operators and release +automation can inspect and validate it without reproducing profile predicates: + +1. Add read-only `hosting profile list` and `hosting profile inspect` surfaces + over the built-in definitions, selected criteria, startup requirements, and + support metadata. +2. Add `hosting profile validate` over effective configuration and the live RFC + 0018 canonical readiness result. Validation reports conformance; it does not + mutate configuration or run a second evaluator. +3. Emit one machine-readable conformance artifact suitable for Docker, + Kubernetes, OCC, Lobster, CI, support bundles, and release qualification. +4. Gate every built-in profile through package-installed release scenarios and + preserve the evidence with the released artifact. + +Transition watching, generic condition/provider inspection, and startup wait +remain RFC 0018 facilities. Doctor remediation, fleet telemetry, support +bundles, and upgrade orchestration remain with their existing owners and may +consume the same readiness and conformance evidence. + ## Rationale Named profiles are useful because OpenClaw's configuration space is much larger From ef6e911707ab22141a23a062558fde2b01c4b2f9 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Mon, 27 Jul 2026 07:04:16 -0700 Subject: [PATCH 46/52] docs(hosting): specify profile catalog inspection --- rfcs/0023-standard-hosting-profiles.md | 33 +++++++++++++--- rfcs/0023/hosting-profile-v1-spec.md | 53 ++++++++++++++++++++++++++ 2 files changed, 81 insertions(+), 5 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index ee21c0a4..16b1d26a 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -140,6 +140,28 @@ condition predicates, packaged conformance scenarios, and an owner willing to maintain the support promise. A new diagnostic condition alone does not justify a new profile. +### Catalog inspection + +The standard catalog is a machine-readable support contract, not only a set of +internal constants. OpenClaw exposes it through local, read-only commands: + +```console +openclaw hosting profiles list +openclaw hosting profiles inspect +``` + +Both commands support human output and `--json`. The JSON contract identifies +its version and returns immutable descriptor copies containing the profile ID, +runtime-posture description, profile-owned conditions, required RFC 0018 +criteria, and advisory RFC 0018 criteria. Stable catalog order follows the +documented `local`, `container`, `reverse-proxy`, and `node-mode` order. + +Inspection does not load configuration or plugins, contact a Gateway, evaluate +readiness, infer active selection, or mutate state. The running Gateway remains +the authority for the selected profile and reports it through canonical +readiness. Catalog/runtime alignment is tested by deriving profile conditions +from the same shipped definitions used to build readiness. + ### Profile conditions The standard catalog composes conditions owned by the canonical readiness @@ -403,15 +425,16 @@ package/image artifact. It proves unprofiled compatibility, all four profiles, expected failures, node approval, workspace recovery, stable repeated polls, and host-stable/process-and-Gateway-rotating container restart identity. -#### Operator and conformance facilities roadmap +#### Operator and conformance facilities The standard catalog becomes easier to support when operators and release automation can inspect and validate it without reproducing profile predicates: -1. Add read-only `hosting profile list` and `hosting profile inspect` surfaces - over the built-in definitions, selected criteria, startup requirements, and - support metadata. -2. Add `hosting profile validate` over effective configuration and the live RFC +1. Read-only `hosting profiles list` and `hosting profiles inspect` surfaces + expose the built-in definitions and selected criteria. The implementation is + available in [fork PR 173](https://github.com/giodl73-repo/openclaw/pull/173) + at exact head `99449434cb4c`. +2. Add `hosting profiles validate` over effective configuration and the live RFC 0018 canonical readiness result. Validation reports conformance; it does not mutate configuration or run a second evaluator. 3. Emit one machine-readable conformance artifact suitable for Docker, diff --git a/rfcs/0023/hosting-profile-v1-spec.md b/rfcs/0023/hosting-profile-v1-spec.md index 6520ba08..4b3c05fc 100644 --- a/rfcs/0023/hosting-profile-v1-spec.md +++ b/rfcs/0023/hosting-profile-v1-spec.md @@ -269,6 +269,55 @@ advisory RFC 0018 criteria directly through `gateway.readiness`, including while a profile is selected. Named operator profiles and inheritance are not part of V1. +## Catalog Inspection + +OpenClaw exposes the shipped standard catalog through these local, read-only +commands: + +```console +openclaw hosting profiles list [--json] +openclaw hosting profiles inspect [--json] +``` + +`list --json` returns: + +```ts +{ + contractVersion: 1; + profiles: HostingProfileDescriptor[]; +} +``` + +`inspect --json` returns: + +```ts +{ + contractVersion: 1; + profile: HostingProfileDescriptor; +} +``` + +Each descriptor contains: + +```ts +type HostingProfileDescriptor = { + id: "local" | "container" | "reverse-proxy" | "node-mode"; + description: string; + profileConditions: string[]; + requiredCriteria: string[]; + advisoryCriteria: string[]; +}; +``` + +Catalog order is `local`, `container`, `reverse-proxy`, then `node-mode`. +Callers receive copies and cannot mutate the shipped definitions. Every +descriptor's `profileConditions` exactly matches the conditions constructed by +the runtime for that profile. + +Inspection is observationally inert: it does not load configuration or plugins, +contact a Gateway, evaluate readiness, infer active selection, or mutate state. +The selected profile and its runtime result remain canonical readiness data. + ## Packaged Scenario Gate The package-installed Docker lane probes the same canonical `/readyz` result @@ -300,6 +349,10 @@ operator-selected RFC 0018 criteria. - Every selection source works with deterministic precedence. - Invalid explicit profiles fail startup validation. - Every profile composes the documented criteria. +- Catalog list and inspect output is versioned, stably ordered, and immutable to + callers. +- Catalog profile conditions exactly match the runtime conditions constructed + for the same profile. - Every profiled result identifies its profile through metadata and subjects. - Node conditions identify the observed controller and related node set. - Profile failures use stable reasons and canonical aggregation. From b2e67cb2de9e205739d02a6a9d8544b923e01238 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Mon, 27 Jul 2026 07:41:04 -0700 Subject: [PATCH 47/52] docs(hosting): specify live profile validation --- rfcs/0023-standard-hosting-profiles.md | 25 ++++++++++++-- rfcs/0023/hosting-profile-v1-spec.md | 47 ++++++++++++++++++++++++++ 2 files changed, 69 insertions(+), 3 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 16b1d26a..cabd8f5a 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -162,6 +162,21 @@ the authority for the selected profile and reports it through canonical readiness. Catalog/runtime alignment is tested by deriving profile conditions from the same shipped definitions used to build readiness. +Operators validate a running profile through: + +```console +openclaw hosting profiles validate [profile] +``` + +The optional argument requires an exact active profile. Validation calls the +canonical `ready` RPC once, verifies the readiness schema, profile identity and +contract version, and required profile-condition coverage, then reports +`conformant` separately from `ready`. Both false states exit nonzero. A +conformant profile may still be non-ready because a required condition is +currently false. Validation embeds the canonical result as evidence and does +not load local configuration or plugins, reproduce predicates, or invoke a +second evaluator. + ### Profile conditions The standard catalog composes conditions owned by the canonical readiness @@ -434,9 +449,13 @@ automation can inspect and validate it without reproducing profile predicates: expose the built-in definitions and selected criteria. The implementation is available in [fork PR 173](https://github.com/giodl73-repo/openclaw/pull/173) at exact head `99449434cb4c`. -2. Add `hosting profiles validate` over effective configuration and the live RFC - 0018 canonical readiness result. Validation reports conformance; it does not - mutate configuration or run a second evaluator. +2. `hosting profiles validate` checks active identity, version, condition + coverage, and readiness over one live RFC 0018 canonical result. The + implementation is available in + [fork PR 174](https://github.com/giodl73-repo/openclaw/pull/174) at exact head + `84227d246d00`; its + [exact-head proof](https://github.com/giodl73-repo/openclaw/actions/runs/30275850209) + passes. It does not mutate configuration or run a second evaluator. 3. Emit one machine-readable conformance artifact suitable for Docker, Kubernetes, OCC, Lobster, CI, support bundles, and release qualification. 4. Gate every built-in profile through package-installed release scenarios and diff --git a/rfcs/0023/hosting-profile-v1-spec.md b/rfcs/0023/hosting-profile-v1-spec.md index 4b3c05fc..1d5db9ac 100644 --- a/rfcs/0023/hosting-profile-v1-spec.md +++ b/rfcs/0023/hosting-profile-v1-spec.md @@ -318,6 +318,49 @@ Inspection is observationally inert: it does not load configuration or plugins, contact a Gateway, evaluate readiness, infer active selection, or mutate state. The selected profile and its runtime result remain canonical readiness data. +## Live Profile Validation + +OpenClaw validates a running Gateway through: + +```console +openclaw hosting profiles validate [profile] [--json] [--timeout ] +``` + +With no profile argument, the exact profile ID in canonical readiness is used. +With an argument, that profile must be active. Input parsing may normalize CLI +text, but Gateway-produced profile identity must exactly match a standard +catalog ID. + +Validation calls the canonical `ready` RPC once. It does not load local +configuration or plugins, reproduce profile predicates, or invoke another +evaluator. It verifies: + +- canonical readiness schema version and structure; +- exact standard profile identity and profile contract version; and +- one required condition row for every `profileConditions` entry in the + descriptor. + +`--json` returns: + +```ts +{ + contractVersion: 1; + conformant: boolean; + ready: boolean; + expectedProfile?: string; + activeProfile?: string; + findings: Array<{ reason: string; message: string }>; + readiness?: unknown; +} +``` + +`conformant` is false for unavailable or malformed readiness, no active +profile, unknown or mismatched profile identity, contract mismatch, or missing, +duplicate, or non-required profile conditions. `ready` is true only when the +canonical evidence is structurally valid and its serving decision is true. +Both false states exit nonzero. A structurally conformant profile whose current +required condition is false reports `conformant: true`, `ready: false`. + ## Packaged Scenario Gate The package-installed Docker lane probes the same canonical `/readyz` result @@ -353,6 +396,10 @@ operator-selected RFC 0018 criteria. callers. - Catalog profile conditions exactly match the runtime conditions constructed for the same profile. +- Live validation consumes one canonical readiness result and never invokes a + second evaluator. +- Validation fails closed on unavailable, malformed, mismatched, or incomplete + evidence and never reports malformed evidence as ready. - Every profiled result identifies its profile through metadata and subjects. - Node conditions identify the observed controller and related node set. - Profile failures use stable reasons and canonical aggregation. From 3130f0faa854c7fd837435ccbf1ce0c9066eee3c Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Mon, 27 Jul 2026 09:05:19 -0700 Subject: [PATCH 48/52] docs(rfc): specify profile conformance evidence --- rfcs/0023-standard-hosting-profiles.md | 59 +++++++++++++++---------- rfcs/0023/hosting-profile-v1-spec.md | 61 ++++++++++++++++++++++++-- 2 files changed, 95 insertions(+), 25 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index cabd8f5a..09ff994f 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -329,8 +329,9 @@ interpreting a profile-specific API. A standard profile is a support promise only if the release process tests it. V1 adds one Docker E2E lane to the release-check matrix. It starts the packaged -OpenClaw entrypoint and validates the ordinary canonical `/readyz` result; -runtime readiness does not rerun release tests or claim artifact attestation. +OpenClaw entrypoint, validates the ordinary canonical `/readyz` result, and +invokes the packaged `hosting profiles validate --json` command. Runtime +readiness does not rerun release tests or claim artifact attestation. The initial profile matrix must execute package-installed scenarios for: @@ -340,10 +341,17 @@ The initial profile matrix must execute package-installed scenarios for: - node-mode unpaired failure and paired/approved recovery; and - workspace-full failure and recovery without restart. -The implementation wires this lane into package acceptance. Upgrade survival, -cross-surface parity, direct-ingress security scenarios, immutable records, and -signed attestations can strengthen the support program later without expanding -the V1 runtime contract. +The implementation wires this lane into package acceptance and emits one +versioned `hosting-profile-conformance.json` artifact. The artifact identifies +the package and immutable Docker image, retains expected and observed +validation plus canonical readiness evidence for every scenario, and is marked +passed only after the exact matrix is complete. Expected non-ready states pass +the release gate only when they remain structurally conformant and report +`ready: false`. + +Upgrade survival, cross-surface parity, direct-ingress security scenarios, +immutable records, and signed attestations can strengthen the support program +later without expanding the V1 runtime contract. ### Support ownership and compatibility @@ -408,17 +416,17 @@ single dependent series in [openclaw/openclaw#113422](https://github.com/openclaw/openclaw/pull/113422). It depends on the readiness framework in [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -at exact head `6dce3555a511` +at exact head `59b02212b1f` and the core-owner criteria in [openclaw/openclaw#113421](https://github.com/openclaw/openclaw/pull/113421) -at exact head `9cc02c5d89c`. The exact profile head is `e9c1988c5e59`. +at exact head `7350b4cd744b`. The exact profile head is `b8d9808e1922`. | Slice | Intended scope | | --- | --- | | Standard selection and predicates | Add opt-in selection, precedence, machine-readable projection, and `local`, `container`, and `reverse-proxy` conditions. | | Node mode | Add product-neutral pairing, connected-target, canonical command-policy, and control-channel conditions. | | Compatibility and safety | Keep unprofiled startup unchanged, validate profile-only identity only when selected, preserve attribution on failed evaluation, and bound pairing recovery work. | -| Packaged scenarios | Exercise all four profiles, primary failures, node approval, workspace-full recovery, unprofiled compatibility, repeated-poll identity, and container-restart renewal boundaries. | +| Packaged scenarios | Exercise all four profiles, primary failures, node approval, workspace-full recovery, unprofiled compatibility, repeated-poll identity, and container-restart renewal boundaries; retain one fail-closed release artifact. | PR 113422 is a stacked upstream draft against `main`. Until PRs 104018 and 113421 land, its aggregate GitHub diff includes both dependencies followed by @@ -434,11 +442,12 @@ slices as review aids; they are not alternative landing requests. The refreshed stack passes 120 focused profile, readiness, selection, and Gateway assertions; type-aware lint, formatting, shell syntax, and diff checks are clean. The -[exact-head package-installed Docker matrix](https://github.com/giodl73-repo/openclaw/actions/runs/30214165737) -passes on GitHub-hosted Actions at `e9c1988c5e59` using an immutable no-push -package/image artifact. It proves unprofiled compatibility, all four profiles, -expected failures, node approval, workspace recovery, stable repeated polls, -and host-stable/process-and-Gateway-rotating container restart identity. +[exact-head package-installed Docker matrix](https://github.com/giodl73-repo/openclaw/actions/runs/30281595193) +passes on GitHub-hosted Actions over profile head `b8d9808e1922` using an +immutable no-push package/image artifact. It proves unprofiled compatibility, +all four profiles, expected failures, node approval, workspace recovery, stable +repeated polls, and host-stable/process-and-Gateway-rotating container restart +identity. #### Operator and conformance facilities @@ -448,18 +457,24 @@ automation can inspect and validate it without reproducing profile predicates: 1. Read-only `hosting profiles list` and `hosting profiles inspect` surfaces expose the built-in definitions and selected criteria. The implementation is available in [fork PR 173](https://github.com/giodl73-repo/openclaw/pull/173) - at exact head `99449434cb4c`. + at exact head `afaf7d1269af`. 2. `hosting profiles validate` checks active identity, version, condition coverage, and readiness over one live RFC 0018 canonical result. The implementation is available in [fork PR 174](https://github.com/giodl73-repo/openclaw/pull/174) at exact head - `84227d246d00`; its - [exact-head proof](https://github.com/giodl73-repo/openclaw/actions/runs/30275850209) - passes. It does not mutate configuration or run a second evaluator. -3. Emit one machine-readable conformance artifact suitable for Docker, - Kubernetes, OCC, Lobster, CI, support bundles, and release qualification. -4. Gate every built-in profile through package-installed release scenarios and - preserve the evidence with the released artifact. + `64cc6b4e8cd9`; the + [package-installed proof](https://github.com/giodl73-repo/openclaw/actions/runs/30281595193) + exercises that exact validator ancestor. It does not mutate configuration or + run a second evaluator. +3. Package-installed release conformance invokes the canonical validator for + all 13 scenario states and retains one machine-readable artifact suitable + for Docker, Kubernetes, OCC, Lobster, CI, support bundles, and release + qualification. The implementation is available in + [fork PR 176](https://github.com/giodl73-repo/openclaw/pull/176) at exact head + `890d042267c`; its + [exact-head package-installed Docker proof](https://github.com/giodl73-repo/openclaw/actions/runs/30281595193) + passes all 13 scenarios, independently verifies the artifact, and uploads it + as release evidence. Transition watching, generic condition/provider inspection, and startup wait remain RFC 0018 facilities. Doctor remediation, fleet telemetry, support diff --git a/rfcs/0023/hosting-profile-v1-spec.md b/rfcs/0023/hosting-profile-v1-spec.md index 1d5db9ac..ede20ba6 100644 --- a/rfcs/0023/hosting-profile-v1-spec.md +++ b/rfcs/0023/hosting-profile-v1-spec.md @@ -343,7 +343,7 @@ evaluator. It verifies: `--json` returns: ```ts -{ +type LiveProfileValidationResult = { contractVersion: 1; conformant: boolean; ready: boolean; @@ -351,7 +351,7 @@ evaluator. It verifies: activeProfile?: string; findings: Array<{ reason: string; message: string }>; readiness?: unknown; -} +}; ``` `conformant` is false for unavailable or malformed readiness, no active @@ -364,7 +364,8 @@ required condition is false reports `conformant: true`, `ready: false`. ## Packaged Scenario Gate The package-installed Docker lane probes the same canonical `/readyz` result -used by hosts. It must prove: +used by hosts and invokes `openclaw hosting profiles validate --json` against +each stable scenario state. It must prove: - unchanged unprofiled behavior; - explicit `local` success and workspace failure/recovery; @@ -376,6 +377,58 @@ used by hosts. It must prove: the same host workload restarts; and - exact condition status and profile contract version. +The lane writes one `hosting-profile-conformance.json` artifact: + +```ts +{ + contractVersion: 1; + suite: "openclaw-standard-hosting-profiles"; + profileContractVersion: 1; + package: { + name: "openclaw"; + version: string; + sha256?: string; + }; + image: { + reference: string; + id: `sha256:${string}`; + }; + scenarios: Array<{ + id: string; + expected: { + profile?: string; + conformant: boolean; + ready: boolean; + exitCode: number; + }; + observed: { + exitCode: number; + validation: LiveProfileValidationResult; + }; + passed: boolean; + mismatches?: string[]; + }>; + summary: { + total: number; + passed: number; + failed: number; + }; + passed: boolean; +} +``` + +The candidate package SHA-256 is present when the package path is available; +the immutable Docker image ID is always present. The writer independently +validates the canonical readiness fields, validation findings, profile +identity, conformance state, readiness state, and command exit before accepting +a scenario. It writes mismatch evidence before failing and sets top-level +`passed: true` only after the exact required scenario set is complete. + +Expected non-ready scenarios are successful conformance evidence only when the +profile is structurally conformant, `ready` is false, and the validator exits +nonzero. The artifact is portable release evidence, not an immutable or signed +attestation. + Upgrade survival, direct-ingress security, immutable records, and signed attestations are follow-up gates, not V1 runtime semantics. @@ -407,4 +460,6 @@ operator-selected RFC 0018 criteria. attribution. - Readiness, health, and status project the same profile result. - Packaged scenarios exercise each profile's primary success and recovery path. +- The packaged gate retains one complete, versioned, fail-closed conformance + artifact with package and image provenance. - Unprofiled deployments retain RFC 0018 behavior. From 0dfdb0bd2414d919a0067818c6ec04be44c46c27 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Mon, 27 Jul 2026 09:32:05 -0700 Subject: [PATCH 49/52] docs(rfc): link combined profile tooling PR --- rfcs/0023-standard-hosting-profiles.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 09ff994f..74b842fb 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -428,7 +428,7 @@ at exact head `7350b4cd744b`. The exact profile head is `b8d9808e1922`. | Compatibility and safety | Keep unprofiled startup unchanged, validate profile-only identity only when selected, preserve attribution on failed evaluation, and bound pairing recovery work. | | Packaged scenarios | Exercise all four profiles, primary failures, node approval, workspace-full recovery, unprofiled compatibility, repeated-poll identity, and container-restart renewal boundaries; retain one fail-closed release artifact. | -PR 113422 is a stacked upstream draft against `main`. Until PRs 104018 and +PR 113422 is a stacked upstream PR against `main`. Until PRs 104018 and 113421 land, its aggregate GitHub diff includes both dependencies followed by the profile commits. After both land, the same PR reduces to the profile-only diff. [Fork PR 157](https://github.com/giodl73-repo/openclaw/pull/157) @@ -454,6 +454,10 @@ identity. The standard catalog becomes easier to support when operators and release automation can inspect and validate it without reproducing profile predicates: +The three facilities below are one ordered upstream review unit in +[openclaw/openclaw#114636](https://github.com/openclaw/openclaw/pull/114636) at +exact head `890d042267c`. The fork PRs remain smaller comparison views. + 1. Read-only `hosting profiles list` and `hosting profiles inspect` surfaces expose the built-in definitions and selected criteria. The implementation is available in [fork PR 173](https://github.com/giodl73-repo/openclaw/pull/173) From 93bcf0f0e443645cb99a0e02a72b1dac8e1e1ec2 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Mon, 27 Jul 2026 10:40:33 -0700 Subject: [PATCH 50/52] docs(rfc-0023): refresh implementation evidence --- rfcs/0023-standard-hosting-profiles.md | 20 ++++++++++---------- rfcs/0023/hosting-profile-v1-spec.md | 15 +++++++++------ 2 files changed, 19 insertions(+), 16 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 74b842fb..031f55f3 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -416,10 +416,10 @@ single dependent series in [openclaw/openclaw#113422](https://github.com/openclaw/openclaw/pull/113422). It depends on the readiness framework in [openclaw/openclaw#104018](https://github.com/openclaw/openclaw/pull/104018) -at exact head `59b02212b1f` +at exact head `2f131c6e220` and the core-owner criteria in [openclaw/openclaw#113421](https://github.com/openclaw/openclaw/pull/113421) -at exact head `7350b4cd744b`. The exact profile head is `b8d9808e1922`. +at exact head `c1d7f394f86`. The exact profile head is `18c42a7f26a`. | Slice | Intended scope | | --- | --- | @@ -442,8 +442,8 @@ slices as review aids; they are not alternative landing requests. The refreshed stack passes 120 focused profile, readiness, selection, and Gateway assertions; type-aware lint, formatting, shell syntax, and diff checks are clean. The -[exact-head package-installed Docker matrix](https://github.com/giodl73-repo/openclaw/actions/runs/30281595193) -passes on GitHub-hosted Actions over profile head `b8d9808e1922` using an +[exact-head package-installed Docker matrix](https://github.com/giodl73-repo/openclaw/actions/runs/30289122192) +passes on GitHub-hosted Actions over profile head `18c42a7f26a` using an immutable no-push package/image artifact. It proves unprofiled compatibility, all four profiles, expected failures, node approval, workspace recovery, stable repeated polls, and host-stable/process-and-Gateway-rotating container restart @@ -456,18 +456,18 @@ automation can inspect and validate it without reproducing profile predicates: The three facilities below are one ordered upstream review unit in [openclaw/openclaw#114636](https://github.com/openclaw/openclaw/pull/114636) at -exact head `890d042267c`. The fork PRs remain smaller comparison views. +exact head `123bae7b876`. The fork PRs remain smaller comparison views. 1. Read-only `hosting profiles list` and `hosting profiles inspect` surfaces expose the built-in definitions and selected criteria. The implementation is available in [fork PR 173](https://github.com/giodl73-repo/openclaw/pull/173) - at exact head `afaf7d1269af`. + at exact head `f9e6b219418`. 2. `hosting profiles validate` checks active identity, version, condition coverage, and readiness over one live RFC 0018 canonical result. The implementation is available in [fork PR 174](https://github.com/giodl73-repo/openclaw/pull/174) at exact head - `64cc6b4e8cd9`; the - [package-installed proof](https://github.com/giodl73-repo/openclaw/actions/runs/30281595193) + `0f59b726de9`; the + [package-installed proof](https://github.com/giodl73-repo/openclaw/actions/runs/30289122192) exercises that exact validator ancestor. It does not mutate configuration or run a second evaluator. 3. Package-installed release conformance invokes the canonical validator for @@ -475,8 +475,8 @@ exact head `890d042267c`. The fork PRs remain smaller comparison views. for Docker, Kubernetes, OCC, Lobster, CI, support bundles, and release qualification. The implementation is available in [fork PR 176](https://github.com/giodl73-repo/openclaw/pull/176) at exact head - `890d042267c`; its - [exact-head package-installed Docker proof](https://github.com/giodl73-repo/openclaw/actions/runs/30281595193) + `123bae7b876`; its + [exact-head package-installed Docker proof](https://github.com/giodl73-repo/openclaw/actions/runs/30289122192) passes all 13 scenarios, independently verifies the artifact, and uploads it as release evidence. diff --git a/rfcs/0023/hosting-profile-v1-spec.md b/rfcs/0023/hosting-profile-v1-spec.md index ede20ba6..8f999296 100644 --- a/rfcs/0023/hosting-profile-v1-spec.md +++ b/rfcs/0023/hosting-profile-v1-spec.md @@ -417,12 +417,15 @@ The lane writes one `hosting-profile-conformance.json` artifact: } ``` -The candidate package SHA-256 is present when the package path is available; -the immutable Docker image ID is always present. The writer independently -validates the canonical readiness fields, validation findings, profile -identity, conformance state, readiness state, and command exit before accepting -a scenario. It writes mismatch evidence before failing and sets top-level -`passed: true` only after the exact required scenario set is complete. +The candidate package SHA-256 is present when package provenance is available; +the immutable Docker image ID is always present. When a candidate package path +is supplied, the lane MUST verify that its SHA-256 matches the package digest +bound into the tested image and fail before recording scenarios on a missing or +mismatched binding. The writer independently validates the canonical readiness +fields, validation findings, profile identity, conformance state, readiness +state, and command exit before accepting a scenario. It writes mismatch +evidence before failing and sets top-level `passed: true` only after the exact +required scenario set is complete. Expected non-ready scenarios are successful conformance evidence only when the profile is structurally conformant, `ready` is false, and the validator exits From a54ae1ac6db3a86361f42e16bdadcda78a91a100 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Mon, 27 Jul 2026 15:30:48 -0700 Subject: [PATCH 51/52] docs: align hosting profile RFC with upstream stack --- rfcs/0023-standard-hosting-profiles.md | 28 +++++++------------------- 1 file changed, 7 insertions(+), 21 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 031f55f3..3e48dac4 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -428,16 +428,9 @@ at exact head `c1d7f394f86`. The exact profile head is `18c42a7f26a`. | Compatibility and safety | Keep unprofiled startup unchanged, validate profile-only identity only when selected, preserve attribution on failed evaluation, and bound pairing recovery work. | | Packaged scenarios | Exercise all four profiles, primary failures, node approval, workspace-full recovery, unprofiled compatibility, repeated-poll identity, and container-restart renewal boundaries; retain one fail-closed release artifact. | -PR 113422 is a stacked upstream PR against `main`. Until PRs 104018 and -113421 land, its aggregate GitHub diff includes both dependencies followed by -the profile commits. After both land, the same PR reduces to the profile-only -diff. [Fork PR 157](https://github.com/giodl73-repo/openclaw/pull/157) -preserves that exact profile-only comparison view. Fork PRs -[#18](https://github.com/giodl73-repo/openclaw/pull/18), -[#19](https://github.com/giodl73-repo/openclaw/pull/19), -[#42](https://github.com/giodl73-repo/openclaw/pull/42), and -[#21](https://github.com/giodl73-repo/openclaw/pull/21) expose the major design -slices as review aids; they are not alternative landing requests. +PR 113422 is stacked on PRs 104018 and 113421. Until those dependencies land, +its aggregate GitHub diff includes the readiness implementation followed by the +profile commits. After both land, the same PR reduces to the profile-only diff. The refreshed stack passes 120 focused profile, readiness, selection, and Gateway assertions; type-aware lint, formatting, shell syntax, and diff checks @@ -454,28 +447,21 @@ identity. The standard catalog becomes easier to support when operators and release automation can inspect and validate it without reproducing profile predicates: -The three facilities below are one ordered upstream review unit in +The three facilities below form one ordered upstream review unit in [openclaw/openclaw#114636](https://github.com/openclaw/openclaw/pull/114636) at -exact head `123bae7b876`. The fork PRs remain smaller comparison views. +exact head `123bae7b876`: 1. Read-only `hosting profiles list` and `hosting profiles inspect` surfaces - expose the built-in definitions and selected criteria. The implementation is - available in [fork PR 173](https://github.com/giodl73-repo/openclaw/pull/173) - at exact head `f9e6b219418`. + expose the built-in definitions and selected criteria. 2. `hosting profiles validate` checks active identity, version, condition coverage, and readiness over one live RFC 0018 canonical result. The - implementation is available in - [fork PR 174](https://github.com/giodl73-repo/openclaw/pull/174) at exact head - `0f59b726de9`; the [package-installed proof](https://github.com/giodl73-repo/openclaw/actions/runs/30289122192) exercises that exact validator ancestor. It does not mutate configuration or run a second evaluator. 3. Package-installed release conformance invokes the canonical validator for all 13 scenario states and retains one machine-readable artifact suitable for Docker, Kubernetes, OCC, Lobster, CI, support bundles, and release - qualification. The implementation is available in - [fork PR 176](https://github.com/giodl73-repo/openclaw/pull/176) at exact head - `123bae7b876`; its + qualification. Its [exact-head package-installed Docker proof](https://github.com/giodl73-repo/openclaw/actions/runs/30289122192) passes all 13 scenarios, independently verifies the artifact, and uploads it as release evidence. From 3c8a32e015761500aeab8947404afade804d6da3 Mon Sep 17 00:00:00 2001 From: Gio Della-Libera Date: Tue, 8 Sep 2026 22:11:45 -0700 Subject: [PATCH 52/52] docs: align hosting profile identity semantics Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- rfcs/0023-standard-hosting-profiles.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/rfcs/0023-standard-hosting-profiles.md b/rfcs/0023-standard-hosting-profiles.md index 3e48dac4..bd697b2f 100644 --- a/rfcs/0023-standard-hosting-profiles.md +++ b/rfcs/0023-standard-hosting-profiles.md @@ -256,10 +256,10 @@ underlying Gateway, proxy, plugin, model, node, or storage config. Profiles use RFC 0018's identity package instead of defining another runtime identity. A profiled result declares `openclaw/hosting-profile/selected` with -the selected profile as its opaque ID and the profile contract version as its -generation. `ProfileSelected` targets that subject. Topology-specific -conditions target the Gateway or node-controller subject and relate back to -the selected profile. +the selected profile as its opaque ID. The profile contract version is result +metadata, not a generation of that subject. `ProfileSelected` targets the +profile subject. Topology-specific conditions target the Gateway or +node-controller subject and relate back to the selected profile. Node mode additionally declares `openclaw/nodes/managed` and bounded child subjects for the paired nodes observed during that evaluation. Its aggregate @@ -267,8 +267,10 @@ conditions use the controller as their primary subject and list observed nodes as related subjects. Repeated results can therefore distinguish a changed condition from a replaced Gateway, changed profile, or changed node set. -The Gateway serving-lifecycle ID remains RFC 0018's concern. Hosts may supply -its opaque ID through `OPENCLAW_INSTANCE_ID`; otherwise OpenClaw generates it. +Gateway, process, and optional host-workload identities remain RFC 0018's +concern. OpenClaw generates the Gateway serving-lifecycle ID and process ID. +When supplied, `OPENCLAW_INSTANCE_ID` identifies only the fingerprinted +host-workload parent; it never overrides either generated child identity. Profiles do not add `runtimeId`, `incarnationId`, or an activation envelope. ### Operator extensions