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

.github/workflows/ci.yml

@@ -56,3 +56,29 @@ jobs:
 
       - name: Verify package contents
         run: npm pack --dry-run
+
+  verification-stack-e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Create kind cluster
+        uses: helm/kind-action@v1.14.0
+        with:
+          cluster_name: factory-stack-e2e
+
+      - name: Deploy and verify descriptor stack
+        run: npm run test:stack-e2e

docs/verification-stack.md

@@ -0,0 +1,60 @@
+# Verification-stack descriptor
+
+Repositories declare their complete verification environment in
+`.factory/verification-stack.yaml`. Factory validates the file, deploys it into
+an isolated environment, waits for every declared service probe, runs seed
+steps, and returns local HTTP endpoint URLs for E2E and load stages.
+
+The published JSON Schema is available as
+`@agent-relay/factory/verification-stack.schema.json`.
+
+```yaml
+apiVersion: factory.agentworkforce.dev/v1alpha1
+kind: VerificationStack
+name: my-app
+source:
+  type: manifests # helm, kustomize, manifests, or docker-compose
+  paths: [deploy/stack.yaml]
+secrets:
+  - name: database
+    data:
+      PASSWORD:
+        ref: resource://production-like/database-password
+services:
+  - name: api
+    workload:
+      kind: deployment
+    readiness:
+      type: http
+      port: 8080
+      path: /health
+      timeoutSeconds: 120
+seeds:
+  - type: exec
+    name: seed-api
+    service: api
+    command: [node, scripts/seed.js]
+endpoints:
+  - name: api
+    service: api
+    port: 8080
+    path: /health
+```
+
+Secret and config entries contain only opaque references. The caller supplies a
+`VerificationStackReferenceResolver`; a missing required reference aborts before
+the stack source is applied. Inline values are rejected by the typed loader.
+
+`resolveVerificationStackDescriptor({ repoPath, ref?, descriptorPath? })`
+selects the default descriptor or a repository-relative override. Passing `ref`
+loads the descriptor committed at that branch or SHA instead of the working
+tree version. On deployment, Factory materializes stack assets from that same
+commit so a dirty or differently checked-out working tree cannot change the
+selected stack.
+
+`VerificationStackDeployer.deploy(descriptor, environment)` supports local or
+OCI/HTTP Helm charts, kustomize directories, raw Kubernetes manifests, and
+Docker Compose through `kompose`. It waits for Deployment, StatefulSet, or
+DaemonSet rollout plus each HTTP, TCP, or exec probe. All waits and seed steps
+have descriptor-bounded timeouts. The returned deployment owns any local
+port-forward processes; call `dispose()` before destroying the environment.

package.json

@@ -19,6 +19,7 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "schemas",
     "bin/factory.mjs",
     "scripts/factory-canary.sh",
     "scripts/com.agentrelay.factory-canary.plist.example",
@@ -56,7 +57,8 @@
     "./hosted": {
       "types": "./dist/hosted/index.d.ts",
       "import": "./dist/hosted/index.js"
-    }
+    },
+    "./verification-stack.schema.json": "./schemas/verification-stack.schema.json"
   },
   "publishConfig": {
     "access": "public"
@@ -65,6 +67,7 @@
     "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
     "featuremap:check": "node bin/factory.mjs featuremap check",
     "test": "vitest run",
+    "test:stack-e2e": "tsx test/e2e/stack-deployer.e2e.ts",
     "verify:e2e": "node scripts/verify-packed-e2e.mjs",
     "factory-build": "factory-build/run-factory-build.sh"
   },
@@ -90,6 +93,7 @@
     "@types/node": "^22.10.2",
     "@types/proper-lockfile": "^4.1.4",
     "esbuild": "^0.28.1",
+    "tsx": "^4.20.6",
     "tsc-alias": "^1.8.17",
     "typescript": "^5.7.0",
     "vitest": "^4.1.8"