@volter/twin-catalog 0.2.2

package/docs/operations.md

@@ -0,0 +1,91 @@
+# Operate a catalog
+
+Select the catalog and publisher repositories for the operation. Use the authorized production or test targets; these commands do not select public source scope or alter an existing World. The [process contract](process.md) owns admission authority; [contributor instructions](contributing.md) own independent publishing.
+
+## Responsibilities and access
+
+`CODEOWNERS` and repository permissions name the moderators; current policy names authorized maintainers and direct trusted accounts. The operator records an incident owner and GitHub failure-notification recipients in the handoff. Repository ownership alone does not prove notifications are configured. An untrusted outside contributor and a distinct authorized human moderator are required to rehearse the outside review path. A trusted-account rehearsal does not require that review.
+
+The catalog read App has administration, contents, checks and pull-request read access to the selected catalog. Its key is in `CATALOG_READ_APP_PRIVATE_KEY`; its client ID is a repository variable. The separate publisher App has contents and pull-request write access, without administration; its key is in `CATALOG_PR_APP_PRIVATE_KEY` in the trusted publisher. Both workflows mint target-scoped short-lived tokens and revoke them afterward. Contributors use their own GitHub and npm authority, never these keys. Registry publication uses trusted publishing or the configured `NPM_TOKEN`. Record registry package/workflow scope separately from GitHub App scope.
+
+## Find and retain a failure
+
+Set the selected repository names, then list runs in the repository that owns the failed phase:
+
+```sh
+catalog_repository="<catalog-owner/catalog-repository>"
+publisher_repository="<publisher-owner/publisher-repository>"
+gh run list --repo "$publisher_repository" --workflow release.yml
+gh run list --repo "$catalog_repository" --workflow check.yml
+gh run list --repo "$catalog_repository" --workflow publish.yml
+```
+
+Inspect the chosen run and retain its artifacts in a new directory:
+
+```sh
+gh run view <run-id> --repo <owner/repository> --log-failed
+gh run download <run-id> --repo <owner/repository> --dir <new-evidence-directory>
+```
+
+Record source SHA, attempt, submission identity and PR head/base alongside the diagnostics. Pack artifacts retain bytes, submission data and the installed catalog CLI lock. Assessment artifacts retain the input-bound report, dependency lock and preparation/cleanup logs. Index publication retains its receipt; durable evidence is also bundled in the index and linked from the evidence release. A failed or missing report is never reconstructed as a pass.
+
+## Recover pack publication
+
+An accepted upload is immutable. If `upload-accepted.json` exists, confirmation is unresolved, or an upload result is uncertain, never upload that version again. Inspect exact registry identity against retained bytes. A rerun of the original workflow uses `GITHUB_RUN_ATTEMPT > 1` and cannot upload:
+
+```sh
+gh run rerun <publisher-run-id> --repo "$publisher_repository" --failed
+```
+
+Its source, lock and rebuilt archive must still match the registry integrity. A mismatch refuses and needs investigation, not a changed version attached to old evidence. For retained-byte confirmation in a publisher that implements the retained-byte recovery command, use its exact checkout and retained `release/` directory; point `CATALOG_CLI` at the exact installed released CLI and run `node scripts/publish.mjs --confirm-only`. This path performs reads and writes its receipt without upload or proposal credentials.
+
+Independent publishers may use different release tooling; they must preserve the same immutable bytes and read-only confirmation rule. The commands above describe the shipped Volter publisher workflow.
+
+A new first-attempt dispatch can upload an absent version. Use it only after evidence proves a prior failure happened before upload, or for a newly prepared immutable version. It is not the recovery command for an accepted or uncertain upload.
+
+Proposal recovery uses canonical retained submission JSON. The publisher workflow's `propose --send` returns the existing PR even if it is closed; it does not reopen it, approve it or create a duplicate. A rejected release is not silently resubmitted. Artifact fixes require a new version. A proposal transport failure needs no package upload.
+
+## Recover assessment
+
+Preparation confirms both the exact-version registry view and npm's installation view. Visibility can lag independently. Confirmation is bounded by the existing measured registry policy, performs reads only and checks exact integrity. Only 404 and an otherwise valid installation document missing that version are retried. Permission errors, malformed identities and conflicting bytes remain refusals.
+
+For an infrastructure failure, explicitly reassess the current PR:
+
+```sh
+gh workflow run check.yml --repo "$catalog_repository" --ref main -f pr=<pr-number>
+```
+
+The job uses trusted current source and reads candidate data at the exact head. A changed head or base needs fresh evidence. Check the resulting report and current-head readiness; an older success or local report is insufficient. Candidate defects need a new immutable package version. The automation neither approves nor merges.
+
+Untrusted-account submissions need genuine current-head non-author human moderator approval. Direct trusted-account contributions, including forks, and eligible internal changes may use the named maintainer exception; every path still requires current-head readiness. Verify the author against `policy.trustedAccounts` using GitHub ID, login and type. Never use administrator merge to bypass missing untrusted-account review or a failed check.
+
+## Recover index publication
+
+Retry current protected main after resolving the recorded cause:
+
+```sh
+gh workflow run publish.yml --repo "$catalog_repository" --ref main
+```
+
+The workflow verifies admission and protection, then reuses a published version only when source and digest match. It cannot overwrite a conflicting identity. Retain the new receipt and compare registry integrity before calling the upload confirmed. No platform build, candidate test or hosted deployment is part of this job.
+
+## Recommend, reject or revoke
+
+A moderator rejects a PR with a concrete reason. An unmerged readiness success adds no release to the index.
+
+With multiple live implementations, change `recommendations.json` in a separate maintainer PR to select the package. Versions from different publishers never compete. Selection within that package offers its newest live stable approved release.
+
+To withdraw an admitted release, append its exact package/version and a nonempty reason to `revocations.json` in a maintainer PR. Remove or replace a recommendation that would otherwise have no selectable release. After current-head readiness and moderator merge, index publication changes future defaults. It preserves immutable package bytes, prior evidence and existing World pins; it does not remotely uninstall a pack.
+
+## Pause distribution and replace credentials
+
+Pause future work without deleting artifacts or rewriting history:
+
+```sh
+gh variable set PACK_PUBLISH_ENABLED --repo "$publisher_repository" --body false
+gh variable set CATALOG_PUBLISH_ENABLED --repo "$catalog_repository" --body false
+```
+
+These flags govern future jobs; they do not recall published packages or settle an in-flight upload. Preserve its receipts and inspect the outcome separately. Re-enable the intended flag only after the incident is resolved.
+
+For an App key replacement, inventory selected repositories and consumers, generate an additional key, store it directly in the correct encrypted repository secret, and confirm the intended workflow's access before revoking the old key. Never print or commit a key, broaden an installation to every repository, or remove another consumer's key. Keep read and proposal roles separate. For npm replacement, use approved custody or trusted publishing and restrict package/workflow scope appropriately. Document identity, target and replacement outcome without secret values.

