kylon-cli 0.7.0 → 0.7.1-next.886

package/README.md

@@ -432,6 +432,154 @@ 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.
+
+**Any CLI publish workflow run on `develop` converges the dev policy with the
+real `@next`** — not only a run that published something. The job runs in one
+of three modes, reported by the classifier as `sync_reason`:
+
+| `sync_reason` | What happened | What the sync does |
+| --- | --- | --- |
+| `published` | this run released a prerelease | point the entry at it |
+| `this_run_already_published` | a full re-run whose own version is already on npm | re-run the outstanding reconciliation |
+| `ordinary_dedup_reconcile_current_next` | the bundle is identical to what `@next` already carries, so nothing was published | reconcile the entry toward the version `@next` already serves |
+
+The third mode is the one to understand: **when there is no new bundle, the run
+only bootstraps or repairs the config.** It publishes nothing, mints no
+version, never touches a dist-tag, and writes no revision at all when the entry
+is already correct. The version it converges on is never hypothetical — it is
+read from the registry, must be an exact `X.Y.Z-next.N`, and is the build every
+`@next` install is already getting.
+
+That mode exists because the previous behaviour had a bootstrap gap. The merge
+that shipped this sync (#6692) changed no CLI bundle, so content dedup skipped,
+the sync job's condition rejected an ordinary skip, and the dev
+`cli_auto_update/next` entry — which did not exist yet — was never created. An
+identical bundle is a reason not to publish; it is not a reason to leave the
+dev policy unreconciled.
+
+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 publishes nothing, but still reconciles.** When
+  content dedup decides the bundle is identical to what `@next` already has, no
+  version is published — and the sync job runs anyway, against the version
+  `@next` currently serves. Usually that is a no-op that writes no revision;
+  when the entry is missing or stale it is repaired on the spot. The sync never
+  fabricates a version for a release that did not happen: the only version it
+  can write is one it read off the registry.
+
+  A run with no release of its own also never moves the dist-tag. If it finds
+  the row pointing at something newer than `@next`, that winner belongs to the
+  run that published it, and that run converges both surfaces itself — so this
+  one records a `superseded` no-op instead of racing it. For the same reason a
+  registry it cannot read — or one serving a version this workflow does not
+  own — is a `::warning::` and a green run here, not a red one, and that holds
+  for **every** registry read the job takes: the read that picks the target and
+  the read the reconciliation itself takes just before it writes. Nothing was
+  published, nothing was written, nothing is at risk, and the next push
+  reconciles again. The downgrade stops there: a schema rejection, a lost CAS
+  fence or a database error still fails the job on this trigger too.
+- **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 stays distinct
+  from an ordinary content-dedup skip: both start a sync, but only the re-run
+  has a release of its own to reconcile, so only it may claim one. 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` — it emits `sync_reason`, and keeps
+  `reconcile_only` reserved for the re-run case — 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.7.0",
-  "fingerprint": "a89459d3e6ec31c993da5374e6879f1bd9eac803a140fd1ee5cb9955b59f021a",
-  "source_commit": "be898b7b82e0948f61cdc5076d4464779cc63101"
+  "version": "0.7.1-next.886",
+  "fingerprint": "eb8ae32e3145ae3090c81c8a5c17f5776fe9445e6dd047815eb8610424c87ee7",
+  "source_commit": "d291002061d8a9ec2fb14765e14c786783d8aa9c"
 }