Skip to content

Repository navigation

docs(packages): explain updates from the compatible collection #70

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Mathih13 merged 2 commits into from
Oct 10, 2026
Merged

docs(packages): explain updates from the compatible collection #70

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
40b0a47
docs(packages): explain updates from the compatible collection
Mathih13 Oct 10, 2026
98cf4be
docs(packages): clarify checks for disabled updates
Mathih13 Oct 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 28 additions & 28 deletions docs/commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ lyracore update
| `packages new` | copy and rename a Reference Package from the collection tag matching this checkout's Package API |
| `packages remove` | delete a disabled Package, after a confirmation and a check for local changes |
| `packages replay` | reapply every enabled Package's claims and Runtime Scripts onto the named Shards, or the whole recorded fixture topology by default |
| `packages update` | advance a Git-backed Package, or every one of them, to the repository's current commit |
| `packages update` | update Git Package Sources from their repository and Official Package Sources from the compatible collection tag |
| `character gm` | flip GM commands on or off for a character, on whichever world shard has it |
| `production status` | read-only checks for an explicitly named production topology and the latest gateway start |
| `service reconcile` | make a production host's Standalone Supervisor match the unit tracked in this checkout. Root only |
Expand Down Expand Up @@ -229,7 +229,7 @@ for you**, so a plain `./lyracore import` never asks twice.
./lyracore packages add https://host/greeter.git # clone a repository whose root is one Package
./lyracore packages add greeter # bare name: resolve from the Official Package Collection
./lyracore packages list
./lyracore packages new my-package # start with example-script
./lyracore packages new my-package # start from example-script
./lyracore packages new my-package --from example-rust
```

Expand All @@ -240,8 +240,8 @@ around saying so.

**Everything that can refuse the install happens before anything is copied.** The name must be one
the build accepts (`[a-zA-Z][a-zA-Z0-9_-]*` — the build maps `my-package` onto the module
`pkg_my_package` and panics on anything else). A Package must carry `src/`, `client/`, `data/`, `scripts/` or `datascripts/`.
When `src/` exists, `src/mod.rs` is required. The name must
`pkg_my_package` and panics on anything else). A Package must carry `src/`, `client/`, `data/`,
`scripts/` or `datascripts/`. When `src/` exists, `src/mod.rs` is required. The name must
collide with neither the enabled nor the disabled inventory, compared on the Rust identifier rather
than the folder name — `my-package` and `my_package` fold onto the same module.

Expand All @@ -250,8 +250,9 @@ candidate folder using a port of the build's own marker scan, so a commented-out
registers nothing here either. It reports tables, reducers, hooks, tick passes, character-owned
sweeps, addons, client overrides and Runtime Script sources. Runtime Scripts are named because they
run on the Realm once the Package is built. It also names Package-local Datascripts, which
`packages build` runs as trusted code on the author's machine. The review states plainly that everything else in the Package's
Rust is trusted code and that it is an inventory, not a security guarantee.
`packages build` runs as trusted code on the author's machine. The review states plainly that
everything else in the Package's Rust is trusted code and that it is an inventory, not a security
guarantee.

On confirmation the folder is **copied, never symlinked**: a linked Package would compile from a
folder outside the checkout, so `preflight`, `publish` and `client sync` would each read whatever
Expand All @@ -274,14 +275,14 @@ waiting on a hidden prompt.
**A bare word that is not a path on this machine is an Official Package Source.** `packages add
greeter` resolves `greeter` against the one Official Package Collection this CLI knows,
`LyraCoreProject/packages`, which holds several first-party Packages side by side, one top-level
directory each. The collection is cloned the same way a Git Package Source is, the named directory
goes through the same Trust Review and consent question as any other install, and the rest of the
clone is discarded. An unknown name is refused before anything is copied; a name that only differs
directory each. The version in the checkout's `docs/package-api.md` selects a tag such as `api-v1`.
The CLI fetches that tag and sends the named directory through the same Trust Review and consent
question as any other install. A missing tag refuses the install; the rest of the clone is
discarded. An unknown name is refused before anything is copied; a name that only differs
from one already in the collection by hyphen/underscore folding is named in the refusal instead of
installed in its place. The Provenance Stamp records the collection's URL and the exact commit the
directory was resolved at. That commit is pinned at install time: `packages update` refuses this
kind by name (see below), so a later commit to the collection can never silently change what is
installed. Picking up a newer one means removing the Package and adding it again.
directory was resolved at. `packages update` can advance the installed Package to the current
commit at the compatible tag, after the normal Trust Review and confirmation.

**It publishes nothing.** The two remaining steps are printed for you to run:

Expand Down Expand Up @@ -382,39 +383,38 @@ Save them outside the checkout first, or delete the folder by hand.

**None of the three publishes or synchronizes a client.** Each prints the steps it did not run.

## `packages update` — advancing a Git-backed Package
## `packages update`

```bash
./lyracore packages update my-package # advance one Package, asks first
./lyracore packages update # advance every Git-backed Package
./lyracore packages update # advance every Git or Official Package Source
./lyracore packages update --yes # answer the questions in advance
```

**Only a Git-backed Package can be updated.** With a name, anything else is refused by name and told
why: a Package installed from a local folder has no newer revision to fetch, a scaffold has no
Package Source at all, an Official Package Source has its commit pinned at install time on purpose,
and a Package Source kind this CLI does not otherwise know is not cloned on the chance that it might
be a repository. With no name, `update` walks both inventories and takes the Git-backed Packages,
disabled ones included. A disabled Package that comes back later should not bring an old revision
with it.
Git Package Sources and Official Package Sources can be updated. With a name, other source kinds
are refused: a local folder has no remote revision to fetch, a scaffold contains code the author
owns, and an unknown source kind is not cloned. With no name, `update` selects both supported
source kinds from the enabled and disabled inventories.

Each update clones the recorded repository and compares the commit it finds against the recorded
one. Same commit, nothing to do. A newer commit gets the same Trust Review and the same question as
an install, and the question names both commits.
A Git Package Source uses the recorded repository's current commit. An Official Package Source
uses the tag matching the checkout's Package API version and resolves the same Package name there.
A missing tag or Package refuses the update before changing the installed copy.

If the resolved commit matches the Provenance Stamp, there is nothing to do. A different commit
gets the same Trust Review and confirmation as an install, with both commits named.

**A folder that has drifted from its Provenance Stamp is refused, and nothing is discarded.** An
update replaces the whole folder, so it may only run when every byte in that folder is recorded
somewhere else. That is `packages remove`'s rule, for the same reason: local edits to an installed
copy are recorded nowhere, and neither command can get them back.

**The previous revision is kept until the new one is proven.** The old folder moves out of the
inventory, the new revision installs in its place, and `preflight` runs with it compiled in. Only
then is the old folder deleted. If anything fails, the previous revision goes back byte for byte,
inventory, the new revision installs in its place, and `preflight` runs. A disabled Package stays
disabled and is excluded from compilation. The old folder is deleted only after `preflight` passes. If anything fails, the previous revision goes back byte for byte,
the candidate is discarded, and the error names both commits. `update` publishes nothing and
synchronizes no client; it prints the steps it did not run.

Applying and replaying Package Deltas is `packages replay`, below. Advancing an Official Package
Source through `packages update` remains separate work.
Applying and replaying Package Deltas is `packages replay`, below.

## `packages config` — a Package's key-values, on every Shard

Expand Down
Loading