Complete Experiment onboarding

authorization/experiment/v0alpha1/operator.cedar

@@ -11,6 +11,7 @@ when
   principal.source == "fixed-local-cli" &&
   context.bindingVersion == "v0alpha1" &&
   resource.planDigest == context.planDigest &&
+  resource.sourceDigest == context.sourceDigest &&
   resource.contractDigest == context.contractDigest &&
   resource.contractVersion == "v0alpha1"
 };

authorization/experiment/v0alpha1/schema.cedarschema

@@ -7,6 +7,7 @@ namespace AgentLab {
 
     entity RequestedExperimentPlan = {
         planDigest: String,
+        sourceDigest: String,
         contractDigest: String,
         contractVersion: String,
         requestedName: String,
@@ -20,6 +21,7 @@ namespace AgentLab {
         context: {
             bindingVersion: String,
             planDigest: String,
+            sourceDigest: String,
             contractDigest: String,
         },
     };

catalog/experiment-images/v0alpha1.json

@@ -0,0 +1 @@
+{"apiVersion":"agent-lab.experiment-images/v0alpha1","entries":[]}

contracts/experiment/v0alpha1/plan.cue

@@ -22,10 +22,10 @@ contractDigest: string & =~"^sha256:[0-9a-f]{64}$" @tag(contractDigest)
 			y:    _
 			less: x.name < y.name
 		}) {
-			name:          member.name
-			image:         member.image
-			command:       member.command
-			resourceClass: member.resourceClass
+			name:              member.name
+			requestedSelector: member.image
+			command:           member.command
+			resourceClass:     member.resourceClass
 		}]
 	})
 })

contracts/experiment/v0alpha1/schema.cue