package/docs/process.md

@@ -0,0 +1,308 @@
+# Catalog process
+
+This repository operates admission and distribution of twin packages from independent publishers. The platform owns
+the runtime, Protocol 3 and the versioned standard. Publishers own their source and npm releases. This repository
+owns source registration, submissions, evaluation policy, moderator decisions and the approved index. It requires
+released tools, not a platform checkout. Its executable contract is the modules in `lib/` and the workflows in
+`.github/workflows/`; `bin/twin-catalog.mjs` exposes the same operations to contributors and automation.
+
+## Identity and authority
+
+A vendor is a service being simulated. An implementation is an npm package. A release is an exact package version
+with a SHA-512 integrity value. A source is a registered GitHub repository, npm scope and release-workflow identity.
+One repository may publish several packages. Several repositories may implement the same vendor. Package names are
+not vendor identities. Version ordering applies only within one package, never between competing implementations.
+
+`sources.json` registers sources. Registration is its own separately authorized PR; a submission cannot grant its source
+trust, change evaluation tools, or change catalog policy. `official` identifies Volter maintenance, not a verification
+exemption or vendor endorsement. Every new release follows the same readiness requirements. Contributions from untrusted accounts
+require current-head human moderator approval. Direct submissions from an account explicitly listed in
+`policy.trustedAccounts` need no separate moderator review, including fork PRs. Each entry binds the numeric
+GitHub account ID, exact login and account type (`User` or `Bot`). Trust is checked against the PR author returned
+by GitHub, never a commit author, fork owner, organization membership or submission field. A maintainer named in
+`policy.reviewBypassUsers`, with current `admin` or `maintain` permission, merges after current-head readiness.
+Publication records this path as `trusted-account-merge` with the submitting account identity; it does not claim
+human review. Trust does not exempt source registration, artifact integrity, provenance or assessment.
+Maintainers may merge their own changes without a separate review.
+Internal admissions require the registered repository to be explicitly listed in `policy.internalRepositories`,
+a PR branch in this catalog repository, and a merge by a maintainer named in `policy.reviewBypassUsers` whose current
+GitHub permission is `admin` or `maintain`. The author must be a repository member/collaborator or its GitHub Actions
+bot, or a publisher bot explicitly named in `policy.internalBotAuthors`. Each configured publisher bot binds both
+its GitHub user ID and exact login; its App registration ID is a different identity. An unconfigured or mismatched
+bot remains outside the internal path. A bot author or `official` badge alone does not make an outside publisher internal.
+Public-source npm provenance is required for new admissions. Existing index records without an assessment remain
+historical records, explicitly unassessed; migration does not manufacture evidence or reapprove them. A separate
+`reassessments/<id>.json` PR uses the same immutable submission schema, checks and moderator review to assess an
+unassessed historical release without rewriting its admission commit. Missing original provenance still fails;
+publishing and admitting a new version is the repair.
+
+`recommendations.json` explicitly selects the default package when a vendor has multiple live implementations.
+One live implementation is unambiguous. With several and no recommendation, resolution refuses to guess. A
+recommendation is moderated separately from a submission and selects a package, whose newest stable approved
+version is offered. Prereleases require an explicit version. A World pins package and version; a catalog update
+does not change that pin. Removing a recommendation is not uninstalling a running World.
+
+## Submission
+
+A release PR adds exactly one `submissions/<id>.json`, with no executable files or index edits:
+
+```json
+{
+  "schemaVersion": 1,
+  "source": "example-team",
+  "vendor": "stripe",
+  "package": "@example/stripe-simulator",
+  "version": "1.2.3",
+  "integrity": "sha512-BASE64_OF_THE_ARTIFACT_DIGEST"
+}
+```
+
+The id is the SHA-256 of the canonical submission fields. The CLI reads registry metadata and creates the file;
+it does not run package code, publish a package, open a PR, or send a message. The author opens the PR normally.
+The registry is catalog policy, not contributor input. Tags, ranges, URLs, git dependencies and mutable versions
+are not release identities. Artifact package.json must match the submitted package and version, declare a license,
+and name the registered repository. Generated pack facts must identify exactly the submitted vendor and Protocol 3.
+An already admitted package/version cannot acquire different bytes or a different vendor/source.
+
+The catalog evaluates only the tarball fetched at the declared integrity. Package source in the contributor's
+repository and evidence supplied in the PR are context, never substitutes for running that artifact. A submission
+cannot select its own evaluator, thresholds, registry, commands or privileges.
+
+## State and invalidation
+
+| State | Evidence | Next action |
+|---|---|---|
+| Submitted | A release PR with valid data | Automation resolves the artifact |
+| Checking | Current-head readiness check in progress | Automation evaluates |
+| Changes needed | Validation, evaluation or replay failed | Contributor updates and resubmits |
+| Ready | Required checks passed for this head and policy | Untrusted authors obtain moderator approval; trusted accounts proceed to authorized maintainer merge |
+| Approved | Required checks remain current; untrusted authors have current-head review, or an explicit trusted-account/internal exception applies | Authorized maintainer merges |
+| Admitted | Authorized merge on protected main through human review, trusted-account admission or the internal maintainer path | Publication builds the index |
+| Rejected | Moderator closes the PR with a reason | New submission if corrected |
+
+Readiness is not approval. Catalog assessment never approves or merges. Review dismissal on new commits, required current-head checks,
+CODEOWNERS review and a branch rule requiring the branch to be current enforce the decision. A moderator's identity
+comes from GitHub review and merge events, never a contributor's `by` string. Self-approval is not accepted as review.
+Named maintainers have a review bypass for internal changes and direct trusted-account contributions; untrusted
+admissions still need human review. Every path needs current-head readiness. Publication records which admission path and merger established authority.
+The repository's installation command checks/configures these rules explicitly; merely committing a workflow is not
+evidence that they are enabled. No credentials or repository settings are changed by an ordinary build.
+
+An assessment binds the PR number and head SHA, base SHA, source registration, submission, policy, evaluator package
+versions, container image identity, artifact integrity and resolved dependency lock. Evidence from an earlier head
+does not satisfy a new one. A base update requires updating the branch and a new readiness run. Jobs cancel superseded
+runs; their historical reports remain evidence only. A merged policy change affects subsequent admission runs; it
+does not retroactively certify old releases under the new policy. Publication checks the admitted submission identity. Identical reruns retain their inputs and produce comparable
+results. A failed or interrupted run has no successful readiness receipt.
+
+## Execution boundary
+
+PR data is read using the GitHub API from the exact head. Trusted automation is checked out from the base commit,
+never the contributor's head. Source-registration and maintenance PRs do not execute candidate scripts. All package
+extraction, dependency installation and evaluation occur in disposable containers with no repository, npm, cloud,
+moderation or publication credentials, no Docker socket and no host project mounts. Install scripts are disabled.
+Dependencies are resolved once into a recorded lock; evaluation reuses that installation with network disabled.
+Before dependency installation, preparation confirms the candidate's exact version and integrity in npm's
+installation metadata as well as its exact-version metadata. These registry views may propagate separately.
+Only HTTP 404 or an otherwise valid package document without that version is retried, using the existing measured
+registry confirmation window. HTTP errors, malformed identities and conflicting integrity fail immediately.
+Confirmation performs reads only; it never uploads, grants readiness or retries candidate installation scripts.
+Input data is readable by the container's unprivileged user. Setup and preparation failures produce a failed JSON
+envelope as well as diagnostics; neither can establish readiness. Owner-dispatched verification walks a synthetic
+browser transport fixture through the same offline boundary before assessing an actual artifact. The fixture checks
+fresh cookie jars, complete request headers, binary bodies, empty responses, CORS and replay equality; it grants no admission.
+The versioned standard owns this fixture. Missing CORS permission remains a denial even when Playwright would add
+mock-response permission. Context teardown is awaited before the next replay.
+A separate public-tooling fixture verifies a real npm SLSA bundle and rejects substituted bytes and repositories.
+Process verification also builds and installs the index tarball and runs its consumer CLI in a directory without
+platform packages or pack checkouts. This checks distribution packaging without claiming a registry publication.
+Registry publish receipts are distinct from repository provenance; SHA-512 subjects emitted by npm and SHA-256
+subjects are checked against the downloaded artifact, with conflicting declared digests refused.
+The released standard declares its separate SDK fixture directories. Preparation installs those trusted, frozen
+locks with scripts disabled and retains them in the receipt, so their client cases need no installation offline.
+Owner verification may expect the specific missing-provenance refusal for a historical fixture. That verifies the
+negative path while retaining its changes-needed envelope; it cannot create the admission workflow's readiness check.
+Preparation's registry reads and evaluation's offline phase are reported separately. A World alone is cooperative
+routing, not the isolation boundary: the container enforces the evaluation network boundary.
+
+The trusted controller owns success/failure, hashes and run identity. Candidate output is untrusted data; bounded
+report parsing never executes it or interpolates it into a shell. It can explain results but cannot confer merge or
+publication authority. The trusted summary renderer escapes contributor strings and neutralizes mentions. Raw logs
+and JSON evidence are downloadable artifacts. There is no execution of arbitrary contributor-supplied test commands.
+Conformance and journey checks are the versioned standard's own entrypoints. Like any in-process plugin check, they
+measure cooperative pack behavior, not a proof that malicious executable code cannot deceive a test; moderator
+source review remains part of admission.
+
+Provenance verification checks the registry signature/attestation using npm's verifier, cryptographically verifies the exact downloaded Sigstore bundle, and checks the attested
+repository/workflow against the registered source. A certificate-shaped string alone is not verification. The
+artifact digest is independently recomputed. Private-source publication without provenance cannot claim readiness.
+
+## Evaluation and reports
+
+The versioned `@volter/twin-standard` owns the checks and machine-readable assessment API. The catalog invokes it;
+it does not implement another Protocol 3 grader or journey engine. Evaluation occurs inside a task-owned World.
+
+Quick assessment walks the packaged customer journey twice from fresh state with the same clock and World draws.
+It reports failures, answered steps, response replay equality, and served/gap counts over the entire declared surface. Actual operation coverage comes from kernel dispatch, with
+every declared gap retained in the denominator; declared support and exercised coverage are separate fields.
+An empty journey or missing response trace cannot establish replay. Unsupported instrumentation is `null`/not measured,
+never zero or 100%. Quick assessment does not claim browser DOM coverage, real-vendor parity, line coverage, or complete
+state-transition coverage. Those require their own instruments. HTTP-only journeys also replay twice through Chromium's fetch, cookie jar and HTTP response behavior, using the same
+walker and operation observer. Mixed or non-HTTP wires report browser measurement as unavailable. This target measures
+no DOM interactions or real-vendor parity. World and JavaScript clocks are frozen; Chromium's process wall time follows
+World time through libfaketime, at one-second native precision. Monotonic timers retain elapsed machine time. Verification
+checks both native `Expires` and `Max-Age` across a World clock advance; no expiry headers are rewritten. The exact
+Chromium version, clock precision and browser replay results are reported.
+
+Admission adds form checks for every unit and full deterministic conformance. A failure in any required check blocks
+readiness; a grade percentage is informational, not a threshold. Missing optional coverage is shown explicitly.
+Comparison to the previous approved version names added/removed served operations, failure counts and changed denominators;
+it never compares two different publishers' percentages as though they share a surface. A missing baseline is
+reported, not treated as no regression. Evaluation reports and catalog output are JSON for later page integration.
+
+Reports identify measurement scope, inputs, tool versions and execution target. Publisher evidence and independent
+catalog measurements remain distinguishable. A moderator may reject an otherwise passing submission for implausible
+journeys, misleading scope, provenance problems, maintenance concerns or source defects, with a concrete reason.
+
+## Discovery and consumer integration
+
+The npm artifact is the distribution interface. `catalog.json` schema 1 lists every recorded vendor/package/version,
+its source, status, integrity when known, and evidence reference. `assessed: false` and `evidence: null` explicitly mark
+historical records. Consumers read `recommendations.json` and `revocations.json` beside it. Displaying a recorded
+release is different from offering it as an install default: pending, rejected, revoked and prerelease versions are
+never automatic selections. A missing or failing assessment is never inferred from a publisher badge.
+
+A future catalog page groups implementations under a vendor, attributes the repository and publisher, and links to
+the immutable version and admission PR/evidence. It can display readiness, support counts, journey failures and replay
+results separately. A contributor sees the PR check, one updated feedback comment, and downloadable workflow artifacts.
+Readiness checks bind the report digest, workflow run ID and attempt in their external receipt. GitHub may replace
+the display URL and attach a manually dispatched check to an older PR check suite; that display association is not
+the report's source. After authorized merge, publication fetches the exact recorded workflow attempt and requires
+success, the trusted readiness workflow, and the report's bound input identity. A manual dispatch runs at the bound
+trusted base; a pull-request-target run names the submitted head. Older receipts retain their validated run URL or
+unique check-suite/head association. An unrelated workflow, source commit, attempt or substituted artifact cannot
+supply evidence. The publisher then validates
+the report against that receipt and stores it in a GitHub evidence release and in the index package's `evidence/`.
+Reports include the resolved dependency lock. Workflow logs remain supplementary artifacts with configured retention.
+If evidence expires before its first durable copy, publication refuses; it never reconstructs a passing report.
+This process supplies data for a browse page and does not deploy one.
+
+`volter world init` uses the installed catalog's selected exact package version when installing a missing vendor.
+Already installed pack identities come from their generated facts. Multiple installed implementations require a
+recommendation or an explicit World package choice; unrelated version numbers cannot resolve that choice. Existing
+World pins remain subject to the runtime's normal version checks. Revocation changes future catalog selection, not
+an existing World's declared dependency; the catalog cannot remotely uninstall code from an application.
+
+## Merge and publication
+
+The publication workflow runs only when the repository variable `CATALOG_PUBLISH_ENABLED` is `true`; activation
+follows successful Actions verification and moderator configuration. Protected main is the admission ledger. Submission files are immutable after admission. The publisher rebuilds from
+the existing index and merged submissions, adding versions without altering historical identity. It writes
+`sources.json`, `vendors/`, `recommendations.json` and machine-readable catalog metadata into the package artifact.
+Each admitted version links to its submission and merge commit; the GitHub PR retains reviews and readiness artifacts.
+Index generation does not import a pack, execute tests or rebuild the platform. The website and hosted runtime are
+independent consumers of the published index; their absence or build failures do not block index publication.
+
+The publisher verifies branch protection and merger permissions with read-only GitHub App access, separate from
+its index/evidence write token. Install the App only on the catalog repositories with administration, contents,
+checks and pull requests set to read. Store its client ID in `CATALOG_READ_APP_CLIENT_ID` and private key in
+`CATALOG_READ_APP_PRIVATE_KEY`. The pinned token action requests those permissions only for the current catalog
+repository and revokes its installation token after the job. The key is available only to the trusted publication
+job; candidate preparation and evaluation remain credential-free. A preconfigured equivalent `CATALOG_READ_TOKEN`
+is supported for existing operators. Missing read access fails admission verification and cannot bypass it.
+
+Trusted pack repositories use a separate publisher App to propose immutable data PRs. Install that App only on the
+target catalogs with contents and pull requests set to write, without administration. Store its client ID as
+`CATALOG_PR_APP_CLIENT_ID` and key as `CATALOG_PR_APP_PRIVATE_KEY` in the trusted publisher repository, never in
+candidate evaluation. Its workflow mints a short-lived token restricted to the target catalog and revokes it after
+proposal. App-authored PR events start catalog readiness through GitHub's normal event flow; the publisher does not
+dispatch or choose an evaluator. Existing scoped `CATALOG_PR_TOKEN` deployments remain supported. Outside publishers
+do not receive Volter's App key: they register their own source and submit through their own GitHub account or fork.
+
+Publication is serialized and starts from a clean checkout of current protected main. An obsolete queued job refuses
+to publish, so it cannot move the registry default backwards; retry on current main includes its admitted releases.
+A release identifies its source commit and npm artifact; retrying the same commit reuses
+the same version, verifies identity if it already exists, and does not publish a duplicate. A registry conflict with
+different identity fails. A publish failure leaves the admitted ledger intact and is retryable; it does not mark
+anything deployed. Credentialed publication never evaluates candidate code. Rejection records remain in closed PRs;
+they are not added to the resolvable index. Revocation of an admitted version is an explicit moderator-maintained
+record with a reason; it removes the version from future selection without rewriting its artifact or existing pins.
+
+After npm accepts an upload, publication confirms the exact version with read-only registry requests. A temporary
+404 is pending propagation, not a second upload: confirmation retries every 15 seconds for up to ten minutes.
+Matching source identity and integrity are still required; conflicting identity and other HTTP refusals fail
+immediately. Exhausted confirmation reports an unverified upload and leaves the admitted ledger intact.
+The window rounds up three times the observed confirmation delay; it is not a registry availability guarantee. Its
+[captured measurement](measurements/registry-confirmation.json) records the source commit, real Actions mode,
+concurrent work, commands and UTC observations; repeat it on a fresh sandbox version when registry behavior changes.
+
+## Contribution and operation
+
+### Read the published catalog
+
+Catalog discovery reads an installed index package through `browse` or the package's `./browse` export. It reads
+JSON only, without Git, network access, platform login or candidate imports. The adapter checks the package/catalog
+source and digest against the index records and evidence references, then checks each bundled report against its
+recorded digest and release identity. Package tarball integrity remains the installer's responsibility; the caller
+may retain its verified lockfile integrity with the snapshot, but the adapter does not manufacture it.
+
+The projection preserves every implementation and version, including historical, pending, rejected and revoked
+records. Selectability, recorded status, assessment availability and default choice are separate fields. Selection
+uses the existing catalog default rule for each vendor. A vendor with competing packages remains browsable with
+`choice-required`; ambiguity does not hide the other vendors or compare versions across publishers.
+
+Measurements come only from checksum-bound catalog reports. Declared surface, dispatched operation coverage,
+journey failures, replay and browser execution retain their scopes and denominators. Missing measurements are
+`null`; coverage is never an admission score. Contribution links point to this catalog's repository and published
+instructions. This read projection grants no admission authority and does not replace the canonical schema-1 data.
+
+### Prepare a source registration
+
+`register` prepares the one-source addition to a selected catalog snapshot's `sources.json`. It validates the same
+source fields as assessment, refuses an existing conflicting source or a different output file, and writes data
+only. Run it in a fork or pass a new output path when using an installed package. Source registration remains a
+separate PR; the command neither publishes a package nor opens, approves or merges that PR.
+
+Contributors can create and index fixed pack files, derive their vendored spec, compile package facts and assess
+with released `twin-standard` commands. Contributors need a public source repository, their own scoped npm package and the released SDK/standard. No Volter
+checkout, private company record or particular pack-repository layout is required by the catalog. Source registration,
+submission, checking, generation and publishing commands are documented in README. Published CLI tooling includes
+the schema/validation code, so contributors see the same refusals before opening a PR.
+
+Automation maintains one PR feedback comment, includes the report in the check summary, and updates it on reruns.
+GitHub reads retry one transport failure; HTTP refusals and writes are not retried. A transport failure identifies
+the method, repository path and underlying error code. A passing evaluation remains retained evidence until GitHub
+successfully records its current-head readiness check; it does not grant admission on its own.
+Manual workflow dispatch can reassess a PR after an external failure. Moderators configure membership through the
+repository's CODEOWNERS users or teams; platform write access is not required. Repository setup and npm publication are explicit
+operator actions. Deploy tokens, website changes, making repositories public, and operating GitHub settings are not
+performed as part of implementing this process.
+
+## Acceptance cases
+
+The acceptance contract below spans process fixtures and the isolated evaluator. Local fixture results cover only
+the cases they exercise; container/provenance execution and browser execution must be reported separately. Verification
+uses synthetic inputs where possible and never real publication:
+
+1. An independently scoped, arbitrarily named package maps to its declared vendor and remains pinned when used.
+2. Two packages for one vendor are retained; no cross-package semver comparison chooses the winner. Recommendation
+   selects the default; absent or revoked choices fail visibly.
+3. A submission cannot alter source trust, policy, workflows, commands, index records or an admitted submission.
+4. Changed bytes, package identity, vendor facts, provenance, head, base or evaluator invalidate the corresponding
+   assessment. Failed, cancelled or missing checks never become ready or admitted.
+5. Empty/mismatching replay fails; passing checks and partial surface remain separate measurements.
+6. Untrusted-account admissions require current-head human moderator review after readiness; approval of an old head
+   and contributor-supplied reviewer names cannot admit a release. A directly trusted account may omit a separate
+   review, including from a fork; account ID, exact login and type must match policy. The separate internal publisher
+   path needs an explicitly trusted source and a same-repository PR. Both exceptions require a named authorized
+   maintainer merge with verified current permission. Every path requires current-head readiness; fork ownership,
+   a bot author or an official badge alone grants no exemption. Catalog workflows have no merge path.
+7. Merging adds one immutable release, preserves other publishers and pins, and produces an index without a platform
+   checkout, hosted build or website.
+8. Publication retry is idempotent; a conflicting published identity fails, and a revoked release is not recommended.
+
+Results state exactly what ran. Static workflow inspection and local fixture checks are not a real GitHub/npm
+activation, and a local quick assessment is not a browser fidelity result.
+
+After npm accepts an upload, publisher submission preparation may use `submit --confirm-published`. It waits only
+for exact-version HTTP 404 propagation, with the same measured bound as index confirmation, and performs no upload.

