From 5a9c828ed07dd36ff274fce767fc7b122c7c7c99 Mon Sep 17 00:00:00 2001 From: Mathih13 Date: Sat, 10 Oct 2026 16:20:38 +0200 Subject: [PATCH 1/4] docs(packages): explain Package activation with apply --- CONTEXT.md | 5 +++++ docs/danger-zones.md | 4 +++- importer/src/package_delta.rs | 2 +- 3 files changed, 9 insertions(+), 2 deletions(-) diff --git a/CONTEXT.md b/CONTEXT.md index a69bad89..94254a49 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -982,6 +982,11 @@ _Avoid_: config file, setting (unqualified), package setting The two directories that hold installed Packages. `packages/` holds the enabled ones, which the build compiles. `.lyracore/packages-disabled/` holds the disabled ones, which it cannot see. A Package's location IS its enabled state; no file records it, so nothing can disagree with the disk about what the next build compiles. `lyracore packages enable` and `lyracore packages disable` move one folder between the two. _Avoid_: registry, package list, enabled flag, state file +`lyracore packages apply` prepares missing or stale artifacts from installed sources, publishes +the Module when the inventory contains Rust or a target records pending Package Teardown, and +applies spell and script artifacts to the chosen Shards. It repairs schedules after each publish. +Client content uses `lyracore client sync`. + **Package Teardown**: The Operator step that stops a Package on every Shard before it leaves the Package Inventory. It makes the Package's Characters Dormant Characters, empties the Package's tables, deletes its Package diff --git a/docs/danger-zones.md b/docs/danger-zones.md index 59bb4bd9..b0f07b47 100644 --- a/docs/danger-zones.md +++ b/docs/danger-zones.md @@ -116,7 +116,9 @@ any line in §1 needs a human review before it ships, whoever or whatever wrote and [HTTP body](https://github.com/clockworklabs/SpacetimeDB/blob/v2.7.1/crates/cli/src/api.rs#L69-L76). - **`game_package_import` is private and has no gateway binding.** Read it with `spacetime sql` only, and with an EQUALITY filter on `family` (a range filter on one column can wrongly return 0 - rows). `lyracore packages replay` is the supported way to change it; never write it by hand. + rows). `lyracore packages apply` is the supported way to change it; never write it by hand. + `apply` can build local artifacts and publish the Module for Rust Packages. Its confirmation + covers the Realm changes; `--check` prepares locally without Realm writes. An empty Package Delta payload is not "unknown" — it means "no Package claims this family" and CLEARS the Package spell range. - **`auto_inc` sequences sit BEHIND explicitly-numbered imported rows.** A content import writes diff --git a/importer/src/package_delta.rs b/importer/src/package_delta.rs index 25489edc..7db67766 100644 --- a/importer/src/package_delta.rs +++ b/importer/src/package_delta.rs @@ -198,7 +198,7 @@ fn read_enabled(root: &Path) -> Result> { // One Package ships every artifact kind it has into this one directory, so the glob // above finds a Script Artifact next to a Package Delta. Skipping it is not leniency: // this stage is the CLAIM half of an apply, and the script family has no base import to - // run behind. `lyracore packages replay` applies that family separately. Anything this + // run behind. `lyracore packages apply` applies that family separately. Anything this // router cannot read at all still goes to the parser, which names what is wrong with it. if matches!( artifact_kind(&json), From add717d86a0c89c7d0953182e6399cb1064697f7 Mon Sep 17 00:00:00 2001 From: Mathih13 Date: Sat, 10 Oct 2026 16:29:24 +0200 Subject: [PATCH 2/4] feat(cli): pin Package apply activation --- .lyracore-cli-rev | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.lyracore-cli-rev b/.lyracore-cli-rev index 094bc10d..e3f5f409 100644 --- a/.lyracore-cli-rev +++ b/.lyracore-cli-rev @@ -1 +1 @@ -950a03ff593722109482ab6dd496e94148ecf709 +65158741481236ab435de54693dd530a4075ad90 From f9258e66096dde86087d2f22c7606166daaaacfe Mon Sep 17 00:00:00 2001 From: Mathih13 Date: Sat, 10 Oct 2026 16:36:32 +0200 Subject: [PATCH 3/4] docs(packages): explain apply in Core installation guides --- CONTEXT.md | 6 +----- README.md | 2 ++ docs/danger-zones.md | 11 +++++++---- packages/README.md | 39 +++++++++++++++++++++++++++++++++------ 4 files changed, 43 insertions(+), 15 deletions(-) diff --git a/CONTEXT.md b/CONTEXT.md index 94254a49..98382f94 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -980,13 +980,9 @@ _Avoid_: config file, setting (unqualified), package setting **Package Inventory**: The two directories that hold installed Packages. `packages/` holds the enabled ones, which the build compiles. `.lyracore/packages-disabled/` holds the disabled ones, which it cannot see. A Package's location IS its enabled state; no file records it, so nothing can disagree with the disk about what the next build compiles. `lyracore packages enable` and `lyracore packages disable` move one folder between the two. +`lyracore packages apply` applies the enabled set to the chosen Shards. See [Applying packages](packages/README.md#applying-packages) for artifact preparation and Module publishing. _Avoid_: registry, package list, enabled flag, state file -`lyracore packages apply` prepares missing or stale artifacts from installed sources, publishes -the Module when the inventory contains Rust or a target records pending Package Teardown, and -applies spell and script artifacts to the chosen Shards. It repairs schedules after each publish. -Client content uses `lyracore client sync`. - **Package Teardown**: The Operator step that stops a Package on every Shard before it leaves the Package Inventory. It makes the Package's Characters Dormant Characters, empties the Package's tables, deletes its Package diff --git a/README.md b/README.md index 36501b2b..7789d805 100644 --- a/README.md +++ b/README.md @@ -55,9 +55,11 @@ in TypeScript or Lua, data changes, client addons, Rust code, or any mix of thes ```bash lyracore packages new my-package # start your own lyracore packages add playerbots # install an official one +lyracore packages apply # build and activate enabled Packages ``` The official Packages live in [LyraCoreProject/packages](https://github.com/LyraCoreProject/packages). +[Applying packages](./packages/README.md#applying-packages) explains what the command changes. [`docs/package-api.md`](./docs/package-api.md) lists what a Package's Rust code may call. ## Architecture diff --git a/docs/danger-zones.md b/docs/danger-zones.md index b0f07b47..b2b59410 100644 --- a/docs/danger-zones.md +++ b/docs/danger-zones.md @@ -117,8 +117,9 @@ any line in §1 needs a human review before it ships, whoever or whatever wrote - **`game_package_import` is private and has no gateway binding.** Read it with `spacetime sql` only, and with an EQUALITY filter on `family` (a range filter on one column can wrongly return 0 rows). `lyracore packages apply` is the supported way to change it; never write it by hand. - `apply` can build local artifacts and publish the Module for Rust Packages. Its confirmation - covers the Realm changes; `--check` prepares locally without Realm writes. + `apply` can publish the Module. See [Applying packages](../packages/README.md#applying-packages) + for the publish conditions. Its confirmation covers the Realm changes; `--check` prepares locally + without Realm writes. An empty Package Delta payload is not "unknown" — it means "no Package claims this family" and CLEARS the Package spell range. - **`auto_inc` sequences sit BEHIND explicitly-numbered imported rows.** A content import writes @@ -422,6 +423,7 @@ cargo build # `--features=debug_reducers` (a bare `spacetime publish` omits it, drops the feature-gated debug # tables, and then false-aborts on a bogus "Removed table: game_debug_readout"), passes `--yes`, and # REFUSES `-c` and any other flag-shaped argument. Plain publish = safe auto-migrate. NEVER -c. +# `packages apply` can also publish the Module. See packages/README.md for its publish conditions. ./lyracore publish # ⚠ With no names, that publishes the FIXTURE topology recorded in this checkout's own # `.lyracore/state.json` — normally absent on a production host, which falls back to the default @@ -477,8 +479,9 @@ sleep 4 # RUST_LOG=info deliberately, not info,gateway::world=debug: since the raw-bytes relay, every packet # logs a line, which floods at scale. -# ⚠ Now call `debug_repair_after_publish` BY HAND, on EVERY shard you just published. Nothing runs -# it for you. It re-arms the motion, creature-tick, aura, ground-area, weather, gateway-lease and +# After `lyracore publish`, call `debug_repair_after_publish` on every published Shard. +# `packages apply` already calls it on each Shard it publishes. +# It re-arms the motion, creature-tick, aura, ground-area, weather, gateway-lease and # instance-reaper schedules and re-seeds every fixture family `init` seeds but an auto-migrating # republish does not re-run. Skipping it presents as a mid-session hang, not an error. # Folding it into `lyracore publish` is issue 41 in the lyracore-cli repository. diff --git a/packages/README.md b/packages/README.md index b164d935..fb63fa9d 100644 --- a/packages/README.md +++ b/packages/README.md @@ -31,11 +31,37 @@ Official Package Source at the compatible tag, but does not replace a scaffold. A folder or Git URL passed to `packages add` keeps its own source rules. Review a Package as you would a Core patch. Its Rust is trusted Module code. +## Applying packages + +After creating, installing or changing a Package, apply the enabled Packages to your Shards: + +```bash +./lyracore packages apply +``` + +With no Shard names, the command uses the recorded development topology. Pass Shard names to +choose other Shards. It builds missing or stale artifacts from enabled sources, then applies +spell Package Deltas and Script Artifacts. Current Script Artifacts need neither Bun nor client data. +A Datascript build needs Bun and your own client data. If its Base Snapshot is missing, `apply` +extracts one locally. Use `--client-data PATH` to select the client's Data directory. + +If an enabled or disabled Package contains `src/mod.rs`, or a Shard records pending Package +Teardown, `apply` publishes the Module built from the enabled Packages. Including disabled Rust +Packages in this decision ensures the publish removes their code. After each publish it calls +`debug_repair_after_publish` to restore Module schedules and fixtures. Each Shard completes its +publish, repair and artifact application before the next Shard starts. + +The command asks once before changing the Realm. Use `--check` to prepare local artifacts and +validate the plan without Realm writes. Client content uses `lyracore client sync` separately. +For flags and retry behavior, see the +[CLI commands](https://github.com/LyraCoreProject/lyracore-cli/blob/main/docs/commands.md). + ## Building source -`lyracore packages build` runs Package-local `datascripts/*.ts` as well as Core's legacy -`datascripts/src//*.ts`. Datascripts use the Authoring Library and a Base Snapshot from -your own client data. Their Package Deltas and Build Identities stay local under `data/.generated/`. +Use `lyracore packages build` to build artifacts without applying them. It runs Package-local +`datascripts/*.ts` as well as Core's legacy `datascripts/src//*.ts`. Datascripts use the +Authoring Library and a Base Snapshot from your own client data. Their Package Deltas and Build +Identities stay local under `data/.generated/`. Never commit a Package Delta to the collection. Runtime Scripts use `scripts/*.ts` or `scripts/*.lua`. The build compiles them into a Script @@ -50,7 +76,7 @@ Each source starts with an event and a durable Script ID: Optional `@priority` defaults to `0`, and `@enabled` defaults to `true`. TypeScript declares `function script(): number | void`. A numeric Script Answer is what a Package reads through `ask()`. Choose distinct IDs before installing multiple copies of a rung. After scaffolding, -run `packages build` to produce artifacts for the renamed source. +run `packages apply` to build and activate the renamed source. ## Client content @@ -66,7 +92,8 @@ Rust Packages seed Package Config with `ensure_package_config_default` and read topology, `lyracore packages config NAME KEY VALUE` changes it without a republish. `packages disable` runs Package Teardown and moves the folder to `.lyracore/packages-disabled/`. -`packages enable` moves it back. Folder location is the enabled state. +`packages enable` moves it back. Folder location is the enabled state. Run `packages apply` after +either command to apply the enabled set. See the [CLI commands](https://github.com/LyraCoreProject/lyracore-cli/blob/main/docs/commands.md) -for build, replay, client installation and Package management. +for build, apply, client installation and Package management. From dac57e4128345a44a8136f0be08ddbaa51cb28e1 Mon Sep 17 00:00:00 2001 From: Mathih13 Date: Sat, 10 Oct 2026 16:36:49 +0200 Subject: [PATCH 4/4] docs(packages): distinguish build and apply data inputs --- packages/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/README.md b/packages/README.md index fb63fa9d..e918e278 100644 --- a/packages/README.md +++ b/packages/README.md @@ -42,8 +42,9 @@ After creating, installing or changing a Package, apply the enabled Packages to With no Shard names, the command uses the recorded development topology. Pass Shard names to choose other Shards. It builds missing or stale artifacts from enabled sources, then applies spell Package Deltas and Script Artifacts. Current Script Artifacts need neither Bun nor client data. -A Datascript build needs Bun and your own client data. If its Base Snapshot is missing, `apply` -extracts one locally. Use `--client-data PATH` to select the client's Data directory. +A Datascript build needs Bun and a Base Snapshot. If the snapshot is missing, `apply` extracts one +from your own client data. Applying spell Package Deltas also reads client data. Use +`--client-data PATH` to select the client's Data directory. If an enabled or disabled Package contains `src/mod.rs`, or a Shard records pending Package Teardown, `apply` publishes the Module built from the enabled Packages. Including disabled Rust