@@ -8,9 +8,14 @@ import (
 #Name: string & strings.MaxRunes(63) &
 	=~"^[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$"
 
-#Image: string & strings.MinRunes(1) & strings.MaxRunes(255) &
+#DigestRef: string & strings.MinRunes(1) & strings.MaxRunes(255) &
 	=~"^([a-z0-9]+([.-][a-z0-9]+)*(:(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?/)?[a-z0-9]+([._-][a-z0-9]+)*(/[a-z0-9]+([._-][a-z0-9]+)*)*@sha256:[0-9a-f]{64}$"
 
+#CatalogName: string & strings.MaxRunes(63) &
+	=~"^[a-z][a-z0-9]*(?:-[a-z0-9]+)*\\.[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+
+#Image: close({digestRef: #DigestRef}) | close({catalogName: #CatalogName})
+
 #Argument: string & strings.MaxRunes(1024) & !~"[\\p{Cc}\\p{Cf}\\p{Zl}\\p{Zp}]"
 
 #Member: close({

docs/architecture.md

@@ -67,20 +67,41 @@ capabilities their documented task requires.
 
 See [Development](development.md) and [development-agent configuration](agent-config.md).
 
-## Experiment request preflight
+## Experiment planning and installed evidence
 
-`scripts/experiment check [--] MANIFEST` validates the closed `agent-lab/v0alpha1` request with the
-repository-pinned CUE contract and emits one canonical, digest-bound `RequestedExperimentPlan`.
-`scripts/experiment authorize install [--] MANIFEST` reads the manifest once, derives that same plan
+`scripts/agent-lab experiment check` snapshots and validates one closed authored source from a sole
+local `experiment.cue`, a bounded sole-member ZIP, or an exact supported public GitHub commit. The
+repository-pinned CUE contract emits one canonical, digest-bound `RequestedExperimentPlan`.
+`scripts/agent-lab experiment authorize install` reads that snapshot once, derives the same plan
 in-process, and asks the repository-pinned Cedar policy whether the fixed local compatibility
 principal may submit the exact plan digest.
 
-Both commands are no-effect preflights: they make no container-engine, network, registration, or
-runtime changes. A requested name is correlation data, not an installed Experiment identity or
-scope. Start, stop, and remove authorization require a future Broker-minted Experiment identity and
-Broker-owned ledger, so they are deliberately outside this requested-plan seam. An install permit
-only clears the exact requested intent for a future Broker-controlled install path; it neither
-actuates the plan nor waives Agent Lab's containment envelope.
+For public Git, the fixed TLS-authenticated GitHub API binds the requested commit ID to its returned
+root-tree ID. The adapter requires the response to echo that commit and independently recomputes the
+returned tree and blob Git object IDs before the authored bytes enter the common planning path.
+
+The preview forms create no durable Agent Lab state; Git previews have only their bounded public
+acquisition effect. `experiment install` instead repeats snapshotting, planning, and Cedar
+evaluation, then stores the exact permitted evidence in the initialized home. Directory, ZIP, and
+Git sources carrying identical bytes converge on the same source, plan, authorization, installation,
+and artifact identities; only their closed transport provenance differs. No caller-supplied decision
+is accepted. For a local image name, install rechecks the selected entry under the shared catalog
+lock before taking the Experiment store lock exclusively; both remain held through durable
+no-replace publication. Direct and bundled selectors do not open local catalog state.
+
+The installed envelope contains the exact artifact plus closed plan, decision, provenance, and
+receipt records. Its installation key binds source, domain-separated plan, contract, authorization,
+and selected-entry identities. The receipt binds the artifact and every other evidence record; its
+returned receipt digest binds the receipt itself. An exact retry verifies the envelope and returns
+the same identity; a different identity under the same requested name never overwrites it.
+`experiment inspect NAME` takes the store lock shared and verifies the complete envelope without
+repairing staging.
+
+Installation is persistent onboarding evidence only. It makes no container-engine, network,
+registration, image-acquisition, admission, or runtime change and does not waive the containment
+envelope. The requested name identifies this stored envelope, not a running Broker identity or
+runtime scope. Experiment start, stop, and runtime removal remain future Broker operations; stored
+artifact uninstall is also not implemented.
 
 ## Workload launch sequence
 
@@ -236,7 +257,7 @@ For formal assumptions and limits, read [Security](../SECURITY.md) and the
 | Squid and test service | `compose.egress.yaml`, `gateway/squid/` |
 | workload container | `compose.agent.yaml` and HOME overlays |
 | workload orchestration | `scripts/agent` |
-| Experiment request planning and authorization | `scripts/experiment`, `contracts/experiment/`, `authorization/experiment/` |
+| Experiment installed evidence | `scripts/agent-lab`, `scripts/experiment.py`, `scripts/experiment_store.py`, contracts, and authorization policy |
 | config parsing and validation | `scripts/lib/config.sh` |
 | project and secret guards | `scripts/lib/guard.sh` |
 | recipe publication | `scripts/lib/allowlist.sh` |

docs/experiments.md

@@ -0,0 +1,121 @@
+# Experiments
+
+An Experiment is authored as data in a directory containing exactly one file, `experiment.cue`, in a
+bounded ZIP archive containing that exact sole member, or at one exact commit of a supported public
+GitHub repository whose root tree contains that exact sole blob. The file defines one concrete value
+named `experiment` in package `experiment`. Agent Lab snapshots the exact authored bytes privately
+before evaluating them; extra entries, links, special files, suspicious modes, changing sources,
+malformed CUE, and unknown schema fields are refused.
+
+```cue
+package experiment
+
+experiment: {
+	apiVersion: "agent-lab/v0alpha1"
+	kind:       "Experiment"
+	metadata: name: "example"
+	spec: members: [{
+		name: "worker"
+		image: digestRef: "registry.example/team/worker@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+		command: ["serve"]
+	}]
+}
+```
+
+Check the artifact or preview its install authorization from the repository:
+
+```bash
+./scripts/agent-lab experiment check ./my-experiment
+./scripts/agent-lab experiment authorize install ./my-experiment
+./scripts/agent-lab experiment check --zip ./my-experiment.zip
+./scripts/agent-lab experiment authorize install --zip ./my-experiment.zip
+./scripts/agent-lab experiment check --git https://github.com/owner/repository.git --commit <40 lowercase hex>
+./scripts/agent-lab experiment authorize install --git https://github.com/owner/repository.git --commit <40 lowercase hex>
+```
+
+The check and authorization forms are previews. They create no durable Agent Lab state and do not
+invoke Docker or run Experiment content. Git previews do perform the bounded public acquisition
+described below. `authorize install` freshly checks the same held source and emits decision evidence
+bound to its source, plan, contract, and authorization identities. The decision is not an
+installation capability.
+
+Install a freshly checked and permitted artifact, then inspect its stored identity:
+
+```bash
+agent-lab [--home /absolute/private/home] experiment install ./my-experiment
+agent-lab [--home /absolute/private/home] experiment install --zip ./my-experiment.zip
+agent-lab [--home /absolute/private/home] experiment install --git https://github.com/owner/repository.git --commit <40 lowercase hex>
+agent-lab [--home /absolute/private/home] experiment inspect example
+```
+
+`install` takes one held source snapshot, derives the plan, and evaluates Cedar again in the same
+operation without reopening the caller path. It does not accept a saved plan, decision, destination,
+or name override. A permit is evidence for that exact candidate only; installation stores the
+source, plan, decision, provenance, and receipt without running content, invoking Docker, acquiring
+image bytes, or claiming runtime admission. The decision and receipt bind the same domain-separated
+plan identity rather than an unframed hash of the JSON bytes.
+
+ZIP intake reads one stable archive into at most 1,048,576 bytes and accepts only stored or deflated
+`experiment.cue` data that expands to at most 262,144 bytes. ZIP64, multidisk archives, encryption,
+comments, extra fields, alternate paths, extra members, special file types, inconsistent headers,
+bad CRC or lengths, truncated streams, and trailing bytes are rejected before CUE evaluation. Agent
+Lab never extracts the archive or chooses a destination from caller data. The normalized source
+digest is identical to directory intake for identical authored bytes; installation provenance also
+records the raw archive byte count and SHA-256 digest. Archive identity does not affect the plan,
+authorization binding, installation key, or idempotent cross-transport retry.
+Regular-file attributes are interpreted only for Unix and DOS-compatible FAT, NTFS, and VFAT
+creator systems; other creator systems are rejected when their member type cannot be proven.
+
+Git intake is Linux-only in this version. It accepts only a normalized, unauthenticated
+`https://github.com/<owner>/<repository>.git` URL and one exact lowercase 40-hex SHA-1 commit object
+ID. A fixed credential-free GitHub Git Data API client reads that commit, its exact root tree, and
+the bound blob under one five-second deadline and a 1,048,576-byte aggregate response cap. It uses
+explicit system trust, identity encoding, fixed headers, a private process group, and zero temporary
+files. The TLS-authenticated fixed GitHub API is the trust binding from the requested commit ID to
+the returned root-tree ID: the response must echo the requested commit, and Agent Lab independently
+recomputes the returned tree and blob Git object IDs before accepting their bytes. Redirects,
+credentials, mutable refs, alternate protocols or authorities, extra tree entries, and changed bound
+objects fail closed. Agent Lab never runs Git, creates a repository, checks out content, follows
+submodules, or executes repository data. Provenance records the canonical URL, provider-bound commit
+ID, independently verified tree/blob IDs, bounded acquisition facts, and the independent framed
+SHA-256 source digest. Git object identity does not replace source identity or change cross-transport
+retry.
+
+An exact retry freshly validates and authorizes again, verifies the complete installed envelope,
+and returns `changed:false` with the same `installationKey` and `receiptDigest`. The same requested
+name with a different installation identity conflicts without overwrite. `inspect` is read-only: it
+verifies and reports one installed identity, but never reconciles staging or repairs state. A later
+effectful install may recover only recognized, bounded staging left by an interrupted publication;
+unknown or ambiguous residue remains in place and returns infrastructure uncertainty.
+
+These preview, install, and inspect commands work from a local installation after `agent-lab init`
+and explicit `agent-lab tools provision`. Installed execution verifies and uses its release bundle
+and the effective home's pinned tool cache; it does not depend on a source checkout.
+
+Each member selects either an exact digest-pinned OCI reference with `digestRef` or a shared name
+with `catalogName`. Shared names have exactly two bounded lowercase components, `<vendor>.<image>`.
+The `agent-lab.*` namespace belongs to the release-owned bundled catalog; the catalog is initially
+empty. Other valid namespaces belong to the operator-local catalog shared by every Experiment using
+the same effective home:
+
+```bash
+agent-lab image add vendor.image registry.example/team/image@sha256:<64 lowercase hex>
+agent-lab image inspect vendor.image
+agent-lab image list [--all]
+agent-lab image remove vendor.image --expect sha256:<entry digest>
+```
+
+Add records a mapping only. Same-subject add is idempotent; a different subject never overwrites.
+Remove uses the active entry digest as a compare-and-swap token, creates a generation-two tombstone,
+and makes the name non-reusable in v0. A local name is resolved from one held, verified catalog
+snapshot. The plan binds only the selected entry digest, generation, and immutable subject; checked
+evidence separately records the held snapshot revision and digest. An unrelated catalog change
+therefore changes catalog evidence without changing the selected plan identity.
+
+After a fresh install permit, every selected local entry is checked again under the stable shared
+catalog lock. That lock remains held while the Experiment store lock is acquired and through durable
+publication. Removal therefore cannot make the selected entry stale during installation. Direct
+digest selectors and release-owned bundled names do not open the local catalog on this path.
+
+Catalog membership is naming only, not image presence, admission, safety, or runnable status. See
+[`images.md`](images.md) for the exact namespace, mutation, persistence, and failure contract.

docs/images.md

@@ -0,0 +1,78 @@
+# Local image names
+
+Agent Lab can assign one operator-local name to an already immutable OCI subject:
+
+```bash
+agent-lab [--home ABSOLUTE_HOME] image add VENDOR.IMAGE DIGEST_REF
+agent-lab [--home ABSOLUTE_HOME] image inspect VENDOR.IMAGE
+agent-lab [--home ABSOLUTE_HOME] image list [--all]
+agent-lab [--home ABSOLUTE_HOME] image remove VENDOR.IMAGE --expect ENTRY_DIGEST
+```
+
+This catalog is shared by every Experiment using the same initialized Agent Lab home. It stores
+names and digest-pinned references only. These commands do not call Docker, contact a registry,
+download or inspect image bytes, perform admission, or assert that a subject is runnable.
+
+## Names and subjects
+
+A local name has exactly two lowercase ASCII components, `<vendor>.<image>`. Each component is 1–31
+bytes, begins with a letter, and may contain digits or single hyphen-separated segments. The whole
+name is at most 63 bytes. `agent-lab.*` is reserved for the release-owned bundled catalog and cannot
+be added, removed, or shadowed locally.
+
+`DIGEST_REF` uses the same bounded parser as an authored Experiment `digestRef`. It must contain one
+exact lowercase `sha256` digest; mutable tags, bare digests, credentials, paths, and ambiguous
+references are refused.
+
+## Mutation rules
+
+The first add publishes generation 1. Repeating the same name and subject is an idempotent
+`changed:false` success. A different subject conflicts and never overwrites.
+
+Removal requires the active entry digest from add or inspect. An exact compare-and-swap publishes a
+generation-2 tombstone. Retrying with the original active digest is idempotent; every other token
+conflicts. A tombstoned name cannot be reused or restored in v0alpha1.
+
+`image remove` removes only the local name from future selection. It does not call Docker, remove
+runtime image bytes, stop a workload, or delete an installed Experiment envelope. A retained
+installed envelope remains inspectable because it binds the exact selected entry identity; a new or
+exact-retry install using the tombstoned name fails its liveness check. Runtime image removal and
+stored-artifact uninstall are separate future operations, and neither is implemented by this
+command.
+
+During `experiment install`, a selected local entry is rechecked after the fresh permit under the
+stable shared catalog lock. The lock remains held through Experiment publication, so a concurrent
+catalog removal cannot invalidate the selected entry mid-install. This proves naming liveness only;
+it does not perform image acquisition or admission.
+
+## Stored authority
+
+The configured images component contains immutable entry and snapshot histories plus one current
+pointer:
+
+```text
+images/catalog/
+|-- current.json
+|-- entries/<entry-digest>.json
+`-- snapshots/<snapshot-digest>.json
+```
+
+Every read holds the stable catalog lock and verifies canonical schemas, record digests, the
+reachable transition chain, all physical history, ownership and modes, fixed counts, and byte
+bounds. Unsafe, missing initialized, changing, or corrupt authority returns `125`; an unknown or
+removed logical name returns `1`.
+
+The initialized-home receipt binds the catalog lock's device, inode, path, and schema. The lock
+starts with its schema line and appends exactly one `initialized` line only after the first complete
+staged catalog is durable and immediately before its no-replace commit. A matching bounded intent
+distinguishes that pre-commit recovery window; replacement or any other bytes fail closed.
+
+Mutations prepare one bounded intent beneath `images/.staging/`. A first catalog uses Linux
+no-replace directory publication. Later changes durably publish immutable records before atomically
+advancing and syncing the current pointer. The next mutation reconciles a recognized interrupted
+intent against the observed pointer. After it proves that cleanup is safe, it durably renames the
+operation to one bounded cleanup wrapper before removing any contents, so a crash during cleanup is
+restartable. Unknown or unsafe residue is preserved and returns `125`.
+
+This is tamper-evident state for a cooperative local account, not protection from a hostile process
+running as the same user.