@mannyc1/ts-release 0.0.7 → 0.3.0

package/README.md

@@ -1,382 +1,459 @@
-# @mannyc1/ts-release
+# ts-release
 
-Portable artifact and package-manager distribution planning for TypeScript projects.
+Automate multi-artifact releases and safely resume partial publication.
 
-`@mannyc1/ts-release` helps you declare the thing you want to distribute, stage
-platform-specific artifacts when needed, and feed those artifacts into
-target-specific package managers, catalogs, release hosts, and install surfaces.
-Publish operations still stay reviewable and approval-gated, but the product
-center is portable distribution data.
+## Release locally
 
-Use it when you need to answer:
-
-- Which binaries, archives, packages, or generated files make up this release?
-- Which package managers or install channels consume each artifact variant?
-- What target-specific files or commands will be generated?
-- Which operations are only rendering data, and which ones publish externally?
-- What evidence proves what was staged, rendered, validated, or executed?
-
-The root package is the reusable TypeScript library. This repo also contains the
-first-party Bun CLI app in `apps/release-ts` and the bundled GitHub Action in
-`apps/ts-release-action`.
-
-## What It Does
-
-`ts-release` models distribution as data:
-
-```text
-release config
-  -> normalized release identity
-  -> artifact recipes and inventory
-  -> installable artifact variants
-  -> target-specific distribution operations
-  -> generated package-manager files
-  -> explicit execution evidence
-  -> verification or reconciliation
-```
-
-The library currently plans, stages, and validates these distribution surfaces:
-
-| Surface | What ts-release models |
-|---|---|
-| npm | package publish, native dry-run validation, provenance, trusted publishing |
-| GitHub Releases | release creation, asset uploads, REST API verification, draft reconciliation |
-| Homebrew taps | generated formula files, macOS artifact variants, and approved tap pushes |
-| PyPI | already-built distributions and platform CLI wrapper wheels published through Twine |
-| Scoop buckets | generated manifest files, Windows binary shims, and approved bucket pushes |
-| Bun executables | optional binary artifact recipe staging before target planning |
-
-It is not a fake universal package manager and does not hide each ecosystem's
-manifest rules. It can stage declared artifacts through adapters, but it does
-not replace full build pipelines, compilers, signing, or installer toolchains.
-The job is to keep shared artifact inventory and target-specific distribution
-data in one typed plan.
-
-## Quick Start
-
-Inside this repository, the CLI script runs the first-party Bun app:
-
-```sh
-bun run cli init --template bun-cli-github --package @scope/pkg --repo owner/repo --github-actions --write
-bun run cli validate-config --config release.config.json
-bun run cli stage-artifacts --config release.config.json --format text
-bun run cli plan --config release.config.json --format text
-bun run cli render --config release.config.json
-```
-
-The first useful path is artifact-first: write or scaffold a config, stage any
-declared artifact recipes, plan the target distribution work, then render
-package-manager files or release metadata. These commands do not publish
-anything unless an execution command receives explicit approval.
-
-To publish through the full ordered workflow, pass both execution approvals:
-
-```sh
-bun run cli run --config release.config.json --execute --approve-irreversible
-```
-
-`run` renders generated files, validates preflights, executes approved publish
-operations, and verifies remote state. The lower-level commands are available
-when you want a manual pause between phases:
+The normal path is one command from a clean Git checkout:
 
 ```sh
-bun run cli render --config release.config.json --execute
-bun run cli validate --config release.config.json
-bun run cli print --config release.config.json
-bun run cli execute --config release.config.json --execute --approve-irreversible
-bun run cli verify --config release.config.json
-```
-
-## GitHub Actions
-
-The bundled action is the intended CI adapter:
-
-```yaml
-- uses: mannyc2/ts-release-action@v1
-  with:
-    command: plan
-    config: release.config.json
-    format: markdown
-    upload-evidence: true
+ts-release release --config release.config.json
 ```
 
-Supported action commands are `plan`, `validate-config`, `doctor`, `check-auth`,
-`check-ci`, `validate`, `run`, and `reconcile`. Artifact recipe staging remains
-owned by the Bun CLI/runtime because the bundled action runs on Node.
+`release` resolves observed package and Git facts, materializes the exact
+verified commit, runs declared local preparation, commits one complete
+`prepared-release/v2` bundle, observes every configured destination, and
+publishes only after a provider-specific decision authorizes that exact
+subject. The command prints the durable prepared reference and correlated
+report. A blocked or uncertain report is preserved and exits nonzero.
 
