diff --git a/AGENTS.md b/AGENTS.md index 64d8ce1..039b8aa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,7 +38,7 @@ The package should be reusable across multiple businesses. Avoid app-specific as ## Current Tracking -As of `2026-06-10`, release-authority, artifact-truth, and runner-contract +As of `2026-06-11`, release-authority, artifact-truth, and runner-contract convergence have largely landed. The active structural work is docs/toolchain truth normalization and the adopter capability contract. @@ -56,8 +56,8 @@ Closed but still relevant context: - `TIN-103` closed the release-authority ambiguity for `Jesssullivan/scheduling-kit` - `TIN-104` was canceled as a duplicate during that convergence work - `TIN-165` is done: the tinyland bazel-registry is generated from standalone - package truth and currently carries scheduling-kit `0.8.0` and - scheduling-bridge `0.5.11`; the registry line is in `.bazelrc` + package truth and currently carries scheduling-kit `0.9.0+` and + scheduling-bridge `0.5.11+`; the registry line is in `.bazelrc` - `TIN-677` is done: HomegrownAdapter takes injected schemas from `@tummycrypt/tinyland-business-pg`, with `tinyland-auth-pg` kept only as an optional legacy fallback @@ -66,8 +66,12 @@ Current operational truth: - local development should default to `jesssullivan/main` - that branch is the current functional release line -- current published package truth is `@tummycrypt/scheduling-kit` `0.8.0` - on GitHub Releases, GitHub Packages, and the active tinyland Bazel registry +- current released version is `0.9.0`: git tag plus GitHub Release, GitHub + Packages `@jesssullivan/scheduling-kit`, and the active tinyland Bazel + registry (`0.9.0+`) +- npmjs `@tummycrypt/scheduling-kit` is retired for new versions and frozen at + `0.8.0`; `npm_publish_mode: disabled` is permanent policy, not a temporary + outage - HomegrownAdapter does not require `tinyland-auth-pg`; schemas are injected explicitly (canonically from `@tummycrypt/tinyland-business-pg`) and any auth-pg fallback stays optional @@ -162,12 +166,19 @@ bar. ### Publishing -Current publish flows target: +Delivery doctrine: -- npmjs as `@tummycrypt/scheduling-kit` -- GitHub Packages as `@jesssullivan/scheduling-kit` +- the Bzlmod module graph through `tinyland-inc/bazel-registry` is the SSOT + delivery mechanism +- GitHub Packages `@jesssullivan/scheduling-kit` is the derived + out-of-ecosystem package, built from the Bazel `//:pkg` artifact + (`./bazel-bin/pkg`) +- npmjs `@tummycrypt/scheduling-kit` is retired for new versions and frozen at + `0.8.0`; `npm_publish_mode: disabled` is permanent policy, not a temporary + outage -That GitHub Packages rename is operationally real. Do not break it +That GitHub Packages naming split (npm-style identity `@tummycrypt`, GitHub +Packages scope `@jesssullivan`) is operationally real. Do not break it accidentally when editing the publish flow. Release/publish changes should be made against the functional release line diff --git a/README.md b/README.md index ce0814f..c02a1ec 100644 --- a/README.md +++ b/README.md @@ -28,10 +28,29 @@ clean shell. ## Installation +The Bazel module graph is the canonical delivery mechanism. Depend on the +module through the tinyland Bazel registry: + +```starlark +bazel_dep(name = "tummycrypt_scheduling_kit", version = "0.9.0") +``` + +with the registry line (already in this repo's `.bazelrc`): + +```text +common --registry=https://raw.githubusercontent.com/tinyland-inc/bazel-registry/main +``` + +npm-ecosystem consumers outside the Bazel module graph install the derived +GitHub Packages artifact: + ```bash -pnpm add @tummycrypt/scheduling-kit +pnpm add @jesssullivan/scheduling-kit # registry: https://npm.pkg.github.com ``` +npmjs (`@tummycrypt/scheduling-kit`) is retired for new versions and frozen at +`0.8.0`. + ## Development Environment ```bash @@ -86,19 +105,25 @@ Current reality: - the functional release line is `Jesssullivan/scheduling-kit` - `tinyland-inc/scheduling-kit` is now a downstream mirror and validation surface, not a second publish authority -- the active tinyland Bazel registry carries `scheduling-kit` `0.8.0` (and - `scheduling-bridge` `0.5.11`); the registry line is already in `.bazelrc` +- the active tinyland Bazel registry carries `scheduling-kit` `0.9.0+` (and + `scheduling-bridge` `0.5.11+`); the registry line is already in `.bazelrc` Treat `Jesssullivan/main` as the release authority for package publication and metadata changes. Do not assume both `main` branches are equivalent. -Longer term, the intended publish shape is: +The delivery doctrine is: 1. release metadata declared once 2. Bazel defines and builds the publishable artifact 3. GitHub Actions validates that artifact on the repo-owned package runner -4. GitHub Packages is the package publish authority while npmjs publishing is disabled -5. downstream apps consume the published package only +4. the Bzlmod module graph via `tinyland-inc/bazel-registry` is the SSOT + delivery mechanism +5. GitHub Packages carries the derived `@jesssullivan/scheduling-kit` package, + built from the Bazel `//:pkg` output, for consumers outside the Bazel + module graph +6. npmjs (`@tummycrypt/scheduling-kit`) is retired for new versions and frozen + at `0.8.0`; `npm_publish_mode: disabled` is permanent policy +7. downstream apps consume the published package only ## Runner Authority diff --git a/docs/build-and-release.md b/docs/build-and-release.md index 4da8124..e221f8d 100644 --- a/docs/build-and-release.md +++ b/docs/build-and-release.md @@ -35,8 +35,23 @@ graph, and the shared `js-bazel-package` workflow publishes from `./bazel-bin/pkg`. The active workflow contract uses repo-owned runner registration with Tinyland -capability labels. npmjs publication is disabled; the publish path validates and -publishes the Bazel artifact through GitHub Packages. +capability labels. npmjs publication is permanently disabled; the publish path +validates the Bazel artifact and publishes the derived GitHub Packages package. +See the delivery doctrine below. + +## Delivery doctrine + +Package delivery follows one source of truth: + +1. The Bzlmod module graph is the canonical (SSOT) delivery mechanism. + Consumers depend on `tummycrypt_scheduling_kit` through the + `tinyland-inc/bazel-registry` registry line already present in `.bazelrc`. +2. GitHub Packages (`@jesssullivan/scheduling-kit`) is a derived package: the + out-of-ecosystem alternative route for npm-style consumers, built from the + same Bazel `//:pkg` output (`./bazel-bin/pkg`) that the module graph models. +3. npmjs (`@tummycrypt/scheduling-kit`) is retired for first-party delivery. + It is frozen at `0.8.0`, and `npm_publish_mode: disabled` in the CI and + publish workflows is permanent policy, not a temporary outage. ## Bazel Cache Contract @@ -81,12 +96,15 @@ Version drift across those files is a bug. Before cutting a package release, verify these surfaces together: -- npm package: `@tummycrypt/scheduling-kit` -- npmjs publish mode: `disabled` -- GitHub Packages package: `@jesssullivan/scheduling-kit` +- Bazel registry entry in `tinyland-inc/bazel-registry` for the new version + (the SSOT delivery surface) +- GitHub Packages package: `@jesssullivan/scheduling-kit`, derived from the + Bazel `//:pkg` artifact - tag and GitHub release for the package version - Bazel package artifact from `./bazel-bin/pkg` - consumer dependency range in bridge and app repos +- npmjs stays frozen: `@tummycrypt/scheduling-kit` is retired at `0.8.0`, and + `npm_publish_mode: disabled` must remain in both workflows Historical releases before this checklist may have npm versions without matching GitHub Releases. Document or backfill those explicitly instead of treating the