carton 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3d0c8755a90c3eb40d7ee29a16a174a89f1c678e43ba08275fab4502b298fae
-  data.tar.gz: 582512d0d84c6e3dfa2b49c9d95b5e77e4fac4a25a45b63b17bf9ed6087d65c1
+  metadata.gz: bed12e1aae3d8c17c74727a84d09d04ace52545dde9320ca3d5bdf39661c7a93
+  data.tar.gz: 57207a6c9c8704239b023dc0b861a4c35ead18f43b7a593c70674712d6dcf084
 SHA512:
-  metadata.gz: f48e9cdd2c5c64d12f323de0acc65498f7e0c0aa7f230decdf5fae538337e268c07686e9f2b5017b4d38dd1b4c22bb2120bc5c54b5ce6884f59d7b319779b0e5
-  data.tar.gz: 1470bb044aaacf574535228f1bc9f12a84f0654651c3fbaa52fe52bcde0f215c9262eb0d603c6cc98239c29f4f44854b07534ff608af0bc206e701f2498f1cc0
+  metadata.gz: c583efac379f57cdd89a500fee73327dab3bfd1130c7d738556077a0484a67b444d721fbb7442b5325da47a5b88a22cd907697bf132b1fb5e13fdafccb34fe84
+  data.tar.gz: ccfd7ce8ea6a5693f391c7e2533a0313e9e717755ae10576543dbd112a8785a0439e171402c80242e1abd6841e1dae9f0c45ba41c31872aae70759f8a31ad6d6

data/CHANGELOG.md

@@ -2,9 +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.
+
+### 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.
+
+### 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.
+- 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.
+
+### 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.
+
+### 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.
+
 ## [0.1.0] - 2026-04-16
 
 Initial release.
 
-[Unreleased]: https://github.com/dtcristo/carton/compare/v0.1.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

@@ -1,65 +1,141 @@
 <div align="center">
+  <img src="images/carton.png" alt="Carton logo" width="200" />
   <h1>
     Carton
   </h1>
-  <img src="images/carton.png" alt="Carton logo" width="200" />
   <p>
     <strong>
-      Easily box your Ruby
+      Real boundaries for Ruby
     </strong>
   </p>
 </div>
 
-Carton is a thin wrapper around [`Ruby::Box`](https://docs.ruby-lang.org/en/4.0/Ruby/Box.html) for safe, ergonomic modularization in Ruby 4+. It gives you imports and exports that feel like ES Modules while still reading like Ruby. Each carton can isolate constants, gems, and monkey patches behind a small public API, so large apps can keep clear boundaries.
+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.
+
+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:
+
+- 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
+
+Carton needs Ruby 4.0.7+ with Boxes enabled (`RUBY_BOX=1`). Install it:
+
+```sh
+gem install carton   # or add `gem 'carton'` to your Gemfile
+```
+
+A Carton's Entrypoint loads its own files and exports one value, usually its root module:
 
-## Minimal usage
+```
+billing.rb          # the Entrypoint
+billing/invoice.rb  # inside the Carton
+```
 
 ```ruby
-# user.rb
-class User
-  def initialize(name) = @name = name
+# billing.rb
+require_relative 'billing/invoice'
+
+module Billing
+  def self.invoice(total) = Invoice.new(total)
 end
 
-export_default User
+export Billing
 ```
 
+Import it:
+
 ```ruby
 # main.rb
 require 'carton'
 
-User = import_relative 'user'
-alice = User.new('Alice')
+Billing = import_relative 'billing'
+Billing.invoice(42)
 ```
 
-Named exports return a namespace-like module:
+```sh
+RUBY_BOX=1 ruby main.rb
+```
 
-```ruby
-# math.rb
-def add(a, b) = a + b
+`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.
 
-export PI: 3.14159, add: method(:add)
-```
+## Gems and Bundler
+
+A Carton can set up its own bundle, isolated from the app's:
 
 ```ruby
-MathTools = import_relative 'math'
-MathTools::PI
-MathTools.add(2, 3)
+# cartons/reports/lib/reports.rb
+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).
+
+## 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).
+
 ## Docs
 
