carton 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bed12e1aae3d8c17c74727a84d09d04ace52545dde9320ca3d5bdf39661c7a93
-  data.tar.gz: 57207a6c9c8704239b023dc0b861a4c35ead18f43b7a593c70674712d6dcf084
+  metadata.gz: 3e0007f7095e824c2b3bc501b140288cde630695d7c56ae96c1a2f4a968c5196
+  data.tar.gz: 301c877d0c63eda3b26b18f6076097b0d8d746d7a1a0228adf7a5d13d173e9c5
 SHA512:
-  metadata.gz: c583efac379f57cdd89a500fee73327dab3bfd1130c7d738556077a0484a67b444d721fbb7442b5325da47a5b88a22cd907697bf132b1fb5e13fdafccb34fe84
-  data.tar.gz: ccfd7ce8ea6a5693f391c7e2533a0313e9e717755ae10576543dbd112a8785a0439e171402c80242e1abd6841e1dae9f0c45ba41c31872aae70759f8a31ad6d6
+  metadata.gz: d3fe870cdb0bcc2ee87f9ca951abfff7c807b9847330605d25762b8be1a012952ee1c55769eefef694d2b1c52e156c4a74ef1b1640431b304ce541e5ae720b45
+  data.tar.gz: 693fcc780bf07ccbd8c85dd7e20919bb7d3cf8ab7fefbbf0f91aa990a835e0e34a3842cf8ef23c80fd9b6ad0364536be1333f5d06ae56b8d1c11b1796cef1c4b

data/CHANGELOG.md

