agentera 3.0.0-dev.7 → 3.0.0-dev.74

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

@@ -0,0 +1,484 @@
+{
+  "schemaVersion": "agentera.packagePublication.v2",
+  "owner": "repository/package scripts",
+  "invariants": {
+    "preparation": "Preparation is pure and registry-independent. CI allocates rolling development package metadata in an isolated construction tree without changing the checkout. The manual readiness preparation path first validates a current normalized source receipt, then accepts an explicit target version and source commit. Stable preparation retains its separate source-provenance contract.",
+    "sourceQualification": "Source verification 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": "Package verification 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 package artifact through one measured stage, independent staged package migration smoke, and promote envelope. Stage and promotion include their required registry convergence and observational checks. The envelope never reconstructs an artifact, reruns source verification, or rolls a tag back.",
+    "approval": "Manual development and stable release machinery requires artifact-bound approval. The routine feat/v3 push path instead derives its immutable version and git ref from the GitHub run and push SHA, validates and smokes the exact isolated tarball, and publishes those bytes directly to next. Stable publication retains explicit protected-environment review on main after the stable workflows land on the default branch.",
+    "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 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": {
+      "label": "development TypeScript package",
+      "packagePath": "packages/cli",
+      "manifestPath": "packages/cli/package.json",
+      "expectedTag": "next",
+      "preparation": "incrementDevPrerelease",
+      "construction": "isolatedTypeScriptPackage",
+      "smoke": ["npx", "-y", "agentera@{version}", "--version"],
+      "localSmoke": ["agentera", "--version"]
+    },
+    "stable": {
+      "label": "transitional stable shim",
+      "packagePath": "packages/cli/shim",
+      "manifestPath": "packages/cli/shim/package.json",
+      "expectedTag": "latest",
+      "preparation": "incrementPatch",
+      "construction": "stableShim",
+      "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": "Publish development package",
+      "path": ".github/workflows/qualify.yml",
+      "ref": "refs/heads/feat/v3"
+    },
+    "developmentPush": {
+      "trigger": "push to refs/heads/feat/v3",
+      "versionAuthority": "GitHub Actions workflow run number plus the fixed migration offset",
+      "runNumberOffset": 72,
+      "rules": [
+        "version is 3.0.0-dev.(GITHUB_RUN_NUMBER + 72)",
+        "agentera.gitRef equals GITHUB_SHA",
+        "the checkout manifest is not modified",
+        "one isolated tarball is built, validated for version and git ref, and executable-smoked before those exact bytes are published to next",
+        "reruns reuse the same run number, SHA, and version; identical already-published bytes succeed without another upload",
+        "failed runs can create version gaps",
+        "before the first push, confirm qualify.yml is still unregistered at run 0 and npm 3.0.0-dev.73 is absent"
+      ],
+      "approval": "The routine push workflow publishes the locally validated exact tarball to next without the manual qualification, receipt, attestation, benchmark, approval, or artifact-handoff framework.",
+      "concurrency": "The publish-next-${{ github.ref }} group uses queue: max, which keeps up to 100 pending runs and does not cancel an active or pending push."
+    },
+    "stableVerificationWorkflow": {
+      "name": "Verify stable package",
+      "path": ".github/workflows/verify-stable.yml",
+      "ref": "refs/heads/main"
+    },
+    "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 package artifact receipt metadataCommit must equal the API-backed run.head_sha; development sourceCommit must also equal run.head_sha"
+    }
+  },
+  "qualification": {
+    "source": {
+      "component": "release-source",
+      "issuanceAuthority": "A new source receipt can be issued only by the contracted GitHub Actions source verification workflow at the committed checkout SHA. Existing valid receipts remain reusable through the read-only source check.",
+      "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": "capacity",
+          "command": ["pnpm", "-C", "packages/cli", "run", "test:capacity"],
+          "owner": "packages/cli/scripts/verify-lane.mjs#capacity",
+          "correction": "pnpm -C packages/cli run test:capacity"
+        },
+        {
+          "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 eleven 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": 25,
+              "sha256": "2094946cd6e189c6ab3db16dd0725596cec759abcea88d8335b05215b65ccfc2"
+            },
+            "state": {
+              "count": 38,
+              "sha256": "7ab0dd6ef1b1b1ce66bd9ea94d1de3d542528233e928a44102e289bf12416681"
+            },
+            "package": {
+              "count": 67,
+              "sha256": "d73cd86fed39057cf9ae73e462a59e842372392b1e88846f2b220378a2ff75cc"
+            },
+            "bootstrap": {
+              "count": 34,
+              "sha256": "71c2038744e2518a6adb722acbb5f9352bddfb5d1c92eeb0e347297ef2ca2f1e"
+            }
+          },
+          "total": {
+            "count": 284,
+            "sha256": "3f30b26839aec47639f2197c9efda5caf2a73d5afca9fb38ff9a341e18a72b98"
+          }
+        }
+      },
+      "reuseCheck": {
+        "command": "node packages/cli/scripts/release-qualification.mjs source-check --candidate-dir DIR [--json]",
+        "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 verification.",
+        "effects": "Runs no verification gate and writes no repository, package artifact, receipt, or registry state. Success emits executed none and reused true without receipt content or private paths.",
+        "fallback": "A missing, invalid, ambiguous, or stale receipt fails before manual readiness metadata effects. Serialized integration preparation and the local staged verification lane do not consume release receipts.",
+        "scope": "Manual readiness preparation uses the check as a source-readiness prerequisite. Direct diagnostics may inspect reuse without executing a gate. Build, compact, parity, package verification, release metadata, approval, and publication remain mandatory at their owning stages."
+      },
+      "dag": {
+        "batchA": ["generated-overlap", "stress", "typecheck"],
+        "performanceBarrier": ["performance"],
+        "capacityBarrier": ["capacity"],
+        "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, the solo performance barrier, and the serial capacity 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, capacity, barrier B, and receipt issuance remain blocked after any batch failure, capacity, barrier B, and receipt issuance remain blocked after any performance failure, and barrier B and receipt issuance remain blocked after any capacity failure.",
+        "isolation": "Every child receives a distinct HOME, cache, user config, global config, and report output. Batch A provides output isolation. Performance runs alone with one worker on the policy-declared authoritative runner after batch A settles. Capacity then runs serially before the reader barrier."
+      },
+      "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 with one worker. Capacity runs alone after performance. After capacity passes, compact, capability-contract, and activation-conjunction run concurrently as readers of the settled generation."
+    },
+    "readiness": {
+      "schemaVersion": "agentera.releaseReadiness.v1",
+      "component": "release-readiness",
+      "adapter": "development",
+      "command": "node packages/cli/scripts/release-readiness.mjs development --candidate-dir DIR --target-version VERSION --source-commit COMMIT [--metadata-commit COMMIT] [--json]",
+      "phases": ["source-readiness", "metadata-review", "candidate-readiness"],
+      "receipts": {
+        "source": "source-receipt.json",
+        "candidate": "candidate-receipt.json"
+      },
+      "reuse": "A present source receipt is validated with the source reuse check instead of invoking source verification. A present package artifact receipt and retained artifact are validated instead of invoking package verification. Invalid, stale, incomplete, or mismatched evidence rejects the run before an issuance owner starts.",
+      "metadataReview": "A successful source verification or source-receipt reuse pauses before package artifact construction until the caller supplies the explicit reviewed metadata commit. The coordinator never prepares metadata, changes a version, commits, approves, rebuilds a valid package artifact, stages bytes, or mutates registry state.",
+      "outcomes": ["paused", "ready", "rejected"],
+      "exitCodes": {
+        "paused": 0,
+        "ready": 0,
+        "rejected": 1
+      }
+    },
+    "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": "Package verification records monotonic, non-overlapping release-metadata, construction/equivalence, and exact-artifact-smoke intervals at their true boundaries. Their sum cannot exceed measured package verification 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": "Manual CI publication requires transferred artifacts, receipts, attestation, and artifact-bound approval. The routine feat/v3 push workflow is separate: it validates, smokes, and publishes one local isolated tarball directly. Stable main publication requires protected-environment review. 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 staged package migration smoke"
+    },
+    {
+      "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 empty external artifact directory; no tracked or checkout-local generated package artifacts.",
+    "cacheNetwork": "Preflight uses no registry call. Every verification 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": "Package verification 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 and serial capacity barriers contribute ordered wall time. Phase timing reconciles through measured DAG wall time rather than by summing nested owner durations. 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 verification and publication commands. verification runs only preflight and source-plus-package verification and never receives npm credentials. publication runs only the approved stage, independent staged package migration smoke, and promote commands, measures them with one monotonic deadline, and never runs source verification.",
+    "qualifiedPublication": {
+      "command": "node packages/cli/scripts/release-benchmark.mjs publication --adapter ADAPTER --candidate-dir DIR --receipt-file FILE",
+      "sequence": [
+        "stage the retained package artifact on the staging tag, wait for exact integrity convergence, and observe an isolated exact-version registry smoke",
+        "run an independent staged package migration smoke 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 package artifact; stage and promote replay matching registry state without upload or backward tag movement."
+    },
+    "timeouts": {
+      "preflightMs": 30000,
+      "sourceQualificationMs": 2400000,
+      "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, package construction, or registry mutation."
+  },
+  "bounds": {
+    "registryAttempts": 6,
+    "registryDelayMs": 5000,
+    "commandTimeoutMs": 120000,
+    "diagnosticCharacters": 1000
+  }
+}