package/lib/automation.mjs

@@ -0,0 +1,75 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { classify, loadIndex, read, write, digest, requireThat, validateIndex, compareReports, compareVersions } from './model.mjs';
+import { builtIndex } from './publication.mjs';
+import { evaluate } from './runner.mjs';
+import { summary, feedback } from './github.mjs';
+
+export async function assessPullRequest(root, github, number, output, evaluator = evaluate) {
+  requireThat(Number.isSafeInteger(number) && number > 0, 'PR number must be a positive integer');
+  const pr = await github.call(`pulls/${number}`);
+  requireThat(pr.state === 'open', 'PR is not open');
+  const local = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8' });
+  requireThat(local.status === 0 && local.stdout.trim() === pr.base.sha, 'trusted checkout must match the current PR base; update/retry the workflow');
+  const head = pr.head.sha;
+  const check = await github.call('check-runs', 'POST', { name: 'catalog/readiness', head_sha: head, status: 'in_progress', external_id: `${number}:${head}:${pr.base.sha}` });
+  const input = { schemaVersion: 1, repository: github.repository, pullRequest: number, head, base: pr.base.sha, policy: read(join(root, 'policy.json')) };
+  let envelope;
+  try {
+    const files = await github.pages(`pulls/${number}/files`);
+    requireThat(files.length === pr.changed_files, 'GitHub did not return the complete change; refuse truncated PR data');
+    const contents = {};
+    for (const file of files) if (/^(submissions|reassessments)\/|^(sources|recommendations|revocations)\.json$/.test(file.filename) && file.status !== 'removed') contents[file.filename] = await github.content(file.filename, head);
+    const index = builtIndex(root);
+    const kind = classify(files, index, contents);
+    input.kind = kind.kind;
+    if (['submission', 'reassessment'].includes(kind.kind)) {
+      input.submission = kind.submission; input.source = kind.source;
+      envelope = await evaluator(root, input, output);
+      const previous = index.vendors.find((v) => v.vendor === kind.submission.vendor)?.packages.find((p) => p.name === kind.submission.package)?.versions.filter((v) => v.status === 'live' && v.integrity && !v.version.includes('-')).sort((a, b) => compareVersions(b.version, a.version))[0];
+      if (previous && envelope.report) {
+        try {
+          const baselineInput = { ...input, submission: { ...kind.submission, version: previous.version, integrity: previous.integrity }, purpose: 'baseline' };
+          const baseline = await evaluator(root, baselineInput, `${output}.baseline.json`);
+          envelope.report.comparison = compareReports(envelope.report, baseline.report);
+        } catch (error) { envelope.report.comparison = { baseline: previous.version, measured: false, note: `Baseline could not be measured: ${error.message}` }; }
+      }
+    } else {
+      // Maintainers decide maintenance; never execute the PR's candidate workflows.
+      envelope = { schemaVersion: 1, input, inputSha256: digest(input), status: 'ready', report: null, note: `${kind.kind}: data validation only; no package assessment` };
+    }
+  } catch (error) {
+    envelope = { schemaVersion: 1, input, inputSha256: digest(input), status: 'changes-needed', error: String(error.message ?? error) };
+  }
+  const current = await github.call(`pulls/${number}`);
+  if (current.head.sha !== head || current.base.sha !== input.base || current.state !== 'open') { envelope.status = 'superseded'; envelope.error = 'PR head, base or state changed during assessment; current input needs a new run.'; }
+  envelope.workflow = process.env.GITHUB_RUN_ID ? { repository: github.repository, run: Number(process.env.GITHUB_RUN_ID), attempt: Number(process.env.GITHUB_RUN_ATTEMPT ?? 1), file: 'check.yml' } : null;
+  write(output, envelope);
+  const body = summary(envelope);
+  const workflow = envelope.workflow;
+  requireThat(!workflow || (Number.isSafeInteger(workflow.run) && workflow.run > 0 && Number.isSafeInteger(workflow.attempt) && workflow.attempt > 0), 'workflow receipt needs a valid run and attempt');
+  const receipt = [number, head, input.base, digest(envelope), ...(workflow ? [workflow.run, workflow.attempt] : [])].join(':');
+  await github.call(`check-runs/${check.id}`, 'PATCH', { external_id: receipt, ...(envelope.workflow ? { details_url: `https://github.com/${github.repository}/actions/runs/${envelope.workflow.run}` } : {}), status: 'completed', conclusion: envelope.status === 'ready' ? 'success' : envelope.status === 'superseded' ? 'cancelled' : 'failure', output: { title: `Catalog ${envelope.status}`, summary: body } });
+  if (envelope.status !== 'superseded') await feedback(github, number, body);
+  return envelope;
+}
+
+/** Explicit operator command; never called by an assessment or publication job. */
+export async function configure(github, apply = false, reviewBypassUsers = []) {
+  requireThat(Array.isArray(reviewBypassUsers) && reviewBypassUsers.every((u) => typeof u === 'string' && /^[A-Za-z0-9-]+$/.test(u)), 'invalid internal maintainer usernames');
+  const desired = {
+    required_status_checks: { strict: true, contexts: ['catalog/readiness'] },
+    enforce_admins: true,
+    required_pull_request_reviews: { dismiss_stale_reviews: true, require_code_owner_reviews: true, required_approving_review_count: 1, require_last_push_approval: true, bypass_pull_request_allowances: { users: reviewBypassUsers, teams: [], apps: [] } },
+    restrictions: null, required_conversation_resolution: true,
+    allow_force_pushes: false, allow_deletions: false,
+  };
+  if (apply) {
+    const owners = await github.call('codeowners/errors?ref=main');
+    requireThat(Array.isArray(owners.errors) && owners.errors.length === 0, 'CODEOWNERS is invalid; configure real moderators with repository write access before protecting admission');
+    await github.call('branches/main/protection', 'PUT', desired);
+    await github.call('actions/permissions', 'PUT', { enabled: true, allowed_actions: 'all' });
+  }
+  return { applied: apply, branch: 'main', protection: desired, actionsEnabled: apply };
+}

