carton 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a0f0305abe746709cf0b95c29f1f5d94d4ae4d794698205a4aa64fded37780b
-  data.tar.gz: 262c64943c2e73831507b95a8dde3e3e8f2ea712f6844e25fa02de178e292bd3
+  metadata.gz: bed12e1aae3d8c17c74727a84d09d04ace52545dde9320ca3d5bdf39661c7a93
+  data.tar.gz: 57207a6c9c8704239b023dc0b861a4c35ead18f43b7a593c70674712d6dcf084
 SHA512:
-  metadata.gz: b20c31a54f13d1a25296779c7bfc9b03adb4a6a2df8fb22cf6ebf7fa714f29b0d497ea8ddf7ca5a96e3e83cb76484d5687dfe7a9d9cb7563e5ab7d482d83f054
-  data.tar.gz: c0db95029ee083e52ab39b535f03a89bd8cc9ad5b9cf1d0741c90d65fb919e64a1ba369377a62ec17615e6e42a69d5969ec550093adebdba527caf79e12e0fe4
+  metadata.gz: c583efac379f57cdd89a500fee73327dab3bfd1130c7d738556077a0484a67b444d721fbb7442b5325da47a5b88a22cd907697bf132b1fb5e13fdafccb34fe84
+  data.tar.gz: ccfd7ce8ea6a5693f391c7e2533a0313e9e717755ae10576543dbd112a8785a0439e171402c80242e1abd6841e1dae9f0c45ba41c31872aae70759f8a31ad6d6

data/CHANGELOG.md

@@ -2,127 +2,100 @@
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-18
+
+`export` now takes one value, which `import` returns as is. This release also adds the `carton-tools` gem, whose `carton` command checks imports and exports and writes RBS, and makes a Carton's autoloads load in its own Box.
+
+### Breaking
+
+- `export` takes one value, which `import` returns as is, and replaces `export_default`: write `export Billing`. Named Exports are removed, since a Ruby module is already a namespace. Export a module of methods instead, or use keywords, which now export a plain Hash: `export version: '1.0'` returns `{ version: '1.0' }`, so read it with `[:version]` or a `=>` pattern. `export` may be called once per Entrypoint, and a Symbol, as in `export def add` or `export :Money`, raises `Carton::ExportError`.
+- `Carton::Exports` is renamed `Carton::Namespace`, and only Bare Cartons return it.
+
+### Added
+
+- The `carton-tools` gem, with a `carton` command that reads code with Prism and never runs it, so it needs no `RUBY_BOX=1`. Give it the app's files; it follows imports into every Carton they reach. It is released with `carton` at exactly the same version, and `carton` itself stays the runtime only, with no dependencies and no executable.
+- `carton check --strict` fails on warnings as well as errors, and a `# carton:dynamic` comment marks an intentionally dynamic import, such as plugin discovery, to silence its warning.
+- `carton check` follows names bound to imports and reports, as errors, a key an exported Hash does not have, read with `fetch(:nope)` or a `=>` pattern, and a reference to an exported module's private constant (`Billing::Tax`).
+- `bench/scale.rb` (`rake bench`) measures import time and memory as Cartons and bundles grow; [docs/performance.md](docs/performance.md) has the results.
+- `Carton::Namespace#keys` and `#to_h`, and a readable `inspect`: `#<Carton::Namespace add, PI>`.
+- `examples/plugins`, a report runner whose two plugins load bigdecimal 3.3.1 and 4.1.1 in one process from their own bundles, while one plugin's `Float#to_s` patch stays out of the host and the other plugin.
+- `carton rbs` writes `sig/generated/carton.rbs` so Steep knows what each import returns: an exported constant's own type, a record type for a keyword export, or a generated `Carton::Namespace::*` module for a Bare Carton, typed from rbs-inline `#:` annotations and literal values.
+- `carton check` reports missing imports, imports of files inside a Carton, import cycles, `require` calls that load a second copy of an imported Carton, and invalid `export` calls, and exits non-zero on errors.
+- `carton check` treats a gem Carton's gemspec as its manifest: it reports each gem the Carton imports or requires that its gemspec does not declare.
+- `examples/monorepo/test` shows both ways to test a Carton: a unit test that loads `pricing` with plain `require` and tests its private `Rounding`, and an integration test that imports the packages and sees only their exports. `rake example:<name>` runs an example's `test/**/*_test.rb` after `main.rb`.
+- `examples/rails_in_cartons` declares the `logger` dependency its `shop` Carton requires.
+- `sig/carton.rbs` declares `Carton::NamespaceMethods`, which `Carton::Namespace` includes.
+- The minimal example type-checks with Steep.
+- `examples/zeitwerk` shows a Carton whose loader uses Zeitwerk 2.8 nsfiles (`loader.nsfile = 'ns.rb'`): a lazy namespace defined in `ns.rb` loads in the Carton's Box when the app references it first, and reloads with the Carton's other files. Another Carton runs Zeitwerk 2.7.5, without nsfiles, in the same process.
+- `examples/zeitwerk` shows Zeitwerk with Cartons outside Rails: a Carton using `Zeitwerk::Loader.for_gem`, a separate Zeitwerk per Box, an app loader that ignores a Carton in its directory, eager loading so autoloads never run in an importer's Box, and reloading, which leaves importers' references stale.
+
+### Changed
+
+- The README and gem summary present Carton as the package system Ruby has been missing, with the tagline "Real boundaries for Ruby", and compare it with Bundler and Packwerk. The README states what a Box does and does not isolate next to its promises, and says where Carton fits today: an app's or monorepo's domains, plugin hosts with conflicting gem versions, Rails inside Cartons as experimental, and not file-by-file loading. Usage recommends exporting a root module, and the docs show shared imports' consequences early, with a plugin testing recipe. Rails in the Main Box is the recommended Rails setup.
+- A Bare Carton helper named like a method every `Carton::Namespace` has, such as `def fetch` or `def name`, raises `Carton::ExportError`. It used to replace the built-in method, so `namespace.fetch(:fetch)` broke. `carton check` reports these too.
+- A missing `import_relative` target's `LoadError` names the files Carton tried, and a name `import` cannot find says it searched `$LOAD_PATH`, suggesting `import_relative` when a matching file is beside the caller.
+- The Rails examples eager load their Cartons' Zeitwerk loaders, so `rails_in_main` no longer loads `Billing::Invoice` in the Main Box, and both gain a Development section on restarting after changes. Each example README now opens with the problem it solves, and `master_prelude` moved out of the README's examples table to an Experiments note.
+
+### Fixed
+
+- An Entrypoint that starts a thread which imports another Carton, and waits for it, no longer blocks forever. The import cache held one global lock while running every Entrypoint; it now locks only its bookkeeping and makes a thread wait only for an Entrypoint another thread is loading.
+- `carton check` no longer reports `export` calls in different branches of one `if`, `unless`, or `case` as duplicates, since only one branch runs.
+- A shared gem Carton raises `Carton::ImportError` when a later importer locks a different version of a gem it loaded without declaring, such as an undeclared gem the first importer's lockfile allowed, including one it required lazily after its import. Before, only its declared dependencies were compared, so it could be shared silently.
+- A Bare Carton imported from a gem no longer exposes `Bundler`, `Psych`, `Date`, or `DateTime`, which Carton's gem activation loaded into its Box.
+- A gem Carton's default-gem dependencies, such as `json` and `date`, keep the importer's activated version when a newer one is installed.
+- The master_prelude example and Box docs no longer claim the Main Box is unaffected: patches loaded into Master can reach Main and existing Boxes, depending on Ruby's copy-on-write state.
+- An autoload a Carton defines, such as a lazy Zeitwerk constant, loads in the Carton's Box even when an importer references it first. It used to run in the importer's Box, often the Main Box, or raise `NameError` when the importer used another name. Autoloaded files also go through the Box's `Kernel#require`, so Zeitwerk's `on_load` callbacks and reloading see them.
+
 ## [0.2.0] - 2026-10-17
 
