Verification-stack descriptor contract + deployer: repos declare their full stack, Factory brings it up

[agent-relay-code]

Publishes previously stranded Factory work for #143.

The implementer completed and pushed factory/143-agentworkforce-factory-f9b704a7, but the terminal publish step failed for five days with 403 Resource not accessible by integration: the workspace's GitHub connection named a personal-account App installation (148356820) instead of the AgentWorkforce org installation (137532802). See AgentWorkforce/relayfile-cloud#155.

The connection has been repointed, and this PR is the acceptance test for that repair — published through Factory's own publish path, authored by app/agent-relay-code.

The branch is well behind main and has not been re-reviewed since it was stranded. Opened for review only; not for merge.

Refs #143

---

Summary by cubic

Introduces a repository-owned verification-stack contract and deployer so repos declare their full verification environment and Factory brings it up in Kubernetes. This replaces ad-hoc env setup with a validated descriptor, bounded health gates, seed steps, and resolved local endpoints.

• Publishes the JSON Schema at @agent-relay/factory/verification-stack.schema.json and exports descriptor types, loader, and errors (VerificationStackDescriptorSchema, VerificationStackDescriptorError, etc.).
• Adds VerificationStackDeployer with HTTP/TCP/exec probes, Helm/Kustomize/manifest/docker-compose (via kompose) support, and endpoint port-forwards. Adds KubernetesEnvironmentProvider that provisions per-run namespaces and deletes them idempotently.
• Exposes new APIs from src/index.ts and ships schemas/ in the package. Requires kubectl, helm, and kompose on PATH and a Kubernetes context/kubeconfig.
• Adds CI job verification-stack-e2e that creates a Kind cluster and runs npm run test:stack-e2e (new tsx dev dependency).
• Adoption is optional. To use, add .factory/verification-stack.yaml with only opaque secret/config references and provide a VerificationStackReferenceResolver; existing repos are unaffected until they add the descriptor.

^{Written for commit c35e66d. Summary will update on new commits.}

[khaliqgant]

Rebase assessment: do not rebase — this PR is fully superseded. Recommend closing it.

I was dispatched to rebase factory/143-agentworkforce-factory-f9b704a7 onto main and resolve conflicts preserving both sides. I did not perform the rebase, because there is no surviving side to preserve: every line of this branch's work is already on main, and merging it would be a pure regression across 17 files.

The brief described conflicts as "concentrated in 6 integration-point files." That understates it. The real merge produces 17 conflicts, 11 of them add/add on the feature's own source files — stack-deployer.ts, stack-descriptor.ts, kubernetes-provider.ts, kubernetes-command.ts, schemas/verification-stack.schema.json, docs/verification-stack.md, the fixtures, and src/ports/environment.ts. An add/add conflict on the feature's own files is the signal that the feature landed by another route.

What happened

Same author, same morning, two parallel dispatches:

commit	when	landed as
c35e66d — this branch	2026-07-21 10:44:41	never published (the credential fault)
c4b545c — "add Kubernetes verification environments"	2026-07-21 10:51:56	#172, merged 11:43Z
18297f3 — "Verification gate: provision to teardown"	later that day	#173, merged 12:59Z

Seven minutes after this branch's commit, a sibling implementation was committed and merged the same day. #173 then carried this branch's exact code onto main under new filenames.

Evidence that it is the same code, not merely similar

Descriptor — literal superset, zero loss. main:src/environments/verification-stack-descriptor.ts vs this branch's stack-descriptor.ts: diff reports zero branch-only lines. Main's file is this file plus a verification gate section (environmentTtlSeconds, e2e, load, overallTimeoutSeconds, teardownTimeoutSeconds) and digest-pinned image validation.

Deployer — same file, extended. main:verification-stack-deployer.ts vs this branch's stack-deployer.ts: 193 differing lines out of 1311. Every branch-only line is one of (a) a signature main extended with signal?: AbortSignal, (b) an import main renamed, or (c) the local kubernetesTarget() helper main replaced with verificationKubernetesConnection. Main additionally enforces enforceKubernetesResourceSafety on rendered resources before apply. No branch-only behaviour.

Public API — 39 of 41 symbols already exported from main. I checked each symbol this branch adds to src/index.ts against main's src/index.ts, src/environments/index.ts, and src/ports/environment.ts. The two exceptions are EnvironmentSpec and KubernetesEnvironmentTarget, and both were deliberately restructured away — EnvironmentSpec → ProvisionEnvironmentSpec (with customerId/repository/ownerId and a stack?: unknown seam), and KubernetesEnvironmentTarget → VerificationEnvironment + a locally-scoped KubernetesConnection & { namespace }. Reinstating them is the regression, not the fix.

