kylon-cli 0.6.0-next.869 → 0.7.0-next.873

package/README.md

@@ -432,6 +432,114 @@ trigger, not a required extra step after a production deploy. Do not run
 Development installs `@next` and production installs `@latest`, so each
 environment tracks its own release train.
 
+#### Auto-update policy: dev is automatic, production is manual
+
+The two `cli_auto_update` keys are maintained by deliberately different
+mechanisms.
+
+**`cli_auto_update/next` (dev) is reconciled automatically.** After a `develop`
+prerelease is published, the `sync-dev-auto-update` job in
+`.github/workflows/cli-publish.yml` sets the dev entry to the exact version it
+just released, with `enabled: true` and `rolloutPercentage: 100`. A staged
+rollout on dev would serve no purpose: the prerelease it points at is the only
+build `@next` resolves to, so anyone tracking `next` is getting it regardless.
+
+The job verifies that `kylon-cli@next` actually resolves to the published
+version before writing (retrying for registry read lag), and writes through
+`upsertRuntimeConfigEntry`, so the same schema validation and
+`runtime_config_entry_revisions` audit row apply as for an admin edit. The
+revision's change reason records the published version, commit and workflow run.
+
+The write is fenced with the entry version the job read, so it is a
+compare-and-swap rather than a blind overwrite. That matters because
+`cli-publish.yml` deliberately gives every run its own concurrency group: two
+`develop` prereleases can be in flight at once and both reach this reconciler.
+The rule is **latest wins** — the highest `X.Y.Z-next.N` the job can observe,
+whether on the dist-tag or already stored in the entry, owns the target. An
+older run that sees a newer one records a `superseded` no-op and succeeds; if
+its fenced write loses the race instead, it re-reads both the dist-tag and the
+row and re-decides against the state that won. An older release can therefore
+never overwrite a newer one, and the entry never flaps between two concurrent
+runs.
+
+**The dist-tag is part of the same convergence, not an input to trust.**
+`npm publish --tag next` moves the tag by wall clock, not by version, so two
+overlapping runs that finish in reverse order leave the registry serving the
+*older* build: run 811 publishes, then run 810 publishes and takes `@next`.
+That is user-visible — `automatic-cli-update.ts` refuses to upgrade a machine
+whose configured target differs from the dist-tag, logging `release_mismatch` —
+so the two surfaces have to agree on one canonical winner: the newest
+`X.Y.Z-next.N` any run can observe on its own release, on the tag, or in the
+row.
+
+Two mechanisms keep them agreeing:
+
+- **The publish never moves `@next` backwards.** Immediately before publishing,
+  the run re-reads the dist-tag; if it already serves a strictly newer
+  prerelease, this run is already superseded and publishes under the
+  non-promoting `next-superseded` tag instead. The version is still published
+  and still installable by exact version — it just does not take the channel
+  head. A lookup that cannot be answered stops the run *before* the
+  irreversible step rather than publishing blind.
+- **The sync repairs what is left.** A check-then-publish window remains, so if
+  the sync job finds `@next` behind the canonical winner it moves the tag
+  first — under a re-read fence, so an older run can never pull it back — and
+  only then writes the row. The row is never pointed at a version the dist-tag
+  does not serve, because that state upgrades nobody.
+
+  Moving a dist-tag needs a credential: npm's OIDC trusted publishing
+  authenticates `npm publish` and nothing else ([npm/cli#8547](https://github.com/npm/cli/issues/8547)).
+  The sync job reads an optional `NPM_DIST_TAG_TOKEN` from its `dev`
+  environment; when it is absent, the run fails with an `::error::` naming the
+  exact `npm dist-tag add kylon-cli@<winner> next` to run, instead of reporting
+  a convergence that did not happen.
+
+Propagation is not part of the write's success condition. Committing the entry
+also bumps a per-namespace revision counter and publishes a cache-invalidation
+message on Redis, but no runtime reader polls that counter: services drop their
+in-process runtime-config snapshot when the pub/sub message arrives, and
+otherwise when the snapshot ages past its five-minute TTL. The publish is
+bounded inside `invalidateRuntimeConfig`, so an unreachable Redis (the CI job
+tunnels Postgres only) costs at most that five minutes of staleness and cannot
+stall or fail an already-committed, already-audited write.
+
+**`cli_auto_update/latest` (production) is never touched by automation.** The
+stable target version and its rollout percentage are set by a human in the
+admin runtime config, and ramping 0 → 100% is an explicit blast-radius
+decision. Publishing a stable build to `@latest` does not enrol any computer in
+updating to it; that remains a separate, deliberate step.
+
+Two consequences worth knowing:
+
+- **A dedup-skipped prerelease changes nothing.** When content dedup decides the
+  bundle is identical to what `@next` already has, no version is published and
+  the dev policy is left exactly as it was — the existing target is still the
+  build `@next` serves. The sync never fabricates a version for a release that
+  did not happen.
+- **A failed sync fails the run, loudly, and re-running repairs it.** The npm
+  publish is irreversible, so the sync cannot be retried by re-publishing. If
+  the config write fails (or `@next` does not converge on the published
+  version), the workflow fails with an `::error::` naming the manual fix — a red
+  run, never a silent partial release.
+
+  "Re-run all jobs" is the supported repair. A re-run keeps the same run number
+  and therefore mints the same `X.Y.Z-next.<run>` version, which is already on
+  npm; the publish job detects exactly that case and marks the run
+  `reconcile_only`, so it publishes nothing but still runs the sync job. The
+  reconciliation is idempotent and reads the live dist-tag, so it either repairs
+  the stale entry, finds it already correct, or finds that a newer prerelease
+  has superseded this one and leaves the newer target alone. That is distinct
+  from an ordinary content-dedup skip, which publishes nothing and reconciles
+  nothing. If the re-run also fails, set `cli_auto_update/next` in the dev admin
+  runtime config by hand.
+
+  The classifier that tells those two skips apart is
+  `scripts/ci/cli-prerelease-npm.sh`, and every registry lookup in it retries
+  and fails closed. A transient `npm view` error is not evidence that a version
+  is unpublished; treating it as such is what would let a failed reconciliation
+  hide behind a green re-run. The dist-tag's own version is used as a second,
+  independent confirmation of the same fact.
+
 ## Usage
 
 ### Sign in for workspace commands

package/dist/kylon-bundle.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.0-next.869",
-  "fingerprint": "afb57efce175ef04f8fa6a2c4b3c7bd4066070f5c64fda3dad261167f7db7556",
-  "source_commit": "f3c83f68293b19a61bac854d9ff40421231a5b25"
+  "version": "0.7.0-next.873",
+  "fingerprint": "1e155dfa2a8b6676fcf6d7fe7d69cd4cd0ff6b725e9af48383f0ae4e47151b83",
+  "source_commit": "b0c31dbf9e8413ecb155cb8693e1170eb6cf99d5"
 }