You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Target main and the original packages/simulator. Make container-society
execution part of the core simulator, not an example.
There is one Kubernetes execution path with two Effect Layers:
a repository-owned local Kubernetes cluster;
regional GKE Standard.
Both run the same code-first RunSpec through Run.execute. The selected
stack is Kubernetes, Kueue, Agent Sandbox, and Temporal. Docker may build images
or support the local cluster; it is not a second simulator backend.
Requirements boundary
The checked-in source-event conversations are the requirements boundary:
docs/decision-evidence/20260801-main-kubernetes-society-execution-trajectory.md,
which also retains the earlier Kubernetes/Kueue/Temporal/Agent Sandbox
selections from the distributed-execution conversation.
Anything not discussed there is a non-goal. This issue is an implementation
plan, not normative authority; the main-track ADR owns the accepted contract.
Run.execute(spec) is the execution entry point. The infrastructure field
contains the selected local or GKE Effect Layer, while Kubernetes objects stay
out of the roster and customer Effect.
This reuses the existing EventCatalog, RunLedger, keyed StartedAgent gateway
types, network services, program Exit, infrastructure outcome, and
customer-owned completion policy. It does not create a new data model,
serialization framework, gateway union, or result system.
After the evaluations and local/GKE proofs migrate, remove the transitional simulator.define(...).run(...) host path and standalone Docker example. Do
not keep a compatibility backend.
One experiment lifecycle
Each execution creates one society for one customer Effect and tears it down:
Temporal starts one coarse workflow for the run.
Kueue admits capacity for the complete roster.
The controller creates one Agent Sandbox with one application container per
roster entry.
The controller waits for the exact full roster to be ready together.
The in-cluster controller invokes the customer execute Effect once.
The existing simulator outcome and ledger retain experiment and
infrastructure evidence.
Temporal drives cleanup of run-owned Kubernetes resources.
A pre-gate backing-Pod restart simply delays readiness and exposes no public
generation model. An unrecoverable or never-ready agent fails acquisition.
After dispatch, runtime termination remains typed ledger evidence and customer
Effect policy decides what to do. Controller or infrastructure loss fails the run and
starts cleanup. The controller does not replay customer code, and the simulator
makes no exactly-once claim for external side effects.
Kueue owns capacity, not readiness. Kubernetes and Agent Sandbox own placement
and container lifecycle, not customer policy. Temporal owns coarse
orchestration and cleanup, not agent logic or simulator evidence.
One roster entry is one agent in one Sandbox application container. Real and
code/scripted agents can share a society, but every social action uses the
production MoltZap router. Principal instructions use each runtime's native
gateway.
A stable controller loads the experiment module late. The stock digest-pinned
OpenClaw image is the compatibility path; an image with MoltZap preinstalled is
only an optimization. Exact bundle transport and caching are private profile
details.
Profiles
The local profile installs the components needed for development and CI,
including a development Temporal deployment.
The GKE reference is regional GKE Standard with Agent Sandbox. Terraform and
Helm own reproducible cluster and add-on setup. Production Temporal hosting and
high availability remain unselected; GKE qualification may use a test
deployment or configured endpoint.
The Effect Layer boundary leaves room for a future scheduler without adding a
new provider framework now. Nomad, Slurm, and managed batch are not implemented.
Implementation slices
0 — Admit the small main decision. Reconcile the source trajectory,
ADR, package law, prior-decision lineage, and affected docs. Freeze the exact
candidate, pass a fresh blind teammate review, and obtain maintainer
acceptance before production code.
1 — Core contract and fake. Add RunSpec and Run.execute as a
small facade over the existing simulator concepts. Add the narrow private
platform seam and fake tests for full-roster gating, one invocation,
post-dispatch termination policy, outcomes, and cleanup.
2 — Local Kubernetes vertical slice. Bring up local Kubernetes with
Kueue, Agent Sandbox, and Temporal. Run a two-agent stock-OpenClaw/core-router
smoke through packages/simulator, retain ledger evidence, and verify zero
run-owned residue.
3 — Four agents and evaluations. Prove the same path with four agents.
Move all 32 OpenClaw/NanoClaw evaluation cells to Run.execute and record
their real outcomes, including honest operational or behavioral failures.
Remove the host executor and standalone example after the replacement proof.
4 — GKE qualification. Provision regional GKE Standard with
Terraform/Helm, run the same small smoke and at least one OpenClaw evaluation
through the unchanged authoring contract, retain evidence, and clean up.
Acceptance criteria
packages/simulator owns the only real society-execution path.
The same agents, events, and execute program run through local
Kubernetes or GKE by changing only RunSpec.infrastructure.
One Kueue cohort is admitted before one Sandbox/application container per
roster entry is created.
The customer Effect cannot start before the exact full roster is ready.
The controller invokes it once and never replays it; no exactly-once
external-side-effect claim is made.
Principal control uses native gateways and all agent social traffic uses
the production router.
Existing typed ledger/outcome and evaluation grading/report contracts
remain readable and current.
Local two-agent, local four-agent, all 32 evaluation cells, and GKE smoke
evidence use Run.execute and leave zero run-owned residue.
No production code lands under v2/* and no new package is introduced.
Explicit non-goals
generation identifiers or streams, customer-visible restart/recovery APIs,
or post-dispatch replacement, rebinding, rejoin, persistent-state recovery,
and recovery of in-flight work;
customer Effect replay, exactly-once external effects, or distributed
side-effect transactions;
start-or-attach identity, artifact authorities, global execution-id
namespaces, synthetic UUIDs, or normative resource-name hashing;
a new immutable-data/JCS grammar or universal input/result/failure schema;
arbitrary Pod templates or public Kubernetes/Kueue/Sandbox/Temporal APIs;
per-agent Temporal workflows, warm societies, multi-run fairness,
preemption, autoscaling, router HA, or production Temporal HA;
scale qualification above four agents in this issue;
a Nomad, Slurm, managed-batch, or Autopilot backend;
a general multi-tenant Secret, NetworkPolicy, or security platform; and
any implementation or contract change under v2/*.
Existing work to reuse
Reuse the current simulator kernel, EventCatalog, RunLedger, scoped cleanup,
runtime-native gateways, router, OpenClaw adapter, and evaluation report
pipeline. The Docker society example remains temporary compatibility evidence
until the core Kubernetes path replaces it.
Outcome
Target
mainand the originalpackages/simulator. Make container-societyexecution part of the core simulator, not an example.
There is one Kubernetes execution path with two Effect Layers:
Both run the same code-first
RunSpecthroughRun.execute. The selectedstack is Kubernetes, Kueue, Agent Sandbox, and Temporal. Docker may build images
or support the local cluster; it is not a second simulator backend.
Requirements boundary
The checked-in source-event conversations are the requirements boundary:
docs/decision-evidence/20260727-code-first-simulator-trajectory.md;docs/decision-evidence/20260729-principal-runtime-gateway-trajectory.md;docs/decision-evidence/20260729-effect-native-evaluation-results-trajectory.md;docs/decision-evidence/20260801-main-kubernetes-society-execution-trajectory.md,which also retains the earlier Kubernetes/Kueue/Temporal/Agent Sandbox
selections from the distributed-execution conversation.
Anything not discussed there is a non-goal. This issue is an implementation
plan, not normative authority; the main-track ADR owns the accepted contract.
Public shape
The public model is deliberately small:
Run.execute(spec)is the execution entry point. Theinfrastructurefieldcontains the selected local or GKE Effect Layer, while Kubernetes objects stay
out of the roster and customer Effect.
This reuses the existing EventCatalog, RunLedger, keyed StartedAgent gateway
types, network services, program Exit, infrastructure outcome, and
customer-owned completion policy. It does not create a new data model,
serialization framework, gateway union, or result system.
After the evaluations and local/GKE proofs migrate, remove the transitional
simulator.define(...).run(...)host path and standalone Docker example. Donot keep a compatibility backend.
One experiment lifecycle
Each execution creates one society for one customer Effect and tears it down:
roster entry.
executeEffect once.infrastructure evidence.
A pre-gate backing-Pod restart simply delays readiness and exposes no public
generation model. An unrecoverable or never-ready agent fails acquisition.
After dispatch, runtime termination remains typed ledger evidence and customer
Effect policy decides what to do. Controller or infrastructure loss fails the run and
starts cleanup. The controller does not replay customer code, and the simulator
makes no exactly-once claim for external side effects.
Kueue owns capacity, not readiness. Kubernetes and Agent Sandbox own placement
and container lifecycle, not customer policy. Temporal owns coarse
orchestration and cleanup, not agent logic or simulator evidence.
One roster entry is one agent in one Sandbox application container. Real and
code/scripted agents can share a society, but every social action uses the
production MoltZap router. Principal instructions use each runtime's native
gateway.
A stable controller loads the experiment module late. The stock digest-pinned
OpenClaw image is the compatibility path; an image with MoltZap preinstalled is
only an optimization. Exact bundle transport and caching are private profile
details.
Profiles
The local profile installs the components needed for development and CI,
including a development Temporal deployment.
The GKE reference is regional GKE Standard with Agent Sandbox. Terraform and
Helm own reproducible cluster and add-on setup. Production Temporal hosting and
high availability remain unselected; GKE qualification may use a test
deployment or configured endpoint.
The Effect Layer boundary leaves room for a future scheduler without adding a
new provider framework now. Nomad, Slurm, and managed batch are not implemented.
Implementation slices
ADR, package law, prior-decision lineage, and affected docs. Freeze the exact
candidate, pass a fresh blind teammate review, and obtain maintainer
acceptance before production code.
RunSpecandRun.executeas asmall facade over the existing simulator concepts. Add the narrow private
platform seam and fake tests for full-roster gating, one invocation,
post-dispatch termination policy, outcomes, and cleanup.
Kueue, Agent Sandbox, and Temporal. Run a two-agent stock-OpenClaw/core-router
smoke through
packages/simulator, retain ledger evidence, and verify zerorun-owned residue.
Move all 32 OpenClaw/NanoClaw evaluation cells to
Run.executeand recordtheir real outcomes, including honest operational or behavioral failures.
Remove the host executor and standalone example after the replacement proof.
Terraform/Helm, run the same small smoke and at least one OpenClaw evaluation
through the unchanged authoring contract, retain evidence, and clean up.
Acceptance criteria
packages/simulatorowns the only real society-execution path.executeprogram run through localKubernetes or GKE by changing only
RunSpec.infrastructure.roster entry is created.
external-side-effect claim is made.
the production router.
remain readable and current.
evidence use
Run.executeand leave zero run-owned residue.v2/*and no new package is introduced.Explicit non-goals
or post-dispatch replacement, rebinding, rejoin, persistent-state recovery,
and recovery of in-flight work;
side-effect transactions;
namespaces, synthetic UUIDs, or normative resource-name hashing;
preemption, autoscaling, router HA, or production Temporal HA;
v2/*.Existing work to reuse
Reuse the current simulator kernel, EventCatalog, RunLedger, scoped cleanup,
runtime-native gateways, router, OpenClaw adapter, and evaluation report
pipeline. The Docker society example remains temporary compatibility evidence
until the core Kubernetes path replaces it.