-Cartons are now gem-sized or domain-sized units: a file plus the directory
-named after it. This release also redesigns exports, shares imports across
-the process, adds gem and Bundler support, and requires Ruby 4.0.7.
+Cartons are now gem-sized or domain-sized units: a file plus the directory named after it. This release also redesigns exports, shares imports across the process, adds gem and Bundler support, and requires Ruby 4.0.7.
 
 ### Breaking
 
-- A Carton is now a file plus the directory named after it, the shape of a
-  gem's `lib/`: `billing.rb` and everything under `billing/`, including
-  Zeitwerk implicit-namespace directories. Importing a file inside a Carton,
-  such as `import 'billing/invoice'`, raises `Carton::ImportError` naming the
-  import to use. It used to load a second copy of the file in its own Box, so
-  its classes did not match the Carton's.
-- Carton now requires Ruby 4.0.7 or later, enforced by the gemspec, and
-  Bundler support needs Bundler 4.0.23 or later.
-- `export` can be called many times per file, and each call adds to one
-  Export Namespace. A capitalized Symbol exports a constant (`export :Money`),
-  other Symbols export methods (`export :add`, or `export def add ...`), and
-  keywords export plain values. Replace `export add: method(:add)` with
-  `export :add`. A missing name raises `NameError`, and a name exported twice
-  raises `Carton::ExportError`.
-- Exported methods forward when called (`exports.add(...)`), while `[]`,
-  `fetch`, and destructuring return the `Method` object. Keyword values are no
-  longer invoked: `export handler: -> {}` makes `exports.handler` return the
-  lambda.
-- `export_default` may be called only once per file and cannot be combined
-  with `export`; both raise `Carton::ExportError`. Put other names inside the
-  default value.
-- Importing a file with no exports (a Bare Carton) returns a `Carton::Exports`
-  of the constants and top-level helpers it defines, instead of its
-  `Carton::Box`. Importers can no longer `eval`, `require`, or read
-  `load_path` inside another Carton. Helpers are callable directly
-  (`toolbox.helper`), lookups return their `Method` object
-  (`toolbox.fetch(:helper).call`), and constants are read when the import
-  finishes. `Carton::Box` is now a private constant.
-- Imports are shared across the process. Each Carton file loads once, and
-  every later `import` or `import_relative` of it returns the same value, so
-  sibling Cartons share classes and Carton state no longer resets per import.
-  A Carton that imports itself raises `Carton::ImportError`.
-- `import 'name'` no longer checks the current directory before `$LOAD_PATH`,
-  so results no longer depend on where the app was started. Use an absolute
-  path, `import_relative`, or add the directory to `$LOAD_PATH`.
-- `Carton.with_bundle { require 'bundler/setup' }` is replaced by
-  `Carton.setup_bundle`. Pass groups as with `Bundler.setup`
-  (`Carton.setup_bundle(:default, :test)`) and choose a Gemfile with
-  `gemfile:`. Bundler errors raise instead of exiting the process.
+- A Carton is now a file plus the directory named after it, the shape of a gem's `lib/`: `billing.rb` and everything under `billing/`, including Zeitwerk implicit-namespace directories. Importing a file inside a Carton, such as `import 'billing/invoice'`, raises `Carton::ImportError` naming the import to use. It used to load a second copy of the file in its own Box, so its classes did not match the Carton's.
+- Carton now requires Ruby 4.0.7 or later, enforced by the gemspec, and Bundler support needs Bundler 4.0.23 or later.
+- `export` can be called many times per file, and each call adds to one Export Namespace. A capitalized Symbol exports a constant (`export :Money`), other Symbols export methods (`export :add`, or `export def add ...`), and keywords export plain values. Replace `export add: method(:add)` with `export :add`. A missing name raises `NameError`, and a name exported twice raises `Carton::ExportError`.
+- Exported methods forward when called (`exports.add(...)`), while `[]`, `fetch`, and destructuring return the `Method` object. Keyword values are no longer invoked: `export handler: -> {}` makes `exports.handler` return the lambda.
+- `export_default` may be called only once per file and cannot be combined with `export`; both raise `Carton::ExportError`. Put other names inside the default value.
+- Importing a file with no exports (a Bare Carton) returns a `Carton::Exports` of the constants and top-level helpers it defines, instead of its `Carton::Box`. Importers can no longer `eval`, `require`, or read `load_path` inside another Carton. Helpers are callable directly (`toolbox.helper`), lookups return their `Method` object (`toolbox.fetch(:helper).call`), and constants are read when the import finishes. `Carton::Box` is now a private constant.
+- Imports are shared across the process. Each Carton file loads once, and every later `import` or `import_relative` of it returns the same value, so sibling Cartons share classes and Carton state no longer resets per import. A Carton that imports itself raises `Carton::ImportError`.
+- `import 'name'` no longer checks the current directory before `$LOAD_PATH`, so results no longer depend on where the app was started. Use an absolute path, `import_relative`, or add the directory to `$LOAD_PATH`.
+- `Carton.with_bundle { require 'bundler/setup' }` is replaced by `Carton.setup_bundle`. Pass groups as with `Bundler.setup` (`Carton.setup_bundle(:default, :test)`) and choose a Gemfile with `gemfile:`. Bundler errors raise instead of exiting the process.
 
 ### Added
 
