@marktiderman/genesis 0.2.2 → 0.2.3

package/README.md

@@ -28,3 +28,56 @@ Web bundlers never pull in React Native code unless a consumer explicitly
 imports `@marktiderman/genesis/native` — `react-native` is an optional peer
 dependency. Each granular package remains independently installable as an
 escape hatch for rare subpaths not mirrored here.
+
+## The Genesis version coordinate
+
+`@marktiderman/genesis`'s own version is the **single canonical coordinate for
+the whole Genesis system** — the one number that answers "which Genesis am I
+on?" for a consuming repo. Pin one umbrella version and the entire set is
+determined:
+
+- **Sub-packages.** The umbrella depends on `@marktiderman/genesis-{core,ui,
+  design-system,switchboard,ui-native}` via `workspace:*`, which pnpm replaces
+  with the **exact** published version at pack time. So `@marktiderman/genesis@X`
+  resolves one reproducible, pinned set — not a caret range that drifts. Each
+  granular package keeps its own independent semver train; the umbrella version
+  is the coordinate that names a specific combination of them.
+- **Vendored harness.** `scripts/harness/genesis-sync.sh` stamps
+  `GENESIS_SOURCE_VERSION` in a child's `.genesis/source` from this same umbrella
+  version (`GENESIS_SOURCE_SHA` stays the precise git-HEAD pointer). So a child's
+  harness stamp and its `@marktiderman/genesis` npm pin read the **same** number.
+- **Plugin / marketplace.** `.claude-plugin/plugin.json`'s `version` tracks the
+  umbrella coordinate, kept in lockstep by `scripts/harness/sync-plugin-version.mjs`
+  (run automatically in the release "version packages" step).
+
+The coordinate advances whenever any pinned sub-package is released. The deciding
+option is changesets' `updateInternalDependents` (default `"out-of-range"`) — **not**
+`updateInternalDependencies`: because the umbrella pins each sub-package via
+`workspace:*`, which changesets resolves to the dependency's **exact** current
+version, any sub-package release moves that dependency out of the umbrella's pinned
+range, so `out-of-range` pulls the umbrella into the same release plan and bumps it.
+(`updateInternalDependencies`, default `"patch"`, only sets the resulting bump
+_type_ once the umbrella is already in the plan — it does not decide whether the
+umbrella is bumped.) The `workspace:*` exact pin is what makes this automatic — a
+caret range would let a patch stay in range and skip the umbrella — so `PKG-04`
+enforces the exact pin. The release step then re-syncs the plugin stamp. One pinned
+umbrella version therefore means every sub-component **and** the harness is already
+"in the system," versioned and pinned together.
+
+Because this auto-advance rests on a changesets **default** rather than an explicit
+config key — a top-level `updateInternalDependents` is silently ignored in changesets
+2.30.0 (the option is read only from the `___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH`
+namespace) — the invariant is made upgrade-safe two ways instead: `@changesets/cli` is
+pinned to `~2.30.0` so a minor bump can't silently flip the default, and `PKG-05`
+empirically re-asserts the umbrella auto-bump on every run (it drives changesets' own
+release-plan assembly with a synthetic sub-package-only changeset). A future changesets
+change that broke the coordinate would fail CI loudly instead of shipping silently.
+
+**Caveat — the release-PR window.** The umbrella version bumps via a changesets
+"version packages" PR, not on the feature-PR merge itself. So there is a brief,
+transient window — feature PR merged, "version packages" PR not yet merged — where
+`main`'s `packages/genesis/package.json` still carries the _previous_ umbrella version.
+A child that runs `genesis-sync.sh` during that window stamps the new harness contents
+with that previous version number. Nothing is silently lost: `GENESIS_SOURCE_SHA` (git
+HEAD) is always exact and is the precise pointer; only the human-readable coordinate can
+lag by one release until the "version packages" PR merges.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@marktiderman/genesis",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "private": false,
   "type": "module",
   "sideEffects": false,
-  "description": "Genesis — one-install umbrella for the Genesis DS. Re-exports @marktiderman/genesis-core, -ui, -design-system, -switchboard, and -ui-native (as /native) via subpath exports. Holds no code of its own; each granular package remains independently installable.",
+  "description": "Genesis — one-install umbrella and single version coordinate for the Genesis system. Re-exports @marktiderman/genesis-core, -ui, -design-system, -switchboard, and -ui-native (as /native) via subpath exports and exact-pins each to a reproducible set. Holds no code of its own; each granular package remains independently installable.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/marktiderman/genesis.git",
@@ -68,11 +68,11 @@
     }
   },
   "dependencies": {
-    "@marktiderman/genesis-core": "^1.0.0",
-    "@marktiderman/genesis-ui": "^1.1.1",
-    "@marktiderman/genesis-design-system": "^1.0.0",
-    "@marktiderman/genesis-switchboard": "^1.0.0",
-    "@marktiderman/genesis-ui-native": "^2.0.0"
+    "@marktiderman/genesis-core": "1.0.0",
+    "@marktiderman/genesis-ui": "1.1.1",
+    "@marktiderman/genesis-design-system": "1.0.0",
+    "@marktiderman/genesis-switchboard": "1.0.0",
+    "@marktiderman/genesis-ui-native": "2.0.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",