package/lib/browse.d.mts

@@ -0,0 +1,80 @@
+export type Coverage = {
+  total: number;
+  exercised: number;
+  percent: number;
+  operations: string[];
+  missing: string[];
+};
+export type Replay = { equal: boolean; runs: number; firstSha256: string; secondSha256: string };
+export type Measurements = {
+  scope: string | null;
+  surface: { total: number; served: number; gap: number } | null;
+  operationCoverage: Coverage | null;
+  servedOperations: string[] | null;
+  steps: number | null;
+  answered: number | null;
+  failures: unknown[] | null;
+  replay: Replay | null;
+  conformance: Array<{ id: string; asks: string; failures: unknown[]; note?: string }> | null;
+  browser: {
+    measured: true;
+    target: string;
+    version: string;
+    answered?: number;
+    failures?: unknown[];
+    operationCoverage?: Coverage;
+    replay?: Replay;
+    domCoverage?: unknown | null;
+    clock?: { native: string; nativePrecisionMs: number; javascriptPrecisionMs: number; monotonic: string };
+  } | null;
+  codeCoverage: unknown | null;
+  stateTransitionCoverage: unknown | null;
+  domCoverage: unknown | null;
+  comparison: Record<string, unknown> | null;
+};
+export type Release = {
+  version: string;
+  status: 'live' | 'pending' | 'rejected';
+  integrity?: string;
+  commit?: string;
+  at?: string;
+  by?: string;
+  reason?: string;
+  submission?: string;
+  assessmentCommit?: string;
+  assessedAt?: string;
+};
+export type CatalogRelease = Release & {
+  revoked: { reason: string } | null;
+  selectable: boolean;
+  default: boolean;
+  assessment: {
+    recorded: boolean;
+    available: boolean;
+    evidence: null | { submission: string; admissionCommit?: string; reportPath?: string; reportSha256?: string;
+      url?: string; pullRequest?: number; moderation?: Record<string, unknown> };
+    input: null | { repository: string; pullRequest: number; head: string; base: string; image?: string;
+      workflow?: { repository: string; run: number; attempt: number; file: string };
+      tools: Record<string, string> | null };
+  };
+  measurements: Measurements | null;
+};
+export type CatalogView = {
+  schemaVersion: 1;
+  snapshot: { package: string; version: string; integrity: string | null; sourceCommit: string; digest: string };
+  contribution: { repository: string; registrationUrl: string; pullRequestsUrl: string; guideUrl: string };
+  vendors: Array<{
+    vendor: string;
+    recommendation: string | null;
+    selection: { state: 'selected' | 'unavailable-recommendation' | 'choice-required' | 'unavailable';
+      default: { package: string; version: string; source: string } | null };
+    implementations: Array<{
+      package: string;
+      source: { name: string; repository: string; scope: string; official: boolean; protocol: '3';
+        workflow?: string; url: string; workflowUrl: string };
+      versions: CatalogRelease[];
+    }>;
+  }>;
+};
+/** JSON-only installed-index reader. Does not fetch, import packs, assess, install or verify tarball integrity. */
+export function browse(root: string, options?: { vendor?: string; package?: string; integrity?: string | null }): CatalogView;