-- `import_relative` and absolute `import` accept a gem-shaped directory:
-  `import_relative 'components/billing'` loads
-  `components/billing/lib/billing.rb` with that `lib/` on the Carton's load
-  path.
-- `Carton::Error`, the base class of every error Carton raises itself, with
-  `Carton::ImportError` (circular imports, gem version mismatches) and
-  `Carton::ExportError` (repeated or conflicting exports). They replace plain
-  `RuntimeError`s and `ArgumentError`s, and are the same classes in every
-  Box. `Carton::GemfileNotFound` is now a `Carton::Error`.
-- `Carton.setup_bundle(*groups, gemfile: nil)` sets up a Carton's own bundle.
-  Without `gemfile:` it searches upward from the calling file for `gems.rb`
-  or `Gemfile`. It clears any stale `BUNDLE_LOCKFILE` and restores all of
-  `ENV` after setup, so a Carton's bundle variables never reach the rest of
-  the process. `Carton::GemfileNotFound` is raised when there is no Gemfile.
+- `import_relative` and absolute `import` accept a gem-shaped directory: `import_relative 'components/billing'` loads `components/billing/lib/billing.rb` with that `lib/` on the Carton's load path.
+- `Carton::Error`, the base class of every error Carton raises itself, with `Carton::ImportError` (circular imports, gem version mismatches) and `Carton::ExportError` (repeated or conflicting exports). They replace plain `RuntimeError`s and `ArgumentError`s, and are the same classes in every Box. `Carton::GemfileNotFound` is now a `Carton::Error`.
+- `Carton.setup_bundle(*groups, gemfile: nil)` sets up a Carton's own bundle. Without `gemfile:` it searches upward from the calling file for `gems.rb` or `Gemfile`. It clears any stale `BUNDLE_LOCKFILE` and restores all of `ENV` after setup, so a Carton's bundle variables never reach the rest of the process. `Carton::GemfileNotFound` is raised when there is no Gemfile.
 - Public RBS signatures in `sig/carton.rbs`.