-- [USAGE.md](USAGE.md) - detailed import/export, load path, and Bundler usage
-- [DESIGN.md](DESIGN.md) - implementation overview and constraints
-- [TODO.md](TODO.md) - future improvements and Bundler upstream ideas
-- [examples/minimal/README.md](examples/minimal/README.md) - smallest example
-- [examples/complex/README.md](examples/complex/README.md) - multi-carton example
+- [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
+
+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, 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 |
+| [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
 
 ```sh
-bundle install                        # Install development deps
-RUBY_BOX=1 bundle exec rake           # Run all tests and examples
-bundle exec rake format               # Format code
+bundle install
+bundle exec rake                  # tests, RuboCop, and every example
+bundle exec rake test             # tests only
+bundle exec rake example:monorepo # one example
+bundle exec rake format           # format with Syntax Tree
 ```
 
 ## License

data/lib/carton/activate_gems.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Required inside a Carton Box by `Carton::Box#activate_gems`. `$LOAD_PATH`
+# 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(
+  *Carton.const_get(:Box).for(Ruby::Box.current).__send__(:pending_gems),
+)

data/lib/carton/box.rb

@@ -1,115 +1,209 @@
 # frozen_string_literal: true
 
 module Carton
-  class Box < Ruby::Box
-    include ExportMethods
-
-    UNSET_EXPORT = Object.new.freeze
-    private_constant :UNSET_EXPORT
+  # 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
+      @box = Ruby::Box.new
+      @box.instance_variable_set(IVAR, self)
+      route_autoloads_through_kernel_require
       reset_export
     end
 
     private
 
-    def configure_for_import(parent_box:, entrypoint:, bundle_gemfile:)
-      inherit_load_path(parent_box)
+    # The whole Import lifecycle, in order: boot Carton in this Box, load the
+    # target, then build its public surface with `build`. Runtime calls only
+    # this, so the ordering lives here.
+    def import_target(target, carton_entrypoint:, import_cache:, &build)
+      configure_for_import(entrypoint: carton_entrypoint, import_cache:)
+      load_import(
+        target.feature,
+        load_path: target.load_path,
+        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
+      add_import_load_path(File.dirname(entrypoint))
       require_in_box(entrypoint)
-      set_bundle_gemfile(bundle_gemfile)
+      share_error_classes
       self
     end
 
-    def require_in_box(feature)
-      eval("require #{feature.inspect}")
-    end
+    # Activate the caller's gems for the target, then load it inside the box.
+    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
 
-    def resolve_feature_path_in_box(feature)
-      eval("$LOAD_PATH.resolve_feature_path(#{feature.inspect})")
+      @entrypoint = real_path(feature)
+      result = require_in_box(feature)
+      discover_public_entries
+      result
     end
 
-    def activate_bundle_if_configured
-      gemfile = ENV['BUNDLE_GEMFILE']
-      return unless gemfile && File.file?(gemfile)
-
-      require_in_box('bundler/setup')
-    end
+    attr_reader :import_cache, :pending_gems
 
-    def set_export(value)
-      if export_set?
-        raise RuntimeError, 'only one export is allowed per imported file'
+    # 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
-
-      @export = value
     end
 
-    def export_set?
-      !@export.equal?(UNSET_EXPORT)
+    # `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)
+      @box.eval("require #{feature.inspect}")
+    end
+
+    # Box methods run in the Box that defined them, so this Box's own copy of
+    # Carton activates gems in this Box's RubyGems. `$LOAD_PATH` resolves to
+    # the Box of the file being loaded, which during a nested Import is the
+    # importing Carton, so activation runs from a file required here.
+    def activate_gems(gems, locked_gems)
+      @pending_gems = [gems, locked_gems]
+      require_in_box(ACTIVATE_GEMS)
+    ensure
+      @pending_gems = nil
+    end
+
+    # This Box just loaded its own copy of Carton, whose error classes are new
+    # objects that `rescue Carton::Error` in another Box would never match.
+    # Point them at the importer's classes, so one rescue catches errors
+    # raised in any Carton.
+    def share_error_classes
+      carton = @box.const_get(:Carton, false)
+      ERRORS.each do |name|
+        carton.__send__(:remove_const, name)
+        carton.const_set(name, Carton.const_get(name, false))
+      end
     end
 
-    def export_value
-      @export
+    def add_import_load_path(path)
+      load_path = @box.load_path
+      load_path.unshift(path) unless load_path.include?(path)
     end
 
-    def reset_export
-      @export = UNSET_EXPORT
+    # Only the imported Entrypoint declares this Carton's exports. Other files
+    # it requires may call `export` for their own imports; here it is inert.
+    def entrypoint?(file)
+      !@entrypoint.nil? && real_path(file) == @entrypoint
     end
 
-    def set_bundle_gemfile(path)
-      return unless path
+    def real_path(path)
+      return unless path && File.absolute_path?(path) && File.file?(path)
 
-      eval("ENV['BUNDLE_GEMFILE'] = #{path.inspect}")
+      File.realpath(path)
     end
 
-    def inherit_load_path(source_box)
-      return self unless source_box.respond_to?(:load_path)
-
-      source_box.load_path.each do |path|
-        next unless inherit_path?(path)
-
-        load_path << path unless load_path.include?(path)
+    def declare_export(value)
+      unless NO_EXPORT.equal?(@export)
+        raise ExportError, 'export may be called only once per Entrypoint'
       end
 
-      self
+      @export = value
     end
 
-    def inherit_path?(path)
-      expanded = File.expand_path(path)
-      !gem_path?(expanded)
+    # 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 gem_path?(path)
-      gem_roots = Gem.path.map { |root| File.expand_path(root) }
-      gem_roots.any? { |root| path == root || path.start_with?("#{root}/") } ||
-        path.include?('/vendor/bundle/') || path.include?('/bundler/gems/')
+    def bare_surface
+      constants =
+        @public_constant_names.to_h do |name|
+          [name, @box.const_get(name, false)]
+        end
+      [@public_method_entries, constants]
     end
 
-    def lookup_entry(key)
-      name = key.to_s
+    def reset_export
+      @export = NO_EXPORT
+    end
 
-      if name.match?(/\A[A-Z]/)
-        lookup_constant_entry(name)
-      else
-        lookup_method_entry(name)
-      end
+    def snapshot_import_support
+      @import_constant_names = @box.constants(false).map(&:to_s)
+      @import_method_names = top_level_methods.keys
     end
 
-    def lookup_constant_entry(name)
-      [true, const_get(name)]
-    rescue NameError
-      [false, nil]
+    def discover_public_entries
+      @public_constant_names =
+        @box.constants(false).map(&:to_s) - @import_constant_names
+      @public_method_entries = top_level_methods.except(*@import_method_names)
     end
 
-    def lookup_method_entry(name)
-      [true, eval(name)]
-    rescue NameError, NoMethodError
-      begin
-        [true, __send__(name)]
-      rescue NoMethodError
-        [false, nil]
-      end
+    def top_level_methods
+      @box.eval(
+        'Object.private_instance_methods(false).to_h { |name| [name.to_s, method(name)] }',
+      )
     end
   end
 end