feat(packages): move the Reference Packages to the collection

.gitignore

@@ -55,15 +55,9 @@ __pycache__/
 /datascripts/node_modules/
 /datascripts/runtime-scripts/node_modules/
 
-# Packages installed on a host (`lyracore packages add`) are local to that checkout. Unknown
-# Package directories stay out of Git status. Source files in the committed first-party Packages
-# remain visible.
+# Installed Packages are local to this checkout. Reference Packages live in the collection.
 /packages/*
-!/packages/example/
-!/packages/fire_nova/
+!/packages/README.md
 
-# What `lyracore packages build` writes into a first-party Package: Package Deltas, Script Artifacts
-# and their Build Identity sidecars. Here they are output the sources next to them reproduce, so
-# none is committed. A Package Delta is never committed anywhere (licensing firewall); the Official
-# Package Collection does commit Script Artifacts, so an Operator installs prebuilt Lua without Bun.
+# Generated Package output stays local. The collection may commit Script Artifacts, never Deltas.
 /packages/*/data/.generated/

.lyracore-cli-rev

@@ -1 +1 @@
-091b502a1020e483df4322881bd808e0e6c958db
+950a03ff593722109482ab6dd496e94148ecf709

CONTEXT.md

@@ -920,7 +920,7 @@ _Avoid_: weather event, weather state table
 ### Packages
 
 **Package**:
-A drop-in folder under `packages/<name>/` that adds content to the realm with no core-file edits. Its `src/` is compiled into the Module wasm by the build's own discovery; its `client/` half supplies addons, whole-file client overrides and UI Transforms to the client packer. Either half alone is a valid Package.
+A drop-in folder under `packages/<name>/` that adds content to the realm with no core-file edits. Its `src/` is compiled into the Module wasm by the build's own discovery; its `client/` half supplies addons, whole-file client overrides and UI Transforms to the client packer. A Package can also carry Runtime Scripts in `scripts/`, Datascripts in `datascripts/`, and generated artifacts in `data/.generated/`. Any one of these parts is enough.
 Its data changes ship as Package Deltas rather than as edits to the base data.
 Package-specific tests live with the Package. Core supplies reusable private integration fixtures;
 the Package's test runner selects the Core checkout and owns its compatibility checks.
@@ -961,31 +961,31 @@ rows, so the Package's tables must be empty first. `lyracore packages disable` r
 _Avoid_: uninstall, package wipe, cleanup
 
 **Reference Package**:
-The maintained, minimal Package at `packages/example/`, committed to the LyraCore repo and present in every checkout. It doubles as living documentation for a Package's shape and is the template `lyracore packages new` copies and renames. It is deliberately inert: Rust-only, one commented hook pattern, no gameplay behavior.
+One rung of the maintained example ladder in the [Official Package Collection](https://github.com/LyraCoreProject/packages#packages): `example-script`, `example-client`, `example-data`, `example-rust` or `example-all`. Each adds a small welcome at one level of the Package API. `lyracore packages new NAME [--from RUNG]` copies and renames one at the collection tag matching the checkout's Package API version. The default is `example-script`. Core ships no enabled Reference Package.
 _Avoid_: template package, sample package
 
 **Package Source**:
-Where an installed Package was copied from: a local folder on the Operator's machine, a Git Package Source, or an Official Package Source. A scaffolded Package (`lyracore packages new`) has none. It was not copied from anywhere the Operator chose, so its Provenance Stamp records a scaffold origin instead.
+Where an installed Package was copied from: a local folder on the Operator's machine, a Git Package Source, or an Official Package Source. A scaffolded Package records a scaffold origin, its Reference Package rung and the collection revision. The author owns that copy; `packages update` does not replace it.
 _Avoid_: origin, upstream, repo
 
 **Git Package Source**:
-A repository whose root is one Package, named by a URL. `lyracore packages add <git-url>` clones it and installs a copy of its tree, without the `.git`. An installed Package is never a working copy, so `lyracore packages update` re-clones rather than pulling. A Package installed this way is Git-backed, and it is the only kind `update` can advance.
+A repository whose root is one Package, named by a URL. `lyracore packages add <git-url>` clones it and installs a copy of its tree, without the `.git`. An installed Package is never a working copy, so `lyracore packages update` re-clones rather than pulling. A Package installed this way is Git-backed, and `packages update` can advance it.
 _Avoid_: git remote, upstream repo, checkout
 
 **Official Package Collection**:
 The one repository, `LyraCoreProject/packages`, that holds several first-party Packages side by side, one top-level directory each. `lyracore packages add <name>` resolves a bare Package name against it: a folder on the Operator's machine or a Git URL keeps its own rules, and only a name that matches neither falls back to the collection.
 _Avoid_: registry, package repository, marketplace
 
 **Official Package Source**:
-The top-level directory of the Official Package Collection that a bare `lyracore packages add <name>` installed. Its Provenance Stamp records the collection's URL and the Recorded Revision the directory was resolved at, the same way a Git Package Source records its repository and commit. The commit is pinned at install time: `lyracore packages update` refuses this kind by name, so a later commit to the collection cannot silently change what is installed.
+The top-level directory of the Official Package Collection that a bare `lyracore packages add <name>` installed. Its Provenance Stamp records the collection's URL and the Recorded Revision the directory was resolved at, the same way a Git Package Source records its repository and commit. The checkout's Package API version selects a collection tag. `packages update` resolves that tag again and records the new commit after the update passes its checks.
 _Avoid_: registry entry, published package
 
 **Recorded Revision**:
-The exact commit a Git Package Source or an Official Package Source was installed at, held in its Provenance Stamp. `lyracore packages update` advances a Git Package Source from this rather than from whatever the repository's branch points at now, so it can name both commits when it reports or restores.
+The exact commit a Git Package Source, Official Package Source or Reference Package was copied from, held in its Provenance Stamp. `lyracore packages update` advances a Git Package Source from this rather than from whatever the repository's branch points at now, so it can name both commits when it reports or restores.
 _Avoid_: version, tag, pin
 
 **Provenance Stamp**:
-The record `lyracore packages add` writes inside an installed Package: its Package Source, its Content Identity at install time, when it was installed, and, for a Git or Official Package Source, its Recorded Revision. A Package without one is still a Package; only its history is unknown.
+The record `lyracore packages add` writes inside an installed Package: its Package Source, its Content Identity at install time, when it was installed, and, for a Git or Official Package Source or a scaffold, its Recorded Revision. A scaffold also records its Reference Package rung. A Package without one is still a Package; only its history is unknown.
 _Avoid_: manifest, lockfile, metadata
 
 **Content Identity**:
@@ -1005,7 +1005,7 @@ The maintained, minimal Datascript at `datascripts/src/reference.ts`. It names r
 _Avoid_: sample script, test script
 
 **Authoring Library**:
-The typed API at `datascripts/lib/` that a Datascript writes against: `data.spell(id)`, `.clone(newId)`, `.set(field, value)`, `.effect(0 | 1 | 2)`, and a `run(package, script)` that emits one Package Delta. It reads the Base Snapshot and refuses exactly what the artifact parser refuses, so a Datascript fails at author time rather than at import. Its source lives outside the Package folder; only the generated artifact goes inside.
+The typed API at `datascripts/lib/` that a Datascript writes against: `data.spell(id)`, `.clone(newId)`, `.set(field, value)`, `.effect(0 | 1 | 2)`, and a `run(package, script)` that emits one Package Delta. It reads the Base Snapshot and refuses exactly what the artifact parser refuses, so a Datascript fails at author time rather than at import. The library lives in Core. A Package carries its Datascripts in `datascripts/`; Core's legacy `datascripts/src/<package>/` path also works.
 _Avoid_: SDK, framework, DSL, builder API
 
 **Base Snapshot**:

CONTRIBUTING.md

@@ -42,7 +42,7 @@ first commit. A maintainer then marks the issue `in progress`.
 ## Building on top
 
 New content and behaviour beyond 1.12.1 live in a Package. `lyracore packages new <name>`
-scaffolds one from the reference Package. [`docs/package-api.md`](docs/package-api.md) lists what
+scaffolds one from the Reference Package ladder in the collection. Use `--from` to choose a rung. [`docs/package-api.md`](docs/package-api.md) lists what
 a Package may call, and the build fails on anything else. The Official Package Collection,
 [LyraCoreProject/packages](https://github.com/LyraCoreProject/packages), takes pull requests under
 its own contributing guide.

crates/lyracore-test-support/README.md

@@ -3,6 +3,8 @@
 `Standalone` owns an isolated SpacetimeDB process, CLI configuration and database storage. Tests
 can publish the selected Core Module, call reducers, read durable state and retain failure logs.
 `module_bytes()` and `gateway_binary()` build the tested artifacts once per test process.
+The test Module enables `debug_reducers` and `package_test_fixture`. The latter registers an inert
+Package named `test_fixture` for Core's ownership and teardown tests; normal publishes omit it.
 
 Core tests use this crate's workspace. Package test runners set `LYRACORE_TEST_CORE` to the explicit
 Core checkout used for both builds and evidence. Package-specific setup and assertions belong in

crates/lyracore-test-support/src/module_wasm.rs

@@ -17,7 +17,7 @@ fn build_module_bytes() -> Vec<u8> {
             "--release",
             "--target",
             "wasm32-unknown-unknown",
-            "--features=debug_reducers",
+            "--features=debug_reducers,package_test_fixture",
         ],
     );
     let bytes = std::fs::read(&wasm).expect("the test Module output is missing");

datascripts/tests/emit.test.ts

@@ -7,7 +7,7 @@
 //
 //   LYRACORE_BASE_SNAPSHOT=datascripts/tests/fixtures/base-snapshot.json \
 //   LYRACORE_PACKAGES_ROOT=<scratch dir> \
-//   bun run datascripts/src/fire_nova/spells.ts
+//   bun run datascripts/tests/fixtures/fire_nova.ts
 //
 // The Datascript is run as a SUBPROCESS rather than imported, because the source hash it records is
 // the entry script's own digest — which only means what it says when the entry script is the
@@ -19,7 +19,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 const REPO = join(import.meta.dir, "..", "..");
-const DATASCRIPT = join(REPO, "datascripts", "src", "fire_nova", "spells.ts");
+const DATASCRIPT = join(import.meta.dir, "fixtures", "fire_nova.ts");
 const SNAPSHOT = join(import.meta.dir, "fixtures", "base-snapshot.json");
 const FROZEN = join(import.meta.dir, "fixtures", "fire-nova.expected.json");