-- `examples/monorepo`: packages as path gems in one Gemfile, imported by gem
-  name.
-- `examples/rails_in_main`: a Rails API app whose domain logic is a
-  Zeitwerk-loaded path-gem Carton.
-- `examples/rails_in_cartons`: Rails loaded once in a framework Carton, with
-  models and controllers spread across domain Cartons. The Main Box runs only
-  Rack.
-- `examples/master_prelude`: an optional, unsupported hack that loads Active
-  Support's core extensions into Ruby's Master Box so every Carton inherits
-  them.
+- `examples/monorepo`: packages as path gems in one Gemfile, imported by gem name.
+- `examples/rails_in_main`: a Rails API app whose domain logic is a Zeitwerk-loaded path-gem Carton.
+- `examples/rails_in_cartons`: Rails loaded once in a framework Carton, with models and controllers spread across domain Cartons. The Main Box runs only Rack.
+- `examples/master_prelude`: an optional, unsupported hack that loads Active Support's core extensions into Ruby's Master Box so every Carton inherits them.
 
 ### Changed
 
-- `export` and `export_default` only declare exports from the imported
-  Entrypoint. Under plain `require`, or in other files a Carton requires, they
-  validate their arguments and do nothing, so Carton-aware files and gems also
-  load with `require`.
-- Importing a file from an activated gem activates that gem and its runtime
-  dependencies in the Carton's Box at the caller's versions. When the caller
-  ran Bundler setup, the Box is also restricted to the caller's bundle: every
-  locked gem loads at its locked version, and gems outside the lockfile raise
-  `LoadError`.
-- `import`, `import_relative`, `export`, and `export_default` are private
-  Kernel methods, like `require`, so `"str".import(...)` raises
-  `NoMethodError` and objects no longer `respond_to?` them.
-- `import 'name'` resolves the feature in the caller's Box and carries only
-  the matching load-path entry into the imported Box, instead of copying the
-  caller's whole `$LOAD_PATH`.
-- `RUBY_BOX=1 bundle exec` works, including Gemfiles that evaluate a gemspec.
-  Carton no longer patches RubyGems or Bundler.
+- `export` and `export_default` only declare exports from the imported Entrypoint. Under plain `require`, or in other files a Carton requires, they validate their arguments and do nothing, so Carton-aware files and gems also load with `require`.
+- Importing a file from an activated gem activates that gem and its runtime dependencies in the Carton's Box at the caller's versions. When the caller ran Bundler setup, the Box is also restricted to the caller's bundle: every locked gem loads at its locked version, and gems outside the lockfile raise `LoadError`.
+- `import`, `import_relative`, `export`, and `export_default` are private Kernel methods, like `require`, so `"str".import(...)` raises `NoMethodError` and objects no longer `respond_to?` them.
+- `import 'name'` resolves the feature in the caller's Box and carries only the matching load-path entry into the imported Box, instead of copying the caller's whole `$LOAD_PATH`.
+- `RUBY_BOX=1 bundle exec` works, including Gemfiles that evaluate a gemspec. Carton no longer patches RubyGems or Bundler.
 
 ### Fixed
 
-- Importing without `RUBY_BOX=1` raises `Carton::ImportError` explaining how to
-  enable Boxes, instead of `NoMethodError` on `nil`.
-- A missing `import_relative` target raises `LoadError` instead of loading a
-  same-named feature from the load path (such as the stdlib `json`), and a
-  missing absolute `import` raises `LoadError` instead of `Errno::ENOENT`.
-- `export_default` keeps Hash, `nil`, and `false` values as Default Exports
-  instead of treating a Hash as an Export Namespace.
-- A gem Carton imported from another Carton's Box gets its dependencies.
-  Activation used to write to the importing Carton's `$LOAD_PATH`, so the
-  gem's `require` of a dependency raised `LoadError`.
-- A gem Carton's dependencies load at the caller's versions instead of the
-  newest installed ones. A later import whose caller has different versions
-  activated raises instead of reusing the cached Carton.
-- Bare Carton lookup only finds constants and helpers the Entrypoint defines.
-  Keys are no longer evaluated as Ruby expressions, and `key?` no longer calls
-  helpers.
-- Hash-rest patterns (`=> { **rest }`) return every Named Export, or every
-  member of a Bare Carton's Public Surface, instead of an empty hash.
+- Importing without `RUBY_BOX=1` raises `Carton::ImportError` explaining how to enable Boxes, instead of `NoMethodError` on `nil`.
+- A missing `import_relative` target raises `LoadError` instead of loading a same-named feature from the load path (such as the stdlib `json`), and a missing absolute `import` raises `LoadError` instead of `Errno::ENOENT`.
+- `export_default` keeps Hash, `nil`, and `false` values as Default Exports instead of treating a Hash as an Export Namespace.
+- A gem Carton imported from another Carton's Box gets its dependencies. Activation used to write to the importing Carton's `$LOAD_PATH`, so the gem's `require` of a dependency raised `LoadError`.
+- A gem Carton's dependencies load at the caller's versions instead of the newest installed ones. A later import whose caller has different versions activated raises instead of reusing the cached Carton.
+- Bare Carton lookup only finds constants and helpers the Entrypoint defines. Keys are no longer evaluated as Ruby expressions, and `key?` no longer calls helpers.
+- Hash-rest patterns (`=> { **rest }`) return every Named Export, or every member of a Bare Carton's Public Surface, instead of an empty hash.
 
 ## [0.1.0] - 2026-04-16
 
 Initial release.
 