@@ -2,100 +2,147 @@
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-22
+
+Every imported Entrypoint now requires an explicit Export; Bare Cartons and `Carton::Namespace` are removed. `carton check` adds unused import and shared-object reopening warnings plus JSON reports. The Rails and Hanami examples share a Customers and Billing workflow, and Bundler support starts at 4.0.20 (#71, #79, #82, #83, #93, #100, #107).
+
+### Breaking
+
+- Every imported Entrypoint must call `export` exactly once; an import with no Export raises `Carton::ExportError` after loading. Removed Bare Cartons and `Carton::Namespace`; adapt legacy files and gems with a distinct Entrypoint that requires them and explicitly exports the chosen value. Imports still return that value exactly, including `nil` and `false`, and plain `require` keeps working (#107).
+
+### Added
+
+- `examples/hanami_in_cartons` implements the Rails examples' Customers/Billing workflow with Hanami slices, Dry contracts, types and operations, ROM SQLite repos, HTML/JSON responses, and a CLI bridge. Tests cover lazy/eager loading, Box ownership, persistence across processes, and Puma HTTP (#93).
+- `carton check` warns about unused import bindings and class/module definitions that open imported shared objects, and `--format json` reports problems and counts for CI and editors. This recovers the applicable parts of the stranded static-checks work; its unused Named Export check is obsolete under the single-value Export model (#54, #82).
+- An experimental Rails-in-Cartons reloading spike rebuilds changed domain Cartons and their Importers in a scratch copy, explicitly refreshes a retained Rails host's domain references and registered classes, and verifies requests after two reloads without losing records. It adds no runtime reload interface (#67).
+- `examples/exports` demonstrates Hash and callable exports, an explicit adapter for legacy Ruby, and Ruby pattern matching without gems or Bundler. The plugin testing recipe is now a runnable test with its own bundle (#64, #107).
+- `examples/dependency_injection`: a checkout Carton receives order storage, payments, and logging from its host through constructor arguments. File-backed demo adapters stay in Main, and integration tests import the Carton with fakes (#63).
+
+### Changed
+
+- The Hanami example's Framework, Customers, Billing, and Shop are gem-shaped components under `components/`, matching the Rails example, and import each other with `import 'name'` instead of `import_relative`. Both example guides show the framework and customers Entrypoints above billing and shop (#103).
+- Renamed the Rails and Hanami example directories to `examples/rails` and `examples/hanami`, with matching Rake tasks and updated fixture paths. Their existing docs URLs still work (#100).
+
+- Aligned the homepage, share previews, README, docs, and gem descriptions around explicit imports and exports, separate dependencies, and runtime boundaries. The homepage introduction is centred and its page title no longer repeats the project name (#98).
+- The website has three sections, Start here, Guides, and Reference, and the sidebar shows only the current one. Each example's guide moved from its README to a website page that shows its code from the repository. The reference is now API docs in YARD's shape, tested against `sig/carton.rbs`, with a page per `carton` command tested against its usage (#90).
+- Renamed the Rails-in-Main example to `rails_with_carton_domain` and aligned both Rails examples around Customers and Billing: domain-owned registration, validation, exact invoice pricing, and persistence through injected repositories. The conventional app keeps Rails adapters in Main; the Engine app owns them in its domain Cartons. Removed the unrelated jobs, updated the private reload fixture, and placed both examples together in the docs (#83).
+
+- Expanded Rails-in-Main into a conventional Rails app with migrations, HTML/JSON responses, an Active Job, standard CLI commands, and isolated Billing integration tests (#80, #81).
+
+- The Rails-in-Cartons example uses isolated Rails Engines with domain-owned loaders, migrations, HTML views, GlobalID jobs, and an explicit Rails CLI bridge (#79).
+
+- The website is now the only user guide and reference: `docs/usage.md` is gone, its remaining details moved to the website, which adds Examples and Rails pages, and the website's Status page is the only place that tracks readiness (#77).
+- Moved the unsupported Master prelude and private Rails reloading experiments into `spikes/`, with dedicated tasks and CI coverage; both Rails examples remain in `examples/`. The reloading spike reuses the Rails-in-Cartons app as a read-only fixture (#76).
+
+- Bundler support now starts at 4.0.20, the first release with the gemspec evaluation fix Carton needs inside Boxes. CI and the example bundles use that minimum (#71).
+- `examples/monorepo` keeps its Cartons under `cartons/` instead of `packages/` (#65).
+- `CONTEXT.md` groups the glossary and adds Interior, Gem-shaped Directory, Root Box, User Box, Carton Box, Template Box, Importer, First Importer, Second Copy, Dynamic Import, Helper, Gem Closure, Carton Bundle, and Undeclared Gem. The docs, comments, and `carton-tools` internals use these terms (#65).
+- `docs/internals/root-box-vs-main-box.md` is now `docs/internals/box-names.md`, which records upstream Ruby's Box names and how they were chosen (#65).
+- The examples guide explains each example's purpose and setup. The minimal app now contains only working Imports, with intentional violations in a separate file for static checks. The guides and comments follow `CONTEXT.md`, including Interior, Public Surface, Importer, Carton Bundle, and Helper. The Rails guides share restart guidance, and Bundler and Zeitwerk examples use clearer labels and names (#64).
+
+### Removed
+
+- Removed `examples/rails_with_carton_domain` and its guide, leaving one Rails example with domain-owned Engines (#100).
+
+### Fixed
+
+- Sample path gems declare and require Carton instead of relying on the host to preload it; the monorepo's leaf gems also work with ordinary `require` without Boxes enabled. The Rails shop gem includes its database configuration. Example docs distinguish bundle installation from activation and correct the undeclared-import demonstration and Rails class-sharing explanation (#64).
+
 ## [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.
+`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 (#41, #48, #58, #59).
 
 ### 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.
+- `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` (#59).
+- `Carton::Exports` is renamed `Carton::Namespace`, and only Bare Cartons return it (#59).
 
 ### 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.
+- 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 (#41, #58).
+- `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 (#53).
+- `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`) (#53, #59).
+- `bench/scale.rb` (`rake bench`) measures import time and memory as Cartons and bundles grow; [docs/performance.md](docs/performance.md) has the results (#50).
+- `Carton::Namespace#keys` and `#to_h`, and a readable `inspect`: `#<Carton::Namespace add, PI>` (#43, #59).
+- `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 (#45).
+- `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 (#41, #59).
+- `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 (#41, #59).
+- `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 (#42).
+- `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` (#44).
+- `examples/rails_in_cartons` declares the `logger` dependency its `shop` Carton requires (#42).
+- `sig/carton.rbs` declares `Carton::NamespaceMethods`, which `Carton::Namespace` includes (#41, #59).
+- The minimal example type-checks with Steep (#41).
+- `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 (#60).
+- `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 (#46).
 
 ### 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.
+- 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 (#56, #57, #59).
+- 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 (#43).
+- 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 (#43).
+- 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 (#47).
 
 ### 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.
+- 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 (#55).
+- `carton check` no longer reports `export` calls in different branches of one `if`, `unless`, or `case` as duplicates, since only one branch runs (#53).
+- 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 (#52).
+- A Bare Carton imported from a gem no longer exposes `Bundler`, `Psych`, `Date`, or `DateTime`, which Carton's gem activation loaded into its Box (#52).
+- A gem Carton's default-gem dependencies, such as `json` and `date`, keep the importer's activated version when a newer one is installed (#52).
+- 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 (#52).
+- 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 (#48).
 
 ## [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 (#9, #10, #11, #14, #15, #17, #18, #19, #20, #36).
 
 ### 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 (#36).
+- Carton now requires Ruby 4.0.7 or later, enforced by the gemspec, and Bundler support needs Bundler 4.0.23 or later (#11).
+- `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` (#9, #19).
+- 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 (#9).
+- `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 (#20).
+- 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 (#17).
+- 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` (#10).
+- `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` (#13).
+- `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 (#11).
 
 ### 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.
+- `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 (#36).
+- `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` (#35).
+- `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 (#11, #12).
+- Public RBS signatures in `sig/carton.rbs` ([0b7d16c](https://github.com/dtcristo/carton/commit/0b7d16c6e251931759edbc65f518b11377635f5d)).
+- `examples/monorepo`: packages as path gems in one Gemfile, imported by gem name (#33).
+- `examples/rails_in_main`: a Rails API app whose domain logic is a Zeitwerk-loaded path-gem Carton (#21, #23).
+- `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 (#22, #23).
+- `examples/master_prelude`: an optional, unsupported hack that loads Active Support's core extensions into Ruby's Master Box so every Carton inherits them (#24).
 
 ### 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` (#18).
+- 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` (#14, #15).
+- `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 (#8).
+- `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` ([110dfb6](https://github.com/dtcristo/carton/commit/110dfb68c7488e2e32de3e71c01fcecccbc893f8)).
+- `RUBY_BOX=1 bundle exec` works, including Gemfiles that evaluate a gemspec. Carton no longer patches RubyGems or Bundler (#11).
 
 ### 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` (#35).
+- 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` (#30).
+- `export_default` keeps Hash, `nil`, and `false` values as Default Exports instead of treating a Hash as an Export Namespace (#4).
+- 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` (#15).
+- 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 (#14).
+- 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 (#5).
+- Hash-rest patterns (`=> { **rest }`) return every Named Export, or every member of a Bare Carton's Public Surface, instead of an empty hash (#6).
 
 ## [0.1.0] - 2026-04-16
 
-Initial release.
+Initial release ([9925397](https://github.com/dtcristo/carton/commit/99253978dd73b70698341d04314e3ccf86b37c16)).
 
-[Unreleased]: https://github.com/dtcristo/carton/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/dtcristo/carton/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/dtcristo/carton/compare/v0.3.0...v0.4.0
 [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

@@ -10,132 +10,77 @@
   </p>
 </div>
 
-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:
+Split your app into Cartons with explicit imports and exports. Each has its own dependencies and runs in a separate [`Ruby::Box`](https://docs.ruby-lang.org/en/4.0/Ruby/Box.html), so Ruby enforces the boundaries at runtime:
 
 - other Cartons reach **only what a Carton exports**;
-- **monkey patches to builtin classes**, such as `String#blank?`, stay in the Carton that makes them;
+- **monkey patches to builtin classes** 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
+Every imported Entrypoint must call `export` exactly once. Loading without an Export raises `Carton::ExportError`; importing returns the exported value itself.
 
-- **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.
+A Carton is shaped like a gem: `billing.rb` plus the `billing/` directory beside it. There is no manifest, and with a gemspec a Carton can leave the app as a gem.
 
 ## Quick start
 
-Carton needs Ruby 4.0.7+ with Boxes enabled (`RUBY_BOX=1`). Install it:
+Carton needs Ruby 4.0.7+ with Boxes enabled (`RUBY_BOX=1`).
 
 ```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:
+```ruby
+# tax.rb: the tax Carton
+module Tax
+  def self.on(total) = total / 10
+end
 
-```
-billing.rb          # the Entrypoint
-billing/invoice.rb  # inside the Carton
+export Tax # the one value importers get
 ```
 
 ```ruby
-# billing.rb
-require_relative 'billing/invoice'
+# billing.rb: the billing Carton
+Tax = import_relative 'tax' # billing's import, invisible to importers
 
 module Billing
-  def self.invoice(total) = Invoice.new(total)
+  def self.invoice(total) = total + Tax.on(total)
 end
 
 export Billing
 ```
 
-Import it:
-
 ```ruby
 # main.rb
 require 'carton'
 
 Billing = import_relative 'billing'
-Billing.invoice(42)
+Billing.invoice(100) # => 110
+Tax                  # NameError: billing's import
 ```
 
 ```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.
-
-## Gems and Bundler
-
-A Carton can set up its own bundle, isolated from the app's:
-
-```ruby
-# 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).
+Carton is experimental, and so is `Ruby::Box`. Box isolates definitions and load state, not objects, so it is not a security boundary, and classes a Carton exports are shared with every importer. [Why Carton](https://carton.dtcristo.com/start/why-carton/) compares it with Bundler and Packwerk and covers where it fits today.
 
 ## Docs
 
-- [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
+Guides and reference live at [carton.dtcristo.com](https://carton.dtcristo.com) (source in [website/](website/README.md)). For contributors:
 
-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 |
+- [design.md](docs/design.md), [performance.md](docs/performance.md), [todo.md](docs/todo.md), and [internals/](docs/internals/)
+- [CONTEXT.md](CONTEXT.md): the glossary
+- [Examples](https://carton.dtcristo.com/guides/examples/): runnable apps, starting with [minimal](https://carton.dtcristo.com/guides/examples/minimal/); run one with `bundle exec rake example:<name>`
 
-**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.
+The `carton` command, for RBS and boundary checks, is in the [`carton-tools`](carton-tools/README.md) gem.
 
 ## Development
 
 ```sh
 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
+bundle exec rake        # tests, RuboCop, and every example
+bundle exec rake format # format with Syntax Tree
 ```
 
 ## License

data/lib/carton/box.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 module Carton
-  # 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`.
+  # A Carton 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
@@ -32,10 +33,10 @@ module Carton
     private
 
     # 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:)
+    # target, then return its Export. Runtime calls only this, so the ordering
+    # lives here.
+    def import_target(target, library:, import_cache:)
+      configure_for_import(library:, import_cache:)
       load_import(
         target.feature,
         load_path: target.load_path,
@@ -43,13 +44,14 @@ module Carton
         locked_gems: target.locked_gems,
       )
       record_used_gems(target)
-      export_public_surface(&build)
+      exported_value
     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.
+    # The gems this Carton depends on: its Gem Closure, plus the locked gems
+    # whose files it has loaded, such as an Undeclared Gem the Importer'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
@@ -63,7 +65,7 @@ module Carton
     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
+    # 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}")
@@ -76,31 +78,25 @@ module Carton
       @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
+    # New Boxes copy Master, so they start without the Importer's gems. Load
+    # Carton's own library so the imported file gets `import`,
+    # `import_relative`, and `export`. Nested imports reuse the Importer's
     # process-wide import cache.
-    def configure_for_import(entrypoint:, import_cache:)
+    def configure_for_import(library:, import_cache:)
       @import_cache = import_cache
       reset_export
-      add_import_load_path(File.dirname(entrypoint))
-      require_in_box(entrypoint)
+      add_import_load_path(File.dirname(library))
+      require_in_box(library)
       share_error_classes
       self
     end
 
-    # Activate the caller's gems for the target, then load it inside the box.
+    # Activate the Importer's gems for the target, then load it in this 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
-
       @entrypoint = real_path(feature)
-      result = require_in_box(feature)
-      discover_public_entries
-      result
+      require_in_box(feature)
     end
 
     attr_reader :import_cache, :pending_gems
@@ -125,7 +121,7 @@ module Carton
     # 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.
+    # Importer, so activation runs from a file required here.
     def activate_gems(gems, locked_gems)
       @pending_gems = [gems, locked_gems]
       require_in_box(ACTIVATE_GEMS)
@@ -135,7 +131,7 @@ module Carton
 
     # 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
+    # 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)
@@ -150,7 +146,7 @@ module Carton
       load_path.unshift(path) unless load_path.include?(path)
     end
 
-    # Only the imported Entrypoint declares this Carton's exports. Other files
+    # Only the imported Entrypoint declares this Carton's Export. Other files
     # it requires may call `export` for their own imports; here it is inert.
     def entrypoint?(file)
       !@entrypoint.nil? && real_path(file) == @entrypoint
@@ -170,40 +166,18 @@ module Carton
       @export = value
     end
 
-    # 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
+    # Every Entrypoint deliberately chooses the value its Importers receive.
+    def exported_value
+      if NO_EXPORT.equal?(@export)
+        raise ExportError,
+              "#{@entrypoint} must call export: export a module or another value"
+      end
 
-    def bare_surface
-      constants =
-        @public_constant_names.to_h do |name|
-          [name, @box.const_get(name, false)]
-        end
-      [@public_method_entries, constants]
+      @export
     end
 
     def reset_export
       @export = NO_EXPORT
     end
-
-    def snapshot_import_support
-      @import_constant_names = @box.constants(false).map(&:to_s)
-      @import_method_names = top_level_methods.keys
-    end
-
-    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 top_level_methods
-      @box.eval(
-        'Object.private_instance_methods(false).to_h { |name| [name.to_s, method(name)] }',
-      )
-    end
   end
 end

data/lib/carton/bundler.rb

@@ -2,7 +2,7 @@
 
 module Carton
   class << self
-    # Set up the current carton's bundle, like `Bundler.setup(*groups)`.
+    # Set up the current Carton's bundle, like `Bundler.setup(*groups)`.
     #
     # Bundler finds its Gemfile through process-global `ENV["BUNDLE_GEMFILE"]`
     # or the real process cwd. Carton resolves the Gemfile from the calling

data/lib/carton/error.rb

@@ -8,13 +8,12 @@ module Carton
   end
 
   # An Import that cannot go ahead: Boxes are disabled, a Carton imports
-  # itself, or a cached Carton was built against other gem versions.
+  # itself, or a shared Carton was built against other gem versions.
   class ImportError < Error
   end
 
-  # 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.
+  # An Entrypoint finished without exporting, called `export` twice, or
+  # gave it a Symbol.
   class ExportError < Error
   end
 

data/lib/carton/gem_activation.rb

@@ -1,23 +1,24 @@
 # frozen_string_literal: true
 
 module Carton
-  # Carries the caller's activated gems into a Carton Box.
+  # Carries the Importer's activated gems into a Carton Box.
   #
   # Optional Boxes copy Master, so they start with clean RubyGems state and
   # would auto-activate the newest installed version of any dependency. When
   # an Import resolves inside an activated gem, Carton activates that gem and
-  # its runtime dependencies in the new Box at the caller's versions, so the
-  # caller's lockfile (or plain `gem` calls) decides what the Carton sees.
+  # its runtime dependencies in the new Box at the Importer's versions, so the
+  # Importer's lockfile (or plain `gem` calls) decides what the Carton sees.
   #
-  # When the caller ran Bundler setup, the Box is also restricted to the
-  # caller's locked gems, as `Bundler.setup` restricts Main: every locked gem
+  # When the Importer ran Bundler setup, the Box is also restricted to the
+  # Importer's locked gems, as `Bundler.setup` restricts Main: every locked gem
   # is activated at its locked version and anything else fails to load.
   module GemActivation
     module_function
 
-    # The gem in `loaded_specs` that owns `feature`, plus its activated
-    # runtime dependencies, dependencies first. Default gems count: a new Box
-    # would otherwise load the newest installed version, not the caller's.
+    # The Gem Closure of `feature`: the gem in `loaded_specs` that owns it,
+    # plus its activated runtime dependencies, dependencies first. Default
+    # gems count: a new Box would otherwise load the newest installed version,
+    # not the Importer's.
     # Empty when no activated gem owns the file.
     def closure(feature, loaded_specs)
       owner = owner_of(feature, loaded_specs.values)
@@ -26,7 +27,7 @@ module Carton
       visit(owner, loaded_specs, [], {})
     end
 
-    # The caller's locked gems when `box` ran Bundler setup, otherwise nil.
+    # The Importer's locked gems when `box` ran Bundler setup, otherwise nil.
     # Bundler marks every locked spec as loaded, so these are the shareable
     # entries of its `Gem.loaded_specs`.
     def locked(box, loaded_specs)
@@ -57,7 +58,7 @@ module Carton
     #
     # Default gems come first, from this Box's own default specs: the YAML
     # round trip loads Psych, whose requires (date, for one) would otherwise
-    # activate the newest installed version before the caller's.
+    # activate the newest installed version before the Importer's.
     def activate(specs, locked = nil)
       defaults, others = (locked || specs).partition(&:default_gem?)
       defaults.each { |source| activate_spec(default_spec(source)) }
@@ -138,8 +139,8 @@ module Carton
     private_class_method :visit
 
     # Bundler is never shared: each Box loads its own copy to apply the
-    # restriction, possibly a different version than the caller's, and
-    # activating the caller's on top of it raises Gem::LoadError.
+    # restriction, possibly a different version than the Importer's, and
+    # activating the Importer's on top of it raises Gem::LoadError.
     def activatable?(spec) = spec.name != 'bundler'
     private_class_method :activatable?
 

data/lib/carton/import_cache.rb

@@ -6,9 +6,7 @@ module Carton
   # The Main Box creates one instance and every Carton Box receives that same
   # object, so each Entrypoint loads once no matter which Carton imports it.
   # Ruby objects are shared across Boxes; only definitions are Box-local, so
-  # the Main Box's loader builds every Carton. A cached value is then a
-  # value or `Carton::Exports` from the Main Box regardless of which
-  # Carton imported it first.
+  # the Main Box's loader builds every Carton and caches its Export.
   class ImportCache
     # Returned by `claim` when the calling thread should load the Entrypoint.
     LOAD = Object.new.freeze
@@ -80,9 +78,9 @@ module Carton
       end
     end
 
-    # A cached Carton keeps the gem versions its first importer gave it: its
-    # closure and the locked gems it has loaded, including any loaded lazily
-    # since. Raise instead of silently sharing it with an importer that
+    # A shared Carton keeps the gem versions its First Importer gave it: its
+    # Gem Closure and the locked gems it has loaded, including any loaded lazily
+    # since. Raise instead of silently sharing it with an Importer that
     # activates or locks another version of one.
     def check_gem_versions(key, target)
       wanted = versions([*target.locked_gems, *target.gems])

data/lib/carton/kernel_patch.rb

@@ -4,19 +4,19 @@ module Carton
   module KernelPatch
     private # like `require` and `require_relative`
 
-    # Import a carton by absolute path or by feature name from the caller box's
+    # Import a Carton by absolute path, or by feature name from the Importer's
     # current `$LOAD_PATH`.
     def import(path)
       Runtime.import(path, from: caller_locations(1, 1).first.path)
     end
 
-    # Import a carton relative to the calling file, like `require_relative`.
+    # Import a Carton relative to the calling file, like `require_relative`.
     def import_relative(path)
       caller_dir = File.dirname(caller_locations(1, 1).first.path)
       Runtime.import(path, base_dir: caller_dir)
     end
 
-    # Export one value from the current carton; `import` returns it as is.
+    # Export one value from the current Carton; `import` returns it as is.
     # Keywords export a Hash, as in `export version: '1.0'`.
     def export(value)
       file = caller_locations(1, 1).first.absolute_path

data/lib/carton/resolver.rb

@@ -2,16 +2,16 @@
 
 module Carton
   # Maps an Import path to the file that should load, without evaluating any
-  # code or reading Box state. The runtime passes the caller Box's
+  # code or reading Box state. The runtime passes the Importer's
   # `$LOAD_PATH`; a static analyzer can pass any load path it has computed.
   module Resolver
-    # `feature` is what the new Box requires. `load_path` is the single caller
+    # `feature` is what the new Box requires. `load_path` is the single Importer
     # load-path entry that matched a name-based Import, if any. The runtime
-    # fills `gems` with the caller specs to activate in the new Box, and
-    # `locked_gems` with the caller's locked specs when it ran Bundler setup.
+    # fills `gems` with the Gem Closure to activate in the new Box, and
+    # `locked_gems` with the Importer's locked specs when it ran Bundler setup.
     # After loading, the Carton Box sets `gem_usage`, a callable returning the
-    # gems the Carton depends on at that moment: its closure plus every locked
-    # gem whose files it has loaded so far.
+    # gems the Carton depends on at that moment: its Gem Closure plus every
+    # locked gem whose files it has loaded so far.
     Target =
       Struct.new(
         :feature,

data/lib/carton/runtime.rb

@@ -2,8 +2,10 @@
 
 module Carton
   module Runtime
-    ENTRYPOINT = File.expand_path('../carton.rb', __dir__)
-    private_constant :ENTRYPOINT
+    # Carton's own library, which every Carton Box loads so its Entrypoint can
+    # call `import` and `export`. It is not an Entrypoint.
+    LIBRARY = File.expand_path('../carton.rb', __dir__)
+    private_constant :LIBRARY
     # Used only when this Box is the Main Box. Carton Boxes reuse the Main
     # Box cache, so every Carton is built by the Main Box loader.
     IMPORT_CACHE = ImportCache.new { |target| load_import(target) }
@@ -11,24 +13,22 @@ module Carton
 
     module_function
 
-    # Load the target feature in a new box and return the exported value, or
-    # a `Carton::Namespace` of its definitions if it exports nothing. Each Entrypoint
-    # loads once per process; later imports return the same value.
-    # `base_dir` is given for `import_relative`; plain `import` searches the
-    # caller Box's `$LOAD_PATH`, and `from` names the calling file for its
-    # error message.
+    # Load the target in a new Carton Box and return its Export. Each Entrypoint
+    # loads once per process; later imports return the same value. `base_dir` is
+    # given for `import_relative`; plain `import` searches the Importer's
+    # `$LOAD_PATH`, and `from` names the calling file for its error message.
     def import(path, base_dir: nil, from: nil)
       unless Ruby::Box.enabled?
         raise ImportError, 'Carton needs Ruby::Box: run Ruby with RUBY_BOX=1'
       end
 
-      caller_box = Ruby::Box.current
-      load_path = caller_box.eval('$LOAD_PATH.to_a')
+      importer_box = Ruby::Box.current
+      load_path = importer_box.eval('$LOAD_PATH.to_a')
       target = Resolver.resolve(path, load_path:, base_dir:)
-      loaded_specs = caller_box.eval('defined?(Gem) ? Gem.loaded_specs : {}')
+      loaded_specs = importer_box.eval('defined?(Gem) ? Gem.loaded_specs : {}')
       target.gems = GemActivation.closure(target.feature, loaded_specs)
       unless target.gems.empty?
-        target.locked_gems = GemActivation.locked(caller_box, loaded_specs)
+        target.locked_gems = GemActivation.locked(importer_box, loaded_specs)
       end
       begin
         import_cache.import(target)
@@ -39,7 +39,7 @@ module Carton
       end
     end
 
-    # Make `value` the current carton's export, which `import` returns as
+    # Make `value` the current Carton's Export, which `import` returns as
     # is. A Symbol is refused even outside the Entrypoint: `export def name`
     # and `export :Name` would export the Symbol itself.
     def export(value, file:)
@@ -54,7 +54,7 @@ module Carton
     end
 
     # A name not on `$LOAD_PATH` is the usual mistake of `import` for a file
-    # beside the caller, so point at `import_relative` when one is there.
+    # beside the calling file, so point at `import_relative` when one is there.
     def missing_name_message(path, message, from)
       message = "#{message}: import searches $LOAD_PATH, like require"
       dir = from && File.dirname(File.expand_path(from))
@@ -68,14 +68,12 @@ module Carton
     private_class_method :missing_name_message
 
     def load_import(target)
-      Box
-        .new
-        .__send__(
-          :import_target,
-          target,
-          carton_entrypoint: ENTRYPOINT,
-          import_cache: IMPORT_CACHE,
-        ) { |methods, constants| Namespace.new(methods, constants) }
+      Box.new.__send__(
+        :import_target,
+        target,
+        library: LIBRARY,
+        import_cache: IMPORT_CACHE,
+      )
     end
     private_class_method :load_import
 

data/lib/carton/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Carton
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

data/lib/carton.rb

@@ -2,8 +2,6 @@
 
 require_relative 'carton/error'
 require_relative 'carton/bundler'
-require_relative 'carton/namespace_methods'
-require_relative 'carton/namespace'
 require_relative 'carton/box'
 require_relative 'carton/gem_activation'
 require_relative 'carton/import_cache'
@@ -16,7 +14,6 @@ module Carton
   private_constant :GemActivation
   private_constant :ImportCache
   private_constant :KernelPatch
-  private_constant :NamespaceMethods
   private_constant :Resolver
   private_constant :Runtime
 end

data/sig/carton.rbs

@@ -23,27 +23,3 @@ end
 
 class Carton::GemfileNotFound < Carton::Error
 end
-
-# Lookup helpers on every `Carton::Namespace`. `carton rbs` extends its
-# generated `Carton::Namespace::*` modules with these.
-module Carton::NamespaceMethods
-  type key = ::String | ::Symbol
-
-  # Helpers come back as Method objects; constants as set.
-  def []: (key key) -> untyped
-  def deconstruct_keys: (nil keys) -> ::Hash[::Symbol, untyped]
-                      | (::Array[::Symbol] keys) -> ::Hash[::Symbol, untyped]
-  def fetch: (key key) -> untyped
-           | (key key, untyped default) -> untyped
-           | [T] (key key) { (key key) -> T } -> (untyped | T)
-  def fetch_values: (*key keys) -> ::Array[untyped]
-  def keys: () -> ::Array[::Symbol]
-  def to_h: () -> ::Hash[::Symbol, untyped]
-  def has_key?: (key key) -> bool
-  def key?: (key key) -> bool
-  def values_at: (*key keys) -> ::Array[untyped]
-end
-
-class Carton::Namespace < ::Module
-  include ::Carton::NamespaceMethods
-end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carton
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - David Cristofaro
@@ -9,10 +9,11 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: 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, so only what
-  it exports is reachable, monkey patches stay where they are made, and two Cartons
-  can use different versions of the same gem. No manifest needed. Requires Ruby 4.0.7+.
+description: Split your app into Cartons with explicit imports and exports. Each has
+  its own dependencies and runs in a separate Ruby::Box, so Ruby enforces the boundaries
+  at runtime. Only what a Carton exports is reachable, monkey patches stay where they
+  are made, and two Cartons can use different versions of the same gem. No manifest
+  needed. Requires Ruby 4.0.7+.
 email:
 - david@dtcristo.com
 executables: []
@@ -31,8 +32,6 @@ files:
 - lib/carton/import_cache.rb
 - lib/carton/kernel_patch.rb
 - lib/carton/loaded_features.rb
-- lib/carton/namespace.rb
-- lib/carton/namespace_methods.rb
 - lib/carton/resolver.rb
 - lib/carton/runtime.rb
 - lib/carton/version.rb

data/lib/carton/namespace.rb

@@ -1,78 +0,0 @@
-# frozen_string_literal: true
-
-module Carton
-  # What importing a Bare Carton returns: a module of the constants and
-  # top-level helpers its Entrypoint defined. Helpers become singleton
-  # methods that forward to the Carton's method, and lookup helpers return
-  # the `Method` object or the constant.
-  class Namespace < ::Module
-    include NamespaceMethods
-
-    # A helper becomes a singleton method, so one named like a method every
-    # `Carton::Namespace` has, such as `fetch` or `name`, would hide it.
-    # Constants are capitalized and never collide.
-    def self.reserved?(name)
-      name = name.to_s
-      !name.match?(/\A[A-Z]/) && RESERVED.include?(name)
-    end
-
-    # Raise for the first reserved name in `names`.
-    def self.check_names(names)
-      name = names.find { |n| reserved?(n) } or return
-
-      raise ExportError,
-            "a top-level method named #{name} would hide " \
-              "Carton::Namespace##{name}: rename it, or export a module"
-    end
-
-    def initialize(methods = {}, constants = {})
-      super()
-      Namespace.check_names(methods.keys)
-      @lookup = {}
-      define_methods(methods)
-      define_constants(constants)
-    end
-
-    def deconstruct_keys(keys)
-      return super if keys
-
-      to_h
-    end
-
-    # `#<Carton::Namespace PI, add>`: its names, so a namespace is
-    # recognizable in a console.
-    def inspect
-      names = @lookup.keys.join(', ')
-      names.empty? ? '#<Carton::Namespace>' : "#<Carton::Namespace #{names}>"
-    end
-    alias to_s inspect
-
-    private
-
-    def define_methods(methods)
-      methods.each do |name, method|
-        @lookup[name.to_s] = method
-        define_singleton_method(name) do |*args, **kwargs, &block|
-          method.call(*args, **kwargs, &block)
-        end
-      end
-    end
-
-    def define_constants(constants)
-      constants.each do |name, value|
-        @lookup[name.to_s] = value
-        const_set(name, value)
-      end
-    end
-
-    def lookup_entry(key)
-      name = key.to_s
-      @lookup.key?(name) ? [true, @lookup[name]] : [false, nil]
-    end
-
-    def lookup_names = @lookup.keys
-
-    RESERVED = public_instance_methods.map(&:to_s).freeze
-    private_constant :RESERVED
-  end
-end

data/lib/carton/namespace_methods.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-module Carton
-  # Hash-like lookup helpers for `Carton::Namespace`.
-  module NamespaceMethods
-    # Support destructuring like `import('math') => { add: }`.
-    def deconstruct_keys(keys)
-      keys.each_with_object({}) do |key, hash|
-        found, value = lookup_entry(key)
-        hash[key] = value if found
-      end
-    end
-
-    # Return the member or `nil`.
-    def [](key)
-      found, value = lookup_entry(key)
-      found ? value : nil
-    end
-
-    # Check whether the lookup will succeed.
-    def key?(key)
-      lookup_entry(key).first
-    end
-
-    alias has_key? key?
-
-    # Fetch a member with the same default/block semantics as `Hash#fetch`.
-    def fetch(key, *default)
-      if default.size > 1
-        raise ArgumentError,
-              "wrong number of arguments (given #{default.size + 1}, expected 1..2)"
-      end
-
-      found, value = lookup_entry(key)
-      return value if found
-      return yield key if block_given?
-      return default.first unless default.empty?
-
-      raise KeyError, "key not found: #{key.inspect}"
-    end
-
-    # Member names as Symbols: helpers first, then constants.
-    def keys = lookup_names.map(&:to_sym)
-
-    # Every member by name: helpers as `Method` objects, constants as set.
-    def to_h = keys.to_h { |key| [key, self[key]] }
-
-    # Fetch several members and raise if any are missing.
-    def fetch_values(*keys)
-      keys.map { |key| fetch(key) }
-    end
-
-    # Return several members, using `nil` for missing keys.
-    def values_at(*keys)
-      keys.map { |key| self[key] }
-    end
-  end
-end