Tests — all six, verbatim, plus one more. Every it() in this branch's stack-deployer.test.ts exists on main in verification-stack-deployer.test.ts under an identical name; main adds a seventh (rejects rendered resources before apply when they cross the safety boundary). Branch-only tests: none.

Files — all 19 exist on main (two under their renamed paths).

What merging this would cost

Because the branch is 200 commits behind, its side of each conflict is the older side. Taking it would:

• roll package.json back 0.1.68 → 0.1.49, and every @agent-relay/* dep ^11.6.9 → ^10.6.4
• drop 5 package exports: ./telemetry, ./cli, ./intake, ./feature-guardian, ./environments, plus kubernetes-environment-stack.schema.json
• delete 3 CI jobs — kubernetes-provider-e2e, load-e2e, verification-gate-e2e
• downgrade CI Node 22.14.0 → 20, remove persist-credentials: false, remove if: always() on evidence upload
• strip the verification gate section from the published JSON Schema and its docs
• strip pod-security hardening from the fixtures: digest-pinned images → floating tags, and removal of runAsNonRoot, seccompProfile, readOnlyRootFilesystem, capabilities: drop [ALL]
• delete verification-pipeline.ts, load-harness.ts, k6-job.ts, kubernetes-client.ts, connection-registry.ts and the reaper/guardrail logic in kubernetes-provider.ts (131 lines here vs 1073 on main)

On issue #143 — do not re-dispatch as written

Worth flagging, because it changes the follow-up: #143's primary acceptance criterion was never built, on either side. The issue specifies Cloudflare (Workers + Containers + D1/KV/R2/Queues/Hyperdrive) as the primary deploy kind, with Helm/kustomize/manifests/compose as escape hatches. Both this branch and main implement only the escape hatches — main's schema offers helm, kustomize, manifests (plus compose via kompose). There is no Cloudflare or wrangler code anywhere in src/ on either side; the sole mention is a negative test asserting a { type: 'cloudflare' } environment is rejected.

So the remaining scope of #143 is the Cloudflare deploy kind — and this branch does not contribute to it. Rebasing it buys nothing toward the open work.

Recommended:

1. Close Verification-stack descriptor contract + deployer: repos declare their full stack, Factory brings it up #314 as superseded by 147: Add BYOC and managed Kubernetes verification environments #172 + Verification gate: provision to teardown in the merge path #173. Nothing is lost; I verified that at line level, symbol level, and test level.
2. Keep Verification-stack descriptor contract + deployer: repos declare their full stack, Factory brings it up #143 open, re-scoped to the unbuilt Cloudflare path only, and dispatch that fresh against current main — building on verification-stack-descriptor.ts / verification-stack-deployer.ts as they now exist, adding a cloudflare deploy kind alongside the existing three. The Kubernetes half of Verification-stack descriptor contract + deployer: repos declare their full stack, Factory brings it up #143 is done and shipped.

CI and review state

• No CI has ever run on this branch. gh run list --branch factory/143-agentworkforce-factory-f9b704a7 returns nothing, and the head SHA c35e66d has 0 check-runs. Nothing was hidden by a rollup — there is no rollup.
• No review threads, no reviews, no comments on Verification-stack descriptor contract + deployer: repos declare their full stack, Factory brings it up #314 (reviewThreads.totalCount = 0). cubic wrote the PR body summary but submitted no review. There are no unanswered bot threads to answer.
• Per-workflow on main, the four environment jobs are green — including verification-stack-e2e, the exact job this PR proposed to add. The package job is red on main for a pre-existing, unrelated reason: src/orchestrator/factory.test.ts > FactoryLoop PR babysitter > holds the terminal Slack receipt lease for as long as the provider write runs (expected false to be true), 1 failed / 100 passed. That failure predates and is independent of this PR.

I ran no local test suite: there is no merged tree to test, and the branch's own dependency set is 200 commits stale. The verification-stack code that matters is already covered green on main by verification-stack-e2e and the unit suite.

I have not merged, closed, or pushed anything. Khaliq owns the merge gate; the close call is yours.

[khaliqgant]

Closing: this PR wraps a branch whose last commit is 2026-07-21, opened against a main that has moved substantially since — hence DIRTY with extensive conflicts.

Reconciling +2378/-1 across 19 files written before 0.1.66→0.1.68, the relay fleet-client bounding work (#307), and the config-schema change would not be an honest review; the branch predates the assumptions the current code makes.

Issue #143 stays open and still carries factory:in-progress from that era. It is one of the abandoned claims identified in today's inventory (branch exists, no commit since 2026-07-21). Better to re-dispatch it cleanly once dispatch is restored than to salvage a month-old branch.

Not closing the issue — only this stale PR. The branch is left in place for reference.