-[Unreleased]: https://github.com/dtcristo/carton/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/dtcristo/carton/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/dtcristo/carton/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/dtcristo/carton/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/dtcristo/carton/releases/tag/v0.1.0

data/README.md

@@ -5,21 +5,42 @@
   </h1>
   <p>
     <strong>
-      Easily box your Ruby
+      Real boundaries for Ruby
     </strong>
   </p>
 </div>
 
-Split a Ruby app into gem-sized units that import and export like modules.
-Each Carton runs in its own
-[`Ruby::Box`](https://docs.ruby-lang.org/en/4.0/Ruby/Box.html), so:
+Ruby has gems to share code and Bundler to pick their versions, but nothing inside an app draws a boundary. Every file loads into one namespace: any code can reach any constant, a monkey patch applies everywhere, and one Gemfile fixes one version of each gem for the whole process. A boundary is a convention.
 
-- two parts of one app can use **different versions of the same gem**;
-- **monkey patches stay** in the Carton that makes them;
-- only what a Carton exports is reachable, so **boundaries hold at runtime**.
+Carton is the package system Ruby has been missing. Split code into Cartons that import and export like modules. Each Carton runs in its own [`Ruby::Box`](https://docs.ruby-lang.org/en/4.0/Ruby/Box.html), so Ruby enforces the boundary while the code runs:
 
-A Carton is shaped like a gem: `billing.rb` plus the `billing/` directory, with
-no manifest. A gem, a path gem, a directory, or a single file can be one.
+- other Cartons reach **only what a Carton exports**;
+- **monkey patches to builtin classes**, such as `String#blank?`, stay in the Carton that makes them;
+- two Cartons can use **different versions of the same gem**.
+
+A Carton is shaped like a gem: `billing.rb` plus the `billing/` directory, with no manifest. A gem, a path gem, a directory, or a single file can be one, and a Carton with a gemspec can leave the app as a published gem unchanged.
+
+A Box does not isolate everything. Classes and objects a Carton exports are shared, not copied, so reopening an exported class or changing a shared object affects every importer. A plain `require` of a Carton's files loads a second copy outside its boundary, which `carton check` reports. And each Carton loads once per process: its state lasts as long as the process, and its first importer fixes its gem versions.
+
+## Why Carton
+
+| | Bundler | [Packwerk](https://github.com/Shopify/packwerk) | Carton |
+| --- | --- | --- | --- |
+| Boundaries inside an app | No | Checked statically, in CI | Enforced at runtime, and checked statically by `carton check` |
+| Private internals | No | Privacy checks removed in 3.0 | Only exports cross; `private_constant` hides the rest |
+| Constants loaded dynamically | n/a | Not seen | Inside the boundary like any other |
+| Gem versions | One per app | One per app | One per Carton |
+| Monkey patches to builtins | Global | Global | Stay in their Carton |
+| Unit of distribution | A gem | A pack, which stays in the app | A gem-shaped Carton, which can become a gem |
+
+Static checks only see what they can parse. Packwerk's authors note that a package with zero violations "may actually crash with name errors when its code is executed" ([A Packwerk Retrospective](https://shopify.engineering/a-packwerk-retrospective)). A Carton's boundary is the Box it runs in, so what `carton check` reports ahead of time is also what Ruby enforces.
+
+## Where it fits today
+
+- **The domains of an app or a monorepo**, as tens of Cartons. See [examples/monorepo](examples/monorepo/README.md), and [examples/rails_in_main](examples/rails_in_main/README.md) for domain Cartons beside a Rails app in the Main Box.
+- **Plugin hosts whose plugins need conflicting gem versions**, which plain Ruby cannot load together; see [examples/plugins](examples/plugins/README.md).
+- **Rails inside Cartons** works but is experimental: there is no reloading yet, and domain Cartons see Active Support's core extensions only if they load them ([examples/rails_in_cartons](examples/rails_in_cartons/README.md)).
+- **Not yet file by file.** Each Carton costs about 60 ms and 2.4 MB ([performance.md](docs/performance.md)), most of it `Ruby::Box.new`, so aim for tens of Cartons, not hundreds.
 
 ## Quick start
 
@@ -29,8 +50,7 @@ Carton needs Ruby 4.0.7+ with Boxes enabled (`RUBY_BOX=1`). Install it:
 gem install carton   # or add `gem 'carton'` to your Gemfile
 ```
 
-A Carton's Entrypoint loads its own files and exports one value with
-`export_default`:
+A Carton's Entrypoint loads its own files and exports one value, usually its root module:
 
 ```
 billing.rb          # the Entrypoint
@@ -45,19 +65,10 @@ module Billing
   def self.invoice(total) = Invoice.new(total)
 end
 
-export_default Billing
+export Billing
 ```
 
-Or it exports several names with `export`. Capitalized Symbols name
-constants, other Symbols name methods, and keywords are plain values:
-
-```ruby
-# math.rb
-export def add(a, b) = a + b
-export PI: 3.14159
-```
-
-Import them:
+Import it:
 
 ```ruby
 # main.rb
@@ -65,22 +76,13 @@ require 'carton'
 
 Billing = import_relative 'billing'
 Billing.invoice(42)
-
-MathTools = import_relative 'math'
-MathTools.add(2, 3) # => 5
-MathTools::PI       # => 3.14159
 ```
 
 ```sh
 RUBY_BOX=1 ruby main.rb
 ```
 
-`import_relative 'billing/invoice'` raises `Carton::ImportError`: the file is
-inside the `billing` Carton, so only `billing` can be imported. `import 'name'`
-searches `$LOAD_PATH` like `require`, so gems and path gems import by name, and
-a gem-shaped directory (`components/billing/lib/billing.rb`) imports by its
-path. Each Carton loads once per process, and every later import returns the
-same value.
+`import_relative 'billing/invoice'` raises `Carton::ImportError`: the file is inside the `billing` Carton, so only `billing` can be imported. `import 'name'` searches `$LOAD_PATH` like `require`, so gems and path gems import by name, and a gem-shaped directory (`components/billing/lib/billing.rb`) imports by its path. Each Carton loads once per process, and every later import returns the same value.
 
 ## Gems and Bundler
 
@@ -92,22 +94,21 @@ Carton.setup_bundle # uses cartons/reports/Gemfile
 require 'bigdecimal'
 ```
 
-A gem in the app's bundle imports as a Carton and gets its dependencies at the
-app's locked versions. For a monorepo, make each package a path gem in one
-Gemfile and import it by name; see [examples/monorepo](examples/monorepo/README.md).
+A gem in the app's bundle imports as a Carton and gets its dependencies at the app's locked versions. For a monorepo, make each package a path gem in one Gemfile and import it by name; see [examples/monorepo](examples/monorepo/README.md).
+
+## Types and checks
+
+The `carton` command, in the [`carton-tools`](carton-tools/README.md) gem, reads code without running it; add `gem 'carton-tools', group: :development` beside `carton`. `carton rbs main.rb` writes RBS so [Steep](https://github.com/soutaro/steep) knows what each import returns, and `carton check main.rb` reports missing imports, cycles, `require` calls that reach into a Carton, and gems a gem Carton uses without declaring them. See [Types and checks](docs/usage.md#types-and-checks).
 
 ## Status
 
-Carton is experimental, and so is `Ruby::Box`. It targets Ruby 4.0.7+ and,
-with Bundler, Bundler 4.0.23+. Box is not a security boundary: it isolates
-definitions and load state, not objects. Classes a Carton defines are shared
-with every importer, so reopening one changes it everywhere; see
-[Sharing classes across Cartons](docs/usage.md#sharing-classes-across-cartons).
+Carton is experimental, and so is `Ruby::Box`. It targets Ruby 4.0.7+ and, with Bundler, Bundler 4.0.23+. Box is not a security boundary: it isolates definitions and load state, not objects. Classes a Carton defines are shared with every importer, so reopening one changes it everywhere; see [Sharing classes across Cartons](docs/usage.md#sharing-classes-across-cartons).
 
 ## Docs
 
-- [usage.md](docs/usage.md): exports, imports, Bundler, gem Cartons, and testing
+- [usage.md](docs/usage.md): exports, imports, Bundler, gem Cartons, testing, types, and checks
 - [design.md](docs/design.md): how an import runs
+- [performance.md](docs/performance.md): import time and memory as Cartons and bundles grow
 - [todo.md](docs/todo.md): planned work and open questions
 - [internals/](docs/internals/): how `Ruby::Box`, RubyGems, and Bundler work, and upstream plans
 - [CONTEXT.md](CONTEXT.md): the glossary
@@ -116,13 +117,16 @@ Examples, each runnable with `RUBY_BOX=1 ruby examples/<name>/main.rb`:
 
 | Example | Shows |
 | --- | --- |
-| [minimal](examples/minimal/README.md) | A Carton with its own directory, a single-file Carton, and the error for importing a file inside a Carton |
+| [minimal](examples/minimal/README.md) | A Carton with its own directory, a single-file Carton, the error for importing a file inside a Carton, and Steep types |
+| [monorepo](examples/monorepo/README.md) | Packages as path gems in one Gemfile, imported by gem name |
+| [rails_in_main](examples/rails_in_main/README.md) | Rails in the Main Box, domain logic in a Carton: the recommended way to use Carton with Rails |
+| [plugins](examples/plugins/README.md) | A plugin host whose plugins need incompatible `bigdecimal` versions, each with its own bundle, and a `Float` patch that stays in one plugin |
 | [gems](examples/gems/README.md) | Two Cartons using different `bigdecimal` versions without Bundler |
 | [bundler](examples/bundler/README.md) | Cartons with their own Bundler setup, plus a path gem |
-| [monorepo](examples/monorepo/README.md) | Packages as path gems in one Gemfile, imported by gem name |
-| [rails_in_main](examples/rails_in_main/README.md) | Rails in the Main Box, domain logic in a Carton |
-| [rails_in_cartons](examples/rails_in_cartons/README.md) | Rails loaded once in a Carton, models and controllers in domain Cartons |
-| [master_prelude](examples/master_prelude/README.md) | An unsupported hack that shares Active Support with every Carton |
+| [zeitwerk](examples/zeitwerk/README.md) | Zeitwerk loaders inside Cartons and in the app, eager loading, and what reloading a Carton does to importers |
+| [rails_in_cartons](examples/rails_in_cartons/README.md) | Experimental: Rails loaded once in a Carton, models and controllers in domain Cartons |
+
+**Experiments.** [master_prelude](examples/master_prelude/README.md) is an unsupported hack, not a pattern to copy. It loads Active Support once into Ruby's internal Master Box so every Carton starts with it, relying on Ruby behavior that Ruby's docs say does not happen.
 
 ## Development
 

data/lib/carton/activate_gems.rb

@@ -4,5 +4,5 @@
 # resolves to the Box of the file being loaded, so activating from a file
 # required here updates this Box even during a nested Import.
 Carton.const_get(:GemActivation).activate(
-  *Ruby::Box.current.__send__(:pending_gems),
+  *Carton.const_get(:Box).for(Ruby::Box.current).__send__(:pending_gems),
 )

data/lib/carton/box.rb

@@ -1,15 +1,32 @@
 # frozen_string_literal: true
 
 module Carton
-  class Box < Ruby::Box
+  # One Import's state, attached to the plain `Ruby::Box` it runs in. It wraps
+  # a `Ruby::Box` rather than subclassing it, because Ruby keeps autoloads in
+  # the Box that registered them only for a plain `Ruby::Box`. Code in any Box
+  # finds the Import from `Ruby::Box.current` with `Box.for`.
+  class Box
     ACTIVATE_GEMS = File.expand_path('activate_gems.rb', __dir__)
     private_constant :ACTIVATE_GEMS
+    LOADED_FEATURES = File.expand_path('loaded_features.rb', __dir__)
+    private_constant :LOADED_FEATURES
     ERRORS = %i[Error ImportError ExportError GemfileNotFound].freeze
     private_constant :ERRORS
+    IVAR = :@carton_import
+    private_constant :IVAR
+
+    NO_EXPORT = Object.new.freeze
+    private_constant :NO_EXPORT
+
+    # The Import running in `ruby_box`, or nil for the Main Box and Boxes
+    # Carton did not create.
+    def self.for(ruby_box) = ruby_box.instance_variable_get(IVAR)
 
     def initialize
-      super
-      reset_export_declaration
+      @box = Ruby::Box.new
+      @box.instance_variable_set(IVAR, self)
+      route_autoloads_through_kernel_require
+      reset_export
     end
 
     private
@@ -25,20 +42,50 @@ module Carton
         gems: target.gems || [],
         locked_gems: target.locked_gems,
       )
+      record_used_gems(target)
       export_public_surface(&build)
     end
 
+    # The gems this Carton depends on: its closure, plus the locked gems whose
+    # files it has loaded, such as an undeclared gem the caller's lockfile
+    # allows. A later importer must agree on these versions to share the
+    # Carton, so they are read again at each check, after any lazy requires.
+    def record_used_gems(target)
+      target.gem_usage = -> { used_gems(target) }
+    end
+
+    def used_gems(target)
+      gems = target.gems || []
+      locked = (target.locked_gems || []) - gems
+      return gems if locked.empty?
+
+      gems + GemActivation.owning(locked, loaded_features)
+    end
+
+    # `Ruby::Box#eval` does not switch the loading Box, so during a nested
+    # Import `$LOADED_FEATURES` there would be the importer's. A file loaded
+    # in this Box reads this Box's.
+    def loaded_features
+      @box.eval("load #{LOADED_FEATURES.inspect}")
+      features = @loaded_features
+      @loaded_features = nil
+      features
+    end
+
+    def receive_loaded_features(features)
+      @loaded_features = features
+    end
+
     # Fresh boxes copy Master, so they start without the caller's gems. Load
     # Carton's own entrypoint so the imported file gets `import`,
     # `import_relative`, and `export`. Nested imports reuse the caller's
     # process-wide import cache.
     def configure_for_import(entrypoint:, import_cache:)
       @import_cache = import_cache
-      reset_export_declaration
+      reset_export
       add_import_load_path(File.dirname(entrypoint))
       require_in_box(entrypoint)
       share_error_classes
-      snapshot_import_support
       self
     end
 
@@ -46,6 +93,9 @@ module Carton
     def load_import(feature, load_path: nil, gems: [], locked_gems: nil)
       activate_gems(gems, locked_gems) unless gems.empty?
       add_import_load_path(load_path) if load_path
+      # After activation, which loads Bundler and Psych here: a Bare
+      # Carton's surface is only what its Entrypoint adds.
+      snapshot_import_support
 
       @entrypoint = real_path(feature)
       result = require_in_box(feature)
@@ -55,8 +105,21 @@ module Carton
 
     attr_reader :import_cache, :pending_gems
 
+    # Ruby 4.0.7 loads an autoload registered in this Box with
+    # `Ruby::Box#require`, which skips the Box's `Kernel#require` and so any
+    # patch on it, such as Zeitwerk's (Bug #21830, fixed on Ruby master). Send
+    # it through `Kernel#require` in this Box instead.
+    def route_autoloads_through_kernel_require
+      box = @box
+      box.define_singleton_method(:require) do |path|
+        box.eval("require #{path.to_s.inspect}")
+      end
+    end
+
+    # `eval` rather than `Ruby::Box#require`, so the Box's own `Kernel#require`
+    # runs, including patches such as Zeitwerk's.
     def require_in_box(feature)
-      eval("require #{feature.inspect}")
+      @box.eval("require #{feature.inspect}")
     end
 
     # Box methods run in the Box that defined them, so this Box's own copy of
@@ -75,7 +138,7 @@ module Carton
     # Point them at the importer's classes, so one rescue catches errors
     # raised in any Carton.
     def share_error_classes
-      carton = const_get(:Carton, false)
+      carton = @box.const_get(:Carton, false)
       ERRORS.each do |name|
         carton.__send__(:remove_const, name)
         carton.const_set(name, Carton.const_get(name, false))
@@ -83,6 +146,7 @@ module Carton
     end
 
     def add_import_load_path(path)
+      load_path = @box.load_path
       load_path.unshift(path) unless load_path.include?(path)
     end
 
@@ -98,43 +162,46 @@ module Carton
       File.realpath(path)
     end
 
-    def declare_export(methods, values)
-      @export_declaration = @export_declaration.add(methods, values)
-    end
+    def declare_export(value)
+      unless NO_EXPORT.equal?(@export)
+        raise ExportError, 'export may be called only once per Entrypoint'
+      end
 
-    def declare_default(value)
-      @export_declaration = @export_declaration.default(value)
+      @export = value
     end
 
-    # A Bare Carton's surface is the constants and top-level helpers its
-    # Entrypoint defined, so importers never receive the Box itself.
-    def export_public_surface(&)
-      @export_declaration.public_surface(bare: method(:bare_surface), &)
+    # The exported value, or for a Bare Carton the constants and top-level
+    # helpers its Entrypoint defined, which `build` wraps, so importers never
+    # receive the Box itself.
+    def export_public_surface
+      NO_EXPORT.equal?(@export) ? yield(*bare_surface) : @export
     end
 
     def bare_surface
       constants =
-        @public_constant_names.to_h { |name| [name, const_get(name, false)] }
+        @public_constant_names.to_h do |name|
+          [name, @box.const_get(name, false)]
+        end
       [@public_method_entries, constants]
     end
 
-    def reset_export_declaration
-      @export_declaration = ExportDeclaration.absent
+    def reset_export
+      @export = NO_EXPORT
     end
 
     def snapshot_import_support
-      @import_constant_names = constants(false).map(&:to_s)
+      @import_constant_names = @box.constants(false).map(&:to_s)
       @import_method_names = top_level_methods.keys
     end
 
     def discover_public_entries
       @public_constant_names =
-        constants(false).map(&:to_s) - @import_constant_names
+        @box.constants(false).map(&:to_s) - @import_constant_names
       @public_method_entries = top_level_methods.except(*@import_method_names)
     end
 
     def top_level_methods
-      eval(
+      @box.eval(
         'Object.private_instance_methods(false).to_h { |name| [name.to_s, method(name)] }',
       )
     end

data/lib/carton/error.rb

@@ -12,8 +12,9 @@ module Carton
   class ImportError < Error
   end
 
-  # An Export Declaration that breaks the rules: a name exported twice,
-  # `export_default` called twice, or both forms in one Entrypoint.
+  # An `export` that breaks the rules: called twice in one Entrypoint, given
+  # a Symbol, or a Bare Carton helper that would hide a `Carton::Namespace`
+  # method.
   class ExportError < Error
   end