agentera 3.0.0-dev.41 → 3.0.0-dev.46

package/bundle/references/adapters/package-publication.json

@@ -1,18 +1,15 @@
 {
-  "schemaVersion": "agentera.packagePublication.v1",
+  "schemaVersion": "agentera.packagePublication.v2",
   "owner": "repository/package scripts",
   "invariants": {
-    "preparation": "Metadata preparation is non-publishing and leaves version and gitRef changes for review and commit.",
-    "preflight": "Publication requires explicit authority, a clean tree, committed package metadata, an adapter-valid version, and an existing gitRef before registry mutation.",
-    "publication": "Publish directly to the expected tag, then require bounded exact-version integrity and tag convergence.",
-    "access": "Publish the unscoped package with public access.",
-    "retry": "An exact version with matching integrity and expected tag is a successful replay; conflicting integrity or an expected tag already ahead of the committed version fails without mutation.",
-    "smoke": "Run one non-mutating no-project exact-version --version command after convergence; failure is explicit and does not imply rollback.",
-    "construction": "Each adapter returns the exact npm name, version, file count, packed and unpacked sizes, shasum, integrity, expected tag, artifact path, warnings, and complete file manifest before publication.",
-    "credentials": "Only the npm publish child receives credentials, through a mode-0600 temporary user config; inherited npm/pnpm lifecycle settings and token variables are removed from its environment, and the config is deleted when the child exits.",
-    "orchestration": "Root package scripts are the shared local and CI interface. Push-only development and stable jobs run the matching transaction after required gates; replay needs no credentials, mutation without credentials fails, and development publication precedes exact-version L2 bootstrap verification.",
-    "outputModes": "Default construction output omits the per-file list; --json and --verbose retain the complete npm pack manifest.",
-    "output": ["package", "version", "expectedTag", "phase", "outcome", "nextAction"]
+    "preparation": "Preparation is pure and registry-independent. It accepts an explicit target version and source commit, changes only package version and agentera.gitRef, and leaves the diff for review and commit.",
+    "sourceQualification": "Source qualification never repairs source. It issues a content-addressed receipt only after every declared source gate succeeds against a clean committed tree. A matching receipt is a deterministic local cache, not an authorization boundary.",
+    "candidateQualification": "Candidate qualification validates a current source receipt, constructs one retained immutable tarball with the contract-required retained mode, proves dry-pack observation equivalence, and runs a local exact-artifact smoke in an empty isolated npm state before any registry effect.",
+    "publication": "Registry publication consumes the retained candidate bytes through one measured stage, independent exact-version L2, and promote envelope. Stage and promotion include their required registry convergence and observational checks. The envelope never reconstructs an artifact, reruns source qualification, or rolls a tag back.",
+    "approval": "Registry mutation requires an explicit approval bound to the candidate receipt digest, target version, integrity, package, registry, and tag. A branch push is never approval.",
+    "replay": "A matching exact version, integrity, and required tag state is a successful no-upload replay. Conflicting integrity, an escaped artifact, a stale tag, or any unrecognized registry state fails before mutation.",
+    "credentials": "Registry inspection runs before credentials are required. Only the npm mutation child receives a mode-0600 temporary user config. Tool probes and every npm, pnpm, and npx child, including receipt validation during stage and promotion, use isolated user/global config, home, cache, and sanitized npm/pnpm environments.",
+    "output": "Every transaction phase emits a bounded start and end result with package, version, phase, outcome, elapsedMs, executed, reused, and nextAction. The qualified-publication coordinator emits one content-bound timing receipt in JSON or equivalent human output with measured component and total durations, strict budget status, first failure, reconciliation, and replay state. Diagnostics redact credentials and private absolute paths."
   },
   "packages": {
     "development": {
@@ -22,7 +19,8 @@
       "expectedTag": "next",
       "preparation": "incrementDevPrerelease",
       "construction": "isolatedTypeScriptPackage",
-      "smoke": ["npx", "-y", "agentera@{version}", "--version"]
+      "smoke": ["npx", "-y", "agentera@{version}", "--version"],
+      "localSmoke": ["agentera", "--version"]
     },
     "stable": {
       "label": "transitional stable shim",
@@ -31,9 +29,405 @@
       "expectedTag": "latest",
       "preparation": "incrementPatch",
       "construction": "stableShim",
-      "smoke": ["npx", "-y", "agentera@{version}", "--version"]
+      "smoke": ["npx", "-y", "agentera@{version}", "--version"],
+      "localSmoke": ["agentera", "--version"],
+      "sourceProvenance": {
+        "rule": "agentera.gitRef must name a commit with exactly the current shim packaged inputs. Only package.json version and agentera.gitRef may differ because preparation owns those fields.",
+        "packagedInputs": [
+          "packages/cli/shim/bin",
+          "packages/cli/shim/lib",
+          "packages/cli/shim/README.md",
+          "packages/cli/shim/LICENSE"
+        ],
+        "permittedManifestDifferences": ["version", "agentera.gitRef"]
+      }
     }
   },
+  "ci": {
+    "repository": "jgabor/agentera",
+    "qualificationWorkflow": {
+      "name": "Qualify release candidate",
+      "path": ".github/workflows/qualify-candidate.yml",
+      "ref": "refs/heads/feat/v3"
+    },
+    "publicationRunBinding": {
+      "beforeArtifactDownload": [
+        "run.id",
+        "run.repository.full_name",
+        "run.head_repository.full_name",
+        "run.name",
+        "run.path",
+        "run.head_branch",
+        "run.head_sha",
+        "run.event",
+        "run.conclusion"
+      ],
+      "refRule": "qualificationWorkflow.ref is a full refs/heads branch ref; run.head_branch must equal its exact branch name",
+      "beforeEnvironmentApproval": "The content-validated candidate receipt metadataCommit must equal the API-backed run.head_sha"
+    }
+  },
+  "qualification": {
+    "source": {
+      "component": "release-source",
+      "inputs": [
+        "tracked_tree_except_package_version_gitRef",
+        "verification_policy",
+        "lockfile",
+        "node",
+        "npm",
+        "pnpm",
+        "gate_set"
+      ],
+      "gates": [
+        {
+          "name": "source",
+          "command": ["pnpm", "-C", "packages/cli", "run", "test:source"],
+          "owner": "packages/cli/scripts/verify-lane.mjs#source",
+          "correction": "pnpm -C packages/cli run test:source"
+        },
+        {
+          "name": "stress",
+          "command": ["pnpm", "-C", "packages/cli", "run", "test:stress"],
+          "owner": "packages/cli/scripts/verify-lane.mjs#stress",
+          "correction": "pnpm -C packages/cli run test:stress"
+        },
+        {
+          "name": "performance",
+          "command": ["pnpm", "-C", "packages/cli", "run", "test:performance"],
+          "owner": "packages/cli/scripts/verify-lane.mjs#performance",
+          "correction": "pnpm -C packages/cli run test:performance"
+        },
+        {
+          "name": "package",
+          "command": ["pnpm", "-C", "packages/cli", "run", "verify:package"],
+          "owner": "packages/cli/scripts/verify-lane.mjs#package",
+          "correction": "pnpm -C packages/cli run verify:package"
+        },
+        {
+          "name": "generated-overlap",
+          "command": ["pnpm", "-C", "packages/cli", "run", "verify:generated-overlap"],
+          "owner": "packages/cli/scripts/verify-generated-overlap.mjs#runGeneratedOverlap",
+          "correction": "pnpm -C packages/cli run verify:generated-overlap"
+        },
+        {
+          "name": "typecheck",
+          "command": ["pnpm", "-C", "packages/cli", "run", "typecheck"],
+          "owner": "packages/cli/package.json#scripts.typecheck",
+          "correction": "pnpm -C packages/cli run typecheck"
+        },
+        {
+          "name": "build",
+          "command": ["pnpm", "-C", "packages/cli", "build"],
+          "owner": "packages/cli/scripts/build-package.mjs#main",
+          "correction": "pnpm -C packages/cli build"
+        },
+        {
+          "name": "compact",
+          "command": ["node", "packages/cli/dist/bin/agentera.js", "check", "compact"],
+          "owner": "packages/cli/src/cli/commands/compact.ts#cmdGate",
+          "correction": "node packages/cli/dist/bin/agentera.js check compact"
+        },
+        {
+          "name": "capability-contract",
+          "command": [
+            "node",
+            "packages/cli/dist/bin/agentera.js",
+            "check",
+            "validate",
+            "capability-contract",
+            "--format",
+            "json"
+          ],
+          "owner": "packages/cli/src/cli/commands/validate.ts#cmdValidateCapabilityContract",
+          "correction": "node packages/cli/dist/bin/agentera.js check validate capability-contract --format json"
+        },
+        {
+          "name": "activation-conjunction",
+          "command": [
+            "node",
+            "packages/cli/dist/bin/agentera.js",
+            "check",
+            "validate",
+            "activation-conjunction",
+            "--format",
+            "json"
+          ],
+          "owner": "packages/cli/src/validate/activationConjunction.ts#activationConjunctionMain",
+          "correction": "node packages/cli/dist/bin/agentera.js check validate activation-conjunction --format json"
+        }
+      ],
+      "performanceEvidenceSchema": "agentera.entityAuthorityPerformanceEvidence.v1",
+      "overlapEvidenceSchema": "agentera.generatedOverlapEvidence.v1",
+      "gateEvidence": "A source receipt contains the exact ten governed gates in contract order. Every gate has its governed origin and phase, outcome passed, a finite non-negative duration, the exact executed/reused shape, and gate-relevant observations. Digest validation precedes semantic validation; either kind of one-field tampering fails closed.",
+      "activationConjunction": {
+        "gateIdentity": "agentera.activationConjunction.v1",
+        "classes": ["cli", "capability", "runtime", "reference", "state", "package", "bootstrap"],
+        "dimensions": [
+          "discovery",
+          "behavior",
+          "diagnostics",
+          "package_projection",
+          "instructions",
+          "adversarial"
+        ],
+        "checkIds": [
+          "cli.discovery",
+          "cli.behavior",
+          "cli.diagnostics",
+          "cli.package_projection",
+          "cli.instructions",
+          "cli.adversarial",
+          "capability.discovery",
+          "capability.behavior",
+          "capability.diagnostics",
+          "capability.package_projection",
+          "capability.instructions",
+          "capability.adversarial",
+          "runtime.discovery",
+          "runtime.behavior",
+          "runtime.diagnostics",
+          "runtime.package_projection",
+          "runtime.instructions",
+          "runtime.adversarial",
+          "reference.discovery",
+          "reference.behavior",
+          "reference.diagnostics",
+          "reference.package_projection",
+          "reference.instructions",
+          "reference.adversarial",
+          "state.discovery",
+          "state.behavior",
+          "state.diagnostics",
+          "state.package_projection",
+          "state.instructions",
+          "state.adversarial",
+          "package.discovery",
+          "package.behavior",
+          "package.diagnostics",
+          "package.package_projection",
+          "package.instructions",
+          "package.adversarial",
+          "bootstrap.discovery",
+          "bootstrap.behavior",
+          "bootstrap.diagnostics",
+          "bootstrap.package_projection",
+          "bootstrap.instructions",
+          "bootstrap.adversarial"
+        ],
+        "bounds": {
+          "maxRows": 320,
+          "maxViolations": 40,
+          "maxDiagnosticCharacters": 500,
+          "maxOutputBytes": 196608,
+          "maxGenerationIdCharacters": 36,
+          "maxPathCharacters": 240,
+          "maxSymbolCharacters": 120,
+          "maxSelectorCharacters": 240,
+          "maxCorrectionCharacters": 320,
+          "maxCheckIdCharacters": 80,
+          "maxSurfaceIdCharacters": 240
+        },
+        "owners": {
+          "cli": {
+            "path": "packages/cli/src/cli/dispatch/commands.ts",
+            "symbol": "DISPATCHER_TOP_LEVEL_COMMANDS",
+            "correction": "pnpm -C packages/cli test:source -- test/cli/activationConjunction.test.ts"
+          },
+          "capability": {
+            "path": "packages/cli/src/capabilities/index.ts",
+            "symbol": "CAPABILITY_INSTRUCTIONS",
+            "correction": "pnpm -C packages/cli test:source -- test/cli/activationConjunction.test.ts"
+          },
+          "runtime": {
+            "path": "packages/cli/src/runtime/lifecycleAuthority.ts",
+            "symbol": "loadLifecycleAuthority",
+            "correction": "pnpm -C packages/cli test:source -- test/runtime/runtimeLifecycle.test.ts"
+          },
+          "reference": {
+            "path": "packages/cli/src/validate/retainedReferenceAuthority.ts",
+            "symbol": "validateRetainedReferenceAuthority",
+            "correction": "node packages/cli/dist/bin/agentera.js check validate retained-references --format json"
+          },
+          "state": {
+            "path": "packages/cli/src/state/write/runtimeOperations.ts",
+            "symbol": "runtimeOperationSpecs",
+            "correction": "node packages/cli/dist/bin/agentera.js check validate state --format json"
+          },
+          "package": {
+            "path": "packages/cli/src/registries/packageRegistry.ts",
+            "symbol": "loadRegistry",
+            "correction": "pnpm -C packages/cli run verify:package"
+          },
+          "bootstrap": {
+            "path": "packages/cli/src/validate/bootstrapAuthority.ts",
+            "symbol": "bootstrapMatrixAuthority",
+            "correction": "pnpm -C packages/cli test:source -- test/cli/runtimeBootstrapMatrix.test.ts"
+          }
+        },
+        "census": {
+          "algorithm": "sha256(sorted_utf8_ids_joined_by_lf)",
+          "classes": {
+            "cli": {
+              "count": 27,
+              "sha256": "986a637f5c11c57ab7a897a01bd291d0811846e5339c3831c715932cf9659ad4"
+            },
+            "capability": {
+              "count": 12,
+              "sha256": "007e1157a892fec54182b1803aeaa442cf8e2e332e6a055c3bd020e2b0731867"
+            },
+            "runtime": {
+              "count": 81,
+              "sha256": "03fe600a3a27f05daf0d1b59c16b00bedc354a13c70ea60be0b457175fdf743c"
+            },
+            "reference": {
+              "count": 22,
+              "sha256": "2b48c82bb7ee10388d9ebb4fa7ea3743ea82a7e9aaedfcd5a858eeedb9d891ae"
+            },
+            "state": {
+              "count": 36,
+              "sha256": "a9f371e2f6d49e7cb890767d7dfe26edee11d4a7d28ee35ab6c491c0abafbbf0"
+            },
+            "package": {
+              "count": 66,
+              "sha256": "3548af7e84151c90690a6eb3d1cb6c7847f39b290161ecab599d8cb1bf0d2cb0"
+            },
+            "bootstrap": {
+              "count": 34,
+              "sha256": "71c2038744e2518a6adb722acbb5f9352bddfb5d1c92eeb0e347297ef2ca2f1e"
+            }
+          },
+          "total": {
+            "count": 278,
+            "sha256": "5767645b4d78d8716e7ea1a283125bcfd43e13634311b33b62bc0a307d1abdb3"
+          }
+        }
+      },
+      "reuseCheck": {
+        "command": "node packages/cli/scripts/release-qualification.mjs source-check --candidate-dir DIR [--json]",
+        "precommitEnvironment": "AGENTERA_PRECOMMIT_SOURCE_CANDIDATE_DIR",
+        "authority": "The external path is input only. Reuse requires digest, full receipt semantics, exact governed gates, current toolchain, and matching current staged and working tracked-tree identities under the same package version and agentera.gitRef normalization used at source qualification.",
+        "effects": "Runs no qualification gate and writes no repository, candidate, receipt, or registry state. Success emits executed none and reused true without receipt content or private paths.",
+        "fallback": "An absent environment variable preserves existing routing. A missing, invalid, ambiguous, or stale receipt never skips tests; pre-commit runs the existing broader policy.",
+        "scope": "Reused source evidence may skip only scripts/precommit-vitest.sh source/release policy execution. Build, compact, parity, candidate qualification, release metadata, approval, and publication remain mandatory at their owning stages."
+      },
+      "dag": {
+        "batchA": ["generated-overlap", "stress", "typecheck"],
+        "performanceBarrier": ["performance"],
+        "generatedOverlapOrigins": ["source", "package", "build", "generated-overlap"],
+        "barrierB": ["compact", "capability-contract", "activation-conjunction"],
+        "generatedOutputWriter": "generated-overlap",
+        "overlapCleanupMarginMs": 10000,
+        "overlapParentReconciliationMarginMs": 4000,
+        "minimumExecutionWindowMs": {
+          "compact": 3000,
+          "capability-contract": 3000,
+          "activation-conjunction": 6000
+        },
+        "failure": "The coordinator passes generated-overlap and the solo performance barrier the actual source deadline. Overlap stops owned work 10000ms before that deadline, settles and cleans its generated state, and returns at least 4000ms before the deadline for parent reconciliation. The first observed owner failure cancels only cancellable process groups. generated-overlap is cooperatively stopped and never force-killed; performance, barrier B, and receipt issuance remain blocked after any batch failure, and barrier B and receipt issuance remain blocked after any performance failure.",
+        "isolation": "Every child receives a distinct HOME, cache, user config, global config, and report output. Batch A provides output isolation. Performance additionally runs alone after batch A settles to provide resource isolation for machine-sensitive evidence."
+      },
+      "parallelism": "Batch A runs generated-overlap, stress, and typecheck concurrently. generated-overlap is the sole checkout generated-output writer and sole execution origin for source, package, build, and overlap evidence. After batch A settles and passes, performance runs alone in fresh isolated state. After performance passes, compact, capability-contract, and activation-conjunction run concurrently as readers of the settled generation."
+    },
+    "candidate": {
+      "component": "release-candidate",
+      "inputs": [
+        "source_receipt",
+        "metadata_commit",
+        "target_version",
+        "source_commit",
+        "adapter",
+        "package",
+        "registry",
+        "expected_tag",
+        "artifact_bytes",
+        "artifact_mode"
+      ],
+      "retainedArtifactMode": "0444",
+      "timing": "Candidate qualification records monotonic, non-overlapping release-metadata, construction/equivalence, and exact-artifact-smoke intervals at their true boundaries. Their sum cannot exceed measured candidate elapsed time; explicit unattributed overhead completes an exact reconciliation.",
+      "gates": [
+        "release-metadata",
+        "dry-pack-observation-equivalence",
+        "local-exact-artifact-smoke"
+      ],
+      "artifact": {
+        "receipt": "candidate-receipt.json",
+        "sourceReceipt": "source-receipt.json",
+        "mode": "0444",
+        "mustRemainWithinCandidateDirectory": true
+      }
+    }
+  },
+  "trust": {
+    "local": "A same-principal source receipt is a deterministic cache only. It cannot authorize registry mutation.",
+    "ci": "CI registry mutation requires the transferred exact artifact and receipts, a CI attestation bound to the candidate receipt and source run, and an explicit candidate-bound approval. OIDC provenance is deferred."
+  },
+  "registryStateTable": [
+    {
+      "state": "absent",
+      "exactVersion": "absent",
+      "candidateTag": "absent",
+      "expectedTag": "older-or-absent",
+      "stage": "upload exact artifact once",
+      "promote": "blocked"
+    },
+    {
+      "state": "staged",
+      "exactVersion": "matching integrity",
+      "candidateTag": "target version",
+      "expectedTag": "older",
+      "stage": "replay without upload and run observational smoke",
+      "promote": "move expected tag forward after exact-version qualification"
+    },
+    {
+      "state": "promoted",
+      "exactVersion": "matching integrity",
+      "candidateTag": "target version or retained history",
+      "expectedTag": "target version",
+      "stage": "replay without upload",
+      "promote": "replay without tag mutation"
+    },
+    {
+      "state": "conflict",
+      "exactVersion": "missing, changed, conflicting, or tag ahead",
+      "candidateTag": "any",
+      "expectedTag": "any",
+      "stage": "fail before mutation",
+      "promote": "fail before mutation"
+    }
+  ],
+  "benchmark": {
+    "environment": "Ubuntu runner or clean local Node 22, npm 10, and pnpm 10.30.3; record exact tool versions in receipts.",
+    "fixture": "clean committed checkout and an external empty candidate directory; no tracked or checkout-local generated candidate files.",
+    "cacheNetwork": "Preflight uses no registry call. Every qualification DAG child and each smoke use a distinct empty HOME, npm cache, user config, global config, and report output; public npm dependency network access is allowed and recorded as cold-cache. Publication reads the registry before credentials.",
+    "repetitions": 3,
+    "statistic": "Qualification reports median wall milliseconds over exactly three cold-cache repetitions. Concurrent owner-duration totals are reported separately; only owners in the same parallel phase overlap, while the solo performance barrier contributes ordered wall time. Phase timing reconciles through measured DAG wall time rather than by summing nested owner durations. Qualified publication reports one actual approved transaction because registry mutation is not a benchmark repetition; replays run the same measured envelope and report reused registry phases.",
+    "coordinator": "packages/cli/scripts/release-benchmark.mjs has separate qualification and publication commands. qualification runs only preflight and source-plus-candidate qualification and never receives npm credentials. publication runs only the approved stage, independent exact-version L2, and promote commands, measures them with one monotonic deadline, and never runs source qualification.",
+    "qualifiedPublication": {
+      "command": "node packages/cli/scripts/release-benchmark.mjs publication --adapter ADAPTER --candidate-dir DIR --receipt-file FILE",
+      "sequence": [
+        "stage retained bytes on the candidate tag, wait for exact integrity convergence, and observe an isolated exact-version registry smoke",
+        "run an independent exact-version L2 consumer check while the public tag is unchanged",
+        "promote the expected tag forward, wait for tag and integrity convergence, and observe the final exact-version registry smoke"
+      ],
+      "receiptBindings": [
+        "candidate_receipt_sha256",
+        "metadata_commit",
+        "package",
+        "version",
+        "artifact_sha256",
+        "artifact_integrity",
+        "source_run_id"
+      ],
+      "timing": "The coordinator measures commands with a monotonic clock. Caller-supplied elapsed data is not accepted. Component floors plus unattributed elapsed time must equal the measured total, and total elapsed time must be strictly less than qualifiedPublicationMs.",
+      "failure": "The first child failure label or timeout owner is retained, later phases do not start, and no rollback is attempted. A retry uses the same exact candidate; stage and promote replay matching registry state without upload or backward tag movement."
+    },
+    "timeouts": {
+      "preflightMs": 30000,
+      "sourceQualificationMs": 420000,
+      "qualifiedPublicationMs": 120000
+    },
+    "failureRule": "The first observed failing owner remains the reported label. Cancellable peers are stopped, generated-overlap is allowed to settle without forced termination, barrier B and receipt issuance are blocked, and completed/cancelled failures are reported. No timeout or failure authorizes repair, candidate work, or registry mutation."
+  },
   "bounds": {
     "registryAttempts": 6,
     "registryDelayMs": 5000,