-Publishing still needs explicit approval:
+npm authentication is always explicit. A GitHub-hosted npm and GitHub release
+can use this authored configuration:
 
-```yaml
-- uses: mannyc2/ts-release-action@v1
-  with:
-    command: run
-    config: release.config.json
-    execute: "true"
-    approve-irreversible: "true"
-    upload-evidence: true
+```json
+{
+  "project": { "repository": "owner/repo" },
+  "versionFrom": "manifest",
+  "npmPackage": { "path": "." },
+  "publish": {
+    "npm": {
+      "authentication": {
+        "strategy": "trusted-publishing",
+        "attestation": {
+          "provider": "github-actions",
+          "runner": "github-hosted",
+          "repository": "owner/repo",
+          "workflow": "release.yml",
+          "workflowRef": "refs/heads/main",
+          "allowedAction": "npm-publish-direct"
+        }
+      }
+    },
+    "github": {}
+  }
+}
 ```
 
-For npm trusted publishing, configure npmjs for the GitHub repository and
-workflow, grant `id-token: write`, and keep `trustedPublishing` in the npm
-target. Trusted publishing uses OIDC during `npm publish`; it does not use
-`NPM_TOKEN`.
-
-For PyPI trusted publishing, configure a pending or existing PyPI Trusted
-Publisher for the GitHub repository, workflow, and release environment, then
-keep `trustedPublishing` in the PyPI target. Twine uses OIDC during
-`twine upload`; it does not require `TWINE_USERNAME` or `TWINE_PASSWORD` in CI.
-
-## Config
-
-A release config declares identity, artifacts, target policy, and evidence
-location.
+`workflow` and `workflowRef` are local host-admission constraints, not claims
+about fields exposed by npm's trusted-publisher configuration. They must name
+the workflow that actually invokes publication: use `release.yml` with the
+automatic template and `reviewed-release.yml` with the reviewed template. The
+host must observe that exact repository/path/ref on a GitHub-hosted runner
+before it reads either OIDC request value. Public npm metadata reads are always
+anonymous; private or custom-registry authenticated reads are unsupported
+until configured with a distinct read credential.
+
+The resolver fills package name, version, tag, commit, and repository only
+when observed facts agree with authored intent. For a non-OIDC host, use
+`{ "strategy": "token", "credential": "NPM_TOKEN" }` instead. The value of
+that environment variable remains host-owned and never enters configuration,
+prepared bytes, reports, or logs.
+
+Prebuilt Python distributions can be published to the closed `pypi` or
+`testpypi` destination. Each named artifact must be a valid wheel or gzip
+sdist whose filename and embedded metadata agree with the configured project
+and version:
 
 ```json
 {
-  "$schema": "https://mannyc2.github.io/ts-release/schema/release-config.schema.json",
-  "identity": {
-    "_tag": "PackageManifestReleaseIdentitySource",
-    "packagePath": "package.json",
-    "commit": "HEAD",
-    "tagTemplate": "v{version}"
-  },
+  "project": { "name": "fixture", "version": "1.0.0", "tag": "v1.0.0" },
   "artifacts": [
-    {
-      "id": "package",
-      "path": ".",
-      "format": "directory",
-      "consumers": ["npm"]
-    }
+    { "id": "wheel", "path": "dist/fixture-1.0.0-py3-none-any.whl", "format": "file" }
   ],
-  "targets": [
-    {
-      "_tag": "NpmRegistryTarget",
-      "id": "npm",
-      "registry": "https://registry.npmjs.org",
-      "packageName": "@scope/pkg",
-      "packagePath": ".",
-      "trustedPublishing": {
-        "provider": "github-actions",
-        "workflow": "release.yml",
-        "packageExists": true,
-        "verifyPackageExists": true
-      },
-      "access": "public",
-      "provenance": true,
-      "dryRunSupport": "native",
-      "mutability": "immutable",
-      "recovery": "publish-new-version"
+  "publish": {
+    "pypi": {
+      "artifacts": ["wheel"],
+      "repository": "pypi",
+      "authentication": {
+        "strategy": "token",
+        "credential": "PYPI_TOKEN",
+        "scope": "project"
+      }
     }
-  ],
-  "strict": true,
-  "evidenceDirectory": ".release/evidence/{version}"
+  }
 }
 ```
 
-Useful config commands:
+PyPI token upload additionally requires the host to install a shared,
+durable terminal `PublicationClaimStore`; runner-local files and memory do not
+satisfy that contract. The stock CLI and Action deliberately fail closed
+without one. Library hosts can pass it to `makeNodeReleaseLayer`,
+`makeBunReleaseLayer`, or `makeCustomReleaseLayer`. The token is projected as
+PyPI Basic authentication only inside the authorized HTTP sink. PyPI trusted
+publishing is represented as an external, host-owned
+`pypa/gh-action-pypi-publish@release/v1` path; the stock coordinator neither
+exchanges its OIDC token nor claims to recover that external upload.
+
+This repository's selected self-release shape is declared in
+`apps/release-ts/pypi-release.config.json`. It deterministically embeds one
+native executable in each of these `ts-release` wheels:
+
+- `py3-none-manylinux_2_17_x86_64`
+- `py3-none-manylinux_2_17_aarch64`
+- `py3-none-macosx_13_0_x86_64`
+- `py3-none-macosx_13_0_arm64`
+
+`.github/workflows/pypi-release.yml` prepares the exact four-file set in a
+read-only build job, transfers it with GitHub Actions artifact retention, and
+gives only the separate `pypi` environment job `id-token: write`. That job has
+no checkout or arbitrary command step; it downloads the prepared wheels and
+invokes the official PyPA trusted-publishing Action. The PyPI publisher must
+be configured for owner `mannyc2`, repository `ts-release`, workflow
+`pypi-release.yml`, branch `main`, and environment `pypi` before dispatch.
+The macOS wheel tags certify the cross-compiled artifact targets; they do not
+expand the product's Linux-only execution-host claim.
+
+With the canonical GitHub origin or package repository configured, `init` can
+discover the exact owner/repository coordinate and write this explicit shape:
 
 ```sh
-bun run cli schema --out release-config.schema.json
-bun run cli validate-config --config release.config.json --format text
-bun run cli plan --config release.config.json --format summary
-bun run cli explain npm:npm-publish --config release.config.json
-```
-
-Paths are release-workspace relative. Artifact paths can interpolate
-`{version}`, `{name}`, and `{normalizedName}`. Evidence directories can
-interpolate `{version}`.
-
-## Artifact Variants
-
-Artifact recipes can produce installable variants for different operating
-systems and architectures. Bun executable recipes derive variant metadata from
-their compile target, so the release plan can carry facts such as `linux`/`x64`
-or `windows`/`x64` before any package-manager adapter consumes the artifact.
-
-```json
-{
-  "id": "cli-linux-x64",
-  "target": "bun-linux-x64-baseline",
-  "path": "artifacts/pkg-{version}-linux-x64",
-  "consumers": ["github"]
-}
+ts-release init --preset bun-npm-github
 ```
 
-The planned artifact inventory for that output includes an executable artifact
-with a variant like:
+It refuses to guess when no repository coordinate is observable and strictly
+inspects the exact generated configuration before writing it.
+
+## Repository 0.3 self-release
+
+The checked-in `.github/workflows/release.yml` is a manual, fail-closed
+five-mode workflow. `prepare-exact-sha` has read-only repository authority
+and independently commits one GitHub-assets bundle and one npm-tarball bundle
+to the content-addressed Actions store. `certify-npm-oidc` adopts the exact npm
+bundle, proves one trusted-publisher exchange through pinned npm's dry-run, and
+proves unchanged anonymous registry state without upload, provenance, or
+publication. `create-tag` has only the separate
+`github-tag` environment and creates or reobserves the lightweight `v0.3.0`
+tag at the exact candidate; it creates no Release. `publish-npm` accepts only
+the npm bundle under the `npm` environment with `id-token: write`, then
+rereads the public registry to prove exact tarball bytes and the exact GitHub
+SLSA provenance identity. The pinned npm archive's Sigstore 4.1.0 verifier
+requires the exact Fulcio workflow SAN and GitHub OIDC issuer, then binds the
+certificate's workflow/source SHA and run-invocation extensions to the same
+candidate and provenance statement. Its repository-subject extension must be
+the ID-qualified `repo:mannyc2@126291407/ts-release@1271545637:environment:npm`
+identity issued for the protected npm environment; the historical ref-bound
+subject is rejected. Generic signature validity is insufficient.
+Only afterward, `publish-github` accepts the GitHub
+bundle plus the already-published npm bundle under the `github-release`
+environment with `contents: write`. Every boundary
+reauthenticates the checkout against the current public `main` tip immediately
+before it can adopt or mutate anything.
+
+The npm client itself is fetched from the canonical npm 11.11.0 tarball,
+checked against its fixed SHA-512 and SHA-1 registry digests, and freshly
+rematerialized before every boundary. Any nonempty `npm_config_*`, `PREFIX`,
+`DESTDIR`, token variable, project/user npmrc, or default global npmrc stops
+before repository or provider work.
+
+The exact order is preparation, no-upload npm OIDC certification, lightweight
+tag creation, npm publication and report-bound public/provenance verification,
+then GitHub publication. A fresh
+npm mutation must carry provenance for that exact workflow run attempt. If a
+prior run applied the bytes but lost its response, an exact `AlreadyEquivalent`
+retry instead authenticates the earlier canonical publishing run named by the
+public provenance; it never demands impossible same-run provenance from a
+no-op retry. Any uncertain, blocked, malformed, or differently bound Action
+report stops verification. The first
+GitHub publication invocation creates or resumes a private draft and uploads
+only missing exact assets. For a desired public Release that staging result is
+deliberately `uncertain`, not success, and the Release remains nonpublic. A
+fresh invocation with the same candidate and both exact `prepared:gha:`
+references must fully reread draft metadata and every paginated asset, download
+and hash any asset whose API digest is absent, and only then perform a
+PATCH-only public transition. Extra, duplicate, missing, or different assets
+stop that transition. On 2026-09-01, repository environments `github-tag`
+(ID `20986778371`), `npm` (ID `20985327992`), and `github-release`
+(ID `20985328229`) were observed with reviewer `mannyc2`, self-review allowed,
+admin bypass disabled, a custom deployment policy selecting exactly `main`,
+and no environment secrets or variables. Re-query those mutable facts before
+every dispatch. Repository Release immutability was also observed enabled on
+2026-09-01; re-query it before GitHub staging or promotion. The repository OIDC
+policy was observed on that date with the immutable ID-qualified subject
+`repo:mannyc2@126291407/ts-release@1271545637:environment:npm`; re-query it
+before certification or publication. That GitHub-side policy does not prove an
+npm-side trusted-publisher record. The exact npm trusted-publisher subject
+remains a separate prerequisite and is not inferred from an environment.
+
+## Automatic GitHub Actions template
+
+The reusable automatic template is one job and one Action invocation. Copy the exact
+[automatic workflow template](templates/github-actions/release.yml). It is
+manual-only and requires `candidate_sha` to equal the current commit on
+`refs/heads/main` before the job can reach checkout. Its
+mutation job grants `contents: write` for the same-repository tag, release, and
+assets, `id-token: write` for npm trusted publishing, and `actions: read` for
+prepared-artifact recovery. It installs the publisher boundary explicitly,
+uses the job-scoped `GITHUB_TOKEN`, and uploads the redacted report as a
+recovery artifact.
 
-```json
-{
-  "os": "linux",
-  "arch": "x64",
-  "libc": "glibc",
-  "targetTriple": "bun-linux-x64-baseline"
-}
-```
-
-Direct artifact declarations can also include `variant` when an artifact was
-built outside `ts-release`. Homebrew formulas can consume macOS `darwin` x64
-and arm64 variants from one target, and Scoop manifests can derive a stable shim
-from a Windows executable variant. Future package-manager adapters should follow
-that pattern instead of guessing platform support from filenames.
-
-## Diagnostics
-
-Static diagnostics help catch missing auth and unsafe workflow setup before an
-approved run:
-
-```sh
-bun run cli doctor --config release.config.json --format text
-bun run cli check-auth --config release.config.json --target npm --format text
-bun run cli check-ci --config release.config.json --workflow .github/workflows/release.yml --format markdown
+```yaml
+- id: release
+  uses: mannyc2/ts-release/apps/ts-release-action@v0.3.0
+  env:
+    GITHUB_TOKEN: ${{ github.token }}
+  with:
+    command: ${{ inputs.prepared_ref == '' && 'release' || 'publish' }}
+    config: ${{ inputs.prepared_ref == '' && 'release.config.json' || '' }}
+    prepared: ${{ inputs.prepared_ref }}
 ```
 
-Diagnostics report confidence levels instead of pretending local checks can
-prove provider-side setup. For example, npm trusted publishing can only be fully
-confirmed inside the configured GitHub Actions environment.
-
-## Programmatic API
-
-Install the library and provide platform services at your application boundary:
+Leave `prepared_ref` empty for a fresh release. To resume after durable
+preparation, dispatch the same candidate with the exact emitted
+`prepared:gha:` reference; the job selects `publish`, loads and verifies the
+original bundle, and does not rebuild.
+
+`v0.3.0` is the immutable monorepo-subpath coordinate intended for this
+candidate. Packaging and release certification must stop unless that tag is
+created from the exact certified result commit before consumers can see a
+README that names it. A floating Action branch is never an alternative.
+
+## Optional environment-gated publication
+
+When a host policy requires a protected environment, use the
+[two-job workflow template](templates/github-actions/reviewed-release.yml).
+Copy its paired
+[reviewed configuration](templates/npm-github/reviewed-release.config.json)
+to the repository root with the same filename; the workflow loads that exact
+file.
+Its prepare job has read-only repository authority and no OIDC permission. It
+uploads one complete prepared bundle and passes only its content-addressed
+hosted reference. The environment-gated publish job installs the publisher
+toolchain, receives mutation permissions, reloads and verifies the bundle, and
+then observes destinations before any write. The environment gate remains a workflow
+fact; it is not release-engine identity or data.
+
+The reviewed configuration attests `workflow: "reviewed-release.yml"` and
+`workflowRef: "refs/heads/main"`. Keep the workflow filename and dispatch it
+from that ref with `candidate_sha` equal to the current commit, or deliberately
+update both constraints. Reusing an automatic configuration that attests
+`release.yml` fails before OIDC acquisition. Recover a failed reviewed
+publication by rerunning the publish job in the same workflow run, not by
+preparing again.
+
+## Prepare without publication
+
+Use the split local path for build-only work or when bytes must cross an
+explicit host boundary:
 
 ```sh
-bun add @mannyc1/ts-release effect@beta @effect/platform-bun@beta
+prepared_ref="$(ts-release prepare --config release.config.json)"
+ts-release inspect "$prepared_ref"
 ```
 
-High-level workflows are available from the opt-in workflow facade:
+The value is a path-free `prepared:local:sha256-…` reference resolved against
+the selected content-addressed store. `--store` selects another local store;
+the reference itself never embeds a filesystem path. Publication accepts only
+a complete reference and never rebuilds from source as a fallback.
 
-```ts
-import * as BunHttpClient from "@effect/platform-bun/BunHttpClient"
-import * as BunServices from "@effect/platform-bun/BunServices"
-import * as Effect from "effect/Effect"
-import * as Layer from "effect/Layer"
-import { Distribution, Live } from "@mannyc1/ts-release/workflows"
-
-const root = "/path/to/release-workspace"
-const RuntimeLayer = Live.makeLayer({ root }).pipe(
-  Layer.provideMerge(BunServices.layer),
-  Layer.provideMerge(BunHttpClient.layer)
-)
-
-const textPlan = await Effect.runPromise(
-  Distribution.renderPlan({ root, configPath: "release.config.json", format: "text" }).pipe(
-    Effect.provide(RuntimeLayer)
-  )
-)
-
-const evidence = await Effect.runPromise(
-  Distribution.run({
-    root,
-    configPath: "release.config.json",
-    execute: true,
-    approveIrreversible: true
-  }).pipe(Effect.provide(RuntimeLayer))
-)
-
-console.log(textPlan)
-console.log(evidence.schemaVersion)
-```
-
-Use `@mannyc1/ts-release/workflows` for the curated `Distribution`, `Config`,
-`Init`, `Diagnostics`, `Evidence`, and `Live` namespaces. The `Distribution`
-namespace is the artifact-first facade; `Config` keeps the lower-level
-config-file workflow names. Use exact subpaths such as
-`@mannyc1/ts-release/workflows/distribution` or lower-level `domain/`,
-`planner/`, `targets/`, and `host/` modules when you need tighter control or
-maximum tree-shaking.
-
-The package root export is intentionally empty. Public API is the explicit
-subpath list in `package.json`.
-
-## Templates And Examples
+Local extension work uses two primitives. `CommandCheck` is a pass/fail gate.
+`CommandArtifact` generates or transforms declared regular-file bytes. Data
+flow uses declared input and output IDs. Generic preparation children receive
+no authored host environment values, and the runner may retain only `PATH` as
+argv execution plumbing. Trusted commands are not a sandbox or a generic
+remote-effect mechanism.
 
-Config templates live in `templates/`:
+## Observe and recover
 
-- `npm-only`
-- `npm-github`
-- `bun-cli-github`
-- `multi-target-homebrew`
-- `multi-target-scoop`
-
-Runnable fixtures live in `examples/` and are checked through the same workflow
-path as user configs.
+Observation is read-only:
 
 ```sh
-bun run build
-cd examples/multi-target
-bun ../../apps/release-ts/src/cli/main.ts plan --config release.config.json --format text
+ts-release observe "$prepared_ref"
 ```
 
-Templates with `artifactRecipes` need an explicit staging step before target
-planning expects the generated files to exist:
+To resume a partial or response-lost release, publish the same reference:
 
 ```sh
-bun run cli stage-artifacts --config release.config.json --format text
+ts-release publish "$prepared_ref"
 ```
 
-## Evidence
+Every attempt verifies the manifest and blobs, then reobserves every subject.
+Equivalent subjects are skipped. Conflict and pre-mutation uncertainty stop
+without mutation. A post-dispatch unknown outcome stays uncertain until a new
+exact observation converges. Publication is not an atomic transaction, so a
+release may partially succeed and there is no universal rollback.
 
-Validation, rendering, execution, reconciliation, and verification write JSON
-evidence bundles. Primitive commands write named files such as
-`validation.json`; the full `run` workflow writes `evidence.json`.
+## Provider-specific correction
 
-```json
-{
-  "schemaVersion": "release-evidence/v1",
-  "releaseName": "release",
-  "releaseVersion": "0.1.0",
-  "records": [
-    {
-      "id": "npm:npm-pack-dry-run:command",
-      "operationId": "npm:npm-pack-dry-run",
-      "phase": "validation",
-      "targetId": "npm",
-      "risk": "read-only",
-      "status": "passed",
-      "severity": "info",
-      "message": "npm pack dry run passed.",
-      "startedAt": "2026-01-01T00:00:00.000Z",
-      "endedAt": "2026-01-01T00:00:00.100Z",
-      "durationMillis": 100,
-      "command": "npm pack --dry-run --json",
-      "exitCode": 0
-    }
-  ]
-}
-```
-
-Failed commands preserve partial evidence when possible. Non-strict mode records
-missing validators as visible skipped evidence instead of silently dropping them.
-
-## Reconciliation
-
-`reconcile` is a narrow repair path for GitHub Releases. It reads the release by
-tag, blocks on mismatched metadata or assets, skips an already matching
-published release, and can publish a matching draft with `--execute`.
-
-It does not replay immutable registry publishes:
+Correction is deliberately separate from ordinary publication:
 
 ```sh
-bun run cli reconcile --config release.config.json --execute
+ts-release correct "$prepared_ref" correction.json
 ```
 
-## Repository Checks
+The command binds authored intent to the exact prepared provider subject. npm
+and GitHub Release corrections remain canonical external operator proposals.
+Catalog Git installs one conditional `forward-catalog-state` correction: it
+requires a SemVer-newer replacement and changes both the consumer formula or
+manifest and its managed-state record against the exact observed branch
+generation. Deletion, arbitrary inverse operations, and announcements are not
+release destinations.
+
+## Capability and platform boundary
+
+A source checkout or accepted field is not support evidence. The generated
+capability inventory must join each supported row to its strict decoder,
+default-layer entrypoint, exact observation semantics, and vertical test, and
+the release-candidate matrix must exercise every claimed execution host.
+
+| Axis | Kernel candidate boundary |
+| --- | --- |
+| Local preparation | Bun compilation, prebuilt imports, command checks/artifacts, archives, and checksums are retained; final support requires the generated capability and clean-candidate gates to agree. |
+| Remote publication | npm, prebuilt PyPI distributions, GitHub Releases, and typed Homebrew/Scoop catalog Git delivery are installed. npm uses explicit trusted-publishing or token authentication; PyPI token writes require a host-supplied shared terminal claim store, and its trusted-publishing strategy is external-host-owned. |
+| Correction | npm and GitHub authored proposals are exact-bound; PyPI yanking is observation-only; catalog Git installs exact paired SemVer-forward correction. |
+| Execution hosts | Linux is the only installed execution host. The checked-in Action is a native Node 24 launcher around a workflow-installed, pinned Bun runtime. macOS and Windows are not ts-release execution hosts. |
+| Artifact targets | The Bun builder advertises Linux and macOS x64/arm64 targets. macOS binaries are cross-compiled artifacts, not host-execution evidence. The self-release does not distribute a Windows ts-release binary. |
+| Native tools | Linux preparation requires an external Bun executable and `libseccomp.so.2`; network-denied commands record both identities. WSL, when used, is Linux. A standalone CLI binary is not a self-contained replacement for these tools. |
+
+Installed Node consumers must satisfy the package engine
+`^22.22.2 || ^24.15.0 || >=26.0.0`; Bun consumers require Bun 1.3.14 or newer.
+The checked-in Action uses GitHub's native Node 24 Action handler so the runner
+can inject its Actions-artifact transport credentials. Its tiny checked-in
+launcher passes no credentials to the Bun 1.3.14 runtime preloader, then runs
+the checked-in `dist/index.js` through the workflow-installed Bun runtime.
+Preparation stays in Bun, while every Actions-artifact upload or download is
+delegated to the checked-in Node 24 bridge so the official artifact client runs
+on its native stream implementation. The Action does not change the Node
+engine of the installed library or CLI package.
+
+The current source tree is not a release certificate. A published support
+claim exists only after the clean-candidate evidence records all required
+gates green; skipped live facts remain `UNVERIFIED`.
+
+## Extension jobs and exclusions
+
+The kernel translates extension requests to the owner that can enforce them:
+
+| User job | Owner |
+| --- | --- |
+| Tests, policy checks, generated notes, and agent bundles | `CommandCheck` or declared `CommandArtifact` bytes |
+| npm, prebuilt PyPI, GitHub Release, and catalog Git remote verification/publication | Installed provider modules; PyPI token mutation also requires the shared terminal claim boundary |
+| Environment protection or human authorization | External workflow host |
+| Downstream announcements | External workflow step after a complete report |
+
+Homebrew and Scoop rendering/delivery use typed renderers and an exact paired
+Git Data subject; arbitrary whole-file catalog templating remains excluded.
+Generic wrapper-wheel generation remains excluded from the prebuilt PyPI
+capability. The repository-specific four-wheel `ts-release` self-release is an
+explicit product decision and is prepared by its dedicated workflow. PyPI
+support is contract-tested but has not been live-write-dogfooded in this wave.
+Custom library applications may compose full provider subjects through the
+[`provider-sdk`](https://github.com/mannyc2/ts-release/blob/main/docs/native-extensions.md)
+subpath. The stock CLI and Action
+do not discover packages or treat generic hooks as remote publishers.
+
+## Library API
+
+The Promise API uses the same lifecycle as the CLI and Action:
 
-Use Bun for package management, scripts, and tests:
-
-```sh
-bun run check:release
-bun run check:examples
-bun run check:readme
+```ts
+import {
+  defineRelease,
+  encodeCompletePreparedReleaseRef,
+  makeReleaseApi
+} from "@mannyc1/ts-release"
+import { NodeReleaseLayer } from "@mannyc1/ts-release/node"
+
+const config = defineRelease({
+  project: { repository: "owner/repo" },
+  versionFrom: "manifest" as const,
+  npmPackage: { path: "." },
+  publish: {
+    npm: {
+      authentication: {
+        strategy: "trusted-publishing" as const,
+        attestation: {
+          provider: "github-actions" as const,
+          runner: "github-hosted" as const,
+          repository: "owner/repo",
+          workflow: "release.yml",
+          workflowRef: "refs/heads/main",
+          allowedAction: "npm-publish-direct" as const
+        }
+      }
+    },
+    github: {}
+  }
+})
+
+const api = makeReleaseApi(NodeReleaseLayer)
+try {
+  const result = await api.release({ config, workspace: process.cwd() })
+  console.log(encodeCompletePreparedReleaseRef(result.prepared))
+  console.log(result.report.status)
+} finally {
+  await api.dispose()
+}
 ```
 
-Real-tool integration checks are opt-in:
+The public operations are `inspect`, `prepare`, `observe`, `publish`,
+`release`, and `correct`. Public inputs contain neither credential values nor
+prepared paths. The derived graph is ephemeral; the verified prepared
+manifest and blobs are the durable cross-process boundary.
+
+The separate `@mannyc1/ts-release/operation-journal` subpath exposes the
+provider-neutral canonical envelope and one S3 CAS protocol for durable
+external-operation continuation. It stores consumer-owned opaque bytes and
+never decodes provider fields. Workflow repository/run coordinates are derived
+from the re-observed GitHub OIDC session rather than accepted from an append
+request. A host can supply one already-authenticated, exact-policy S3 boundary
+as the credential-agnostic qualification seam. The separate
+`@mannyc1/ts-release/operation-journal/aws` subpath is the only operational
+backend implementation: it accepts one sealed activation contract, rejects
+ambient AWS variables and shared files, requests GitHub OIDC directly, uses
+only the returned short-lived role session, and parses live STS, IAM, bucket,
+Object Lock, ownership, public-access, and policy responses. It accepts no
+profile, credential, endpoint, alternate bucket, or fallback-store input.
+Operation identities are bounded to 65,536 bytes, payloads to 1,048,576 bytes,
+and retained objects to 1,500,000 bytes before hashing or allocation. The AWS
+trust and activation contract require the
+reusable workflow to be called as `uses: .../operational-journal.yml@<40-hex>`;
+a branch or tag ref is not authority, and the observed `job_workflow_ref` SHA
+must equal `job_workflow_sha`. The frozen subject selects exactly one GitHub
+environment-subject form: name-bound `repo:owner/repository:environment:name`
+or immutable-ID-bound
+`repo:owner@ownerId/repository@repositoryId:environment:name`; observed IDs
+must reconstruct the latter exactly, and there is no runtime fallback between
+forms. The same STS-admitted token must also report `workflow_dispatch`, a
+branch ref, a public repository, and a GitHub-hosted runner. Every OIDC fetch,
+AWS SDK send, and retained-object stream has a fixed 10,000 ms wall-clock
+deadline in addition to single-attempt retry policy.
+
+The checked-in `operational-journal.yml` is intentionally inert: it has no
+OIDC permission, AWS coordinate, credential input, checkout, or executable
+adapter and always stops. Activating it requires the separately provisioned
+bucket/role, a released adapter version, a reviewed opaque-byte caller/callee
+transport, and qualification of the exact retained object protocol. The
+serialized SDK requests, structural boundary, and fake tests are not live AWS
+or workflow qualification.
+An activated reusable job must install the package-supported Node 22.22.2
+runtime independently of the caller and launch the adapter through an
+`env -i` allowlist containing only the exact Actions OIDC request coordinates
+and non-secret activation inputs. The caller's Node 24.14.1 runtime is below a
+transitive dependency's admitted Node 24 floor and must not run this package.
+
+## Agent bundles and development
+
+The single tracked agent source owner is `apps/ts-release-agents`. Generated
+Codex and Claude layouts are ignored build output and are captured by the
+self-release as declared `CommandArtifact` outputs. No root marketplace tree
+is a second canonical owner.
 
 ```sh
-bun run test:integration:tools
-RELEASE_INTEGRATION_GITHUB=1 bun run test:integration:tools
+bun install --frozen-lockfile
+bun run check:portable
+bun test
 ```
 
-See `ARCHITECTURE.md` for module boundaries, `SPEC.md` for the design contract,
-`templates/README.md` for starter configs, and `examples/README.md` for runnable
-fixtures.
+The durable model is documented in [ARCHITECTURE.md](ARCHITECTURE.md), and the
+precise public contract is in [SPEC.md](SPEC.md). Both files are included with the npm
+package; this README does not rely on an unpackaged relative document.