package-and-dependency-layout.md

package-and-dependency-layout — notes

Hand-written. ../harvested/package-and-dependency-layout.md is what the documents say; this file is what the implementation found, and it wins. Each entry names the harvested entry it answers by that entry's stable key.

Conflicts

• Ruby version floor: the design wins — required_ruby_version >= 3.2 in every gemspec, with a 3.2 / 3.3 / 3.4 / 4.0 CI matrix. Resolves package-and-dependency-layout/41b154a3. Library-versus-application again, and this is the clearest case of it: .ruby-version pins the interpreter an application runs on, and a gem does not choose its consumer's interpreter — required_ruby_version only excludes consumers. NFR-10 requires a declared lowest-supported-runtime floor targeted by all general-purpose units; pinning 4.0 would make the SDK uninstallable on every currently-maintained Ruby below it for no correctness gain. What the SDK does instead: floor 3.2 (the release that introduced Data.define, which the domain model depends on), TargetRubyVersion: 3.2 in .rubocop.yml, and the matrix runs the real suite on each Ruby rather than a syntax check, because TargetRubyVersion catches syntax and not stdlib availability. The 4.0 column is load-bearing for a second reason: it is where the bundled-gem trap (logger, ostruct, benchmark, fiddle, pstore leave the default set at 4.0) and the clean-bundle isolation run actually fire. .ruby-version remains committed for development, and it names the highest Ruby in the matrix, not the floor. The styleguide-amendment alternative (separating .ruby-version from required_ruby_version in rule 1.1) was considered and not taken; this is recorded as an SDK deviation instead. _{review · docs/work/mvp/2026-09-05-ruby-sdk-v1-roadmap-design.md · high · sha:manual-roadmap-conflict-3}
• Gems per repository: the design wins — one repository, one directory and one gemspec per published gem under gems/. Resolves package-and-dependency-layout/8c0687bf. The styleguide's rule reads "multiple gemspecs in one repo signal the gem should be split", and the port agrees with the signal and has already acted on it: the gems are split, into dexpace-core plus one adapter per seam, which is exactly what NFR-2 asks for. The disagreement is only about repository count, which the styleguide's chapter does not actually reason about. What the SDK does instead: the aws-sdk-ruby/rubocop shape — one lean core and independently versioned satellites in one repository with shared CI and a root VERSIONS file as NFR-14's single source of truth. The dry-rb one-repo-per-gem model was weighed and rejected because adapters must track core's seam interfaces closely while those interfaces are still moving pre-1.0, and cross-repo CI would cost more than it saves. Within each gems/<name>/ directory the styleguide's standard gem layout is followed exactly: single entry point, sig/, test/ mirroring lib/, one gemspec. The styleguide-amendment alternative (rewording rule 12.5 point 4 to "one gemspec per published gem") was considered and not taken; this is recorded as an SDK deviation instead. _{review · docs/work/mvp/2026-09-05-ruby-sdk-v1-roadmap-design.md · high · sha:manual-roadmap-conflict-4}

Superseded

• The Ruby 4.0 bundled-gem list is longer than five names, racc left at 3.3 and tsort leaves at 4.1, set stops being a gem entirely at 4.0, and Gem::BUNDLED_GEMS::SINCE does not exist on the 3.2 floor. Supersedes package-and-dependency-layout/934983a1 and corrects the illustrative default-gem list in package-and-dependency-layout/a50018cc. The harvested facts were verified on Ruby 3.4.10 only, where the 4.0 column of Gem::BUNDLED_GEMS::SINCE was still a forward-looking table; re-verified on 2026-09-05 against installed interpreters 3.2.11, 3.4.10 and 4.0.6 (ruby -e 'require "bundler"; p Gem::BUNDLED_GEMS::SINCE' under each), the table on Ruby 4.0.6 has 23 entries, not the 6 the harvested entry implies: racc since 3.3.0; abbrev, base64, bigdecimal, csv, drb, getoptlong, mutex_m, nkf, observer, resolv-replace, rinda and syslog since 3.4.0; benchmark, fiddle, irb, logger, ostruct, pstore, rdoc, reline and win32ole since 4.0.0; and tsort since 4.1.0. Why it matters rather than being a longer list of the same thing: irb, rdoc and reline are names the harvested entry does not warn about and a core file could plausibly reach for; tsort is default on every Ruby in the supported range and is still a trap, because it leaves at 4.1 and an allowlist built from "default on the highest supported Ruby" would admit it today and break at the next floor bump. Two further corrections in the same family: set is not a default gem on 4.0.6 at all — Set is a core class there, Set.instance_method(:add).source_location is nil, and require "set" succeeds as a no-op — so citing it as an example of a default gem is true on 3.2 and 3.4 and false on 4.0; and pathname and cgi move the other way, from default gem on 3.2/3.4 to non-gemified stdlib on 4.0. And the mechanism itself has a floor: Gem::BUNDLED_GEMS::SINCE is undefined on Ruby 3.2.11, so the require-allowlist audit cannot read it on the floor interpreter and must take the highest Ruby in the matrix as the authority, which is what docs/sdk-design-ruby/09-toolchain-and-quality-gates.md §9.2 already says and is now a hard constraint rather than a preference. The counts behind all of this: 3.2.11 ships 71 default gems and no SINCE table, 3.4.10 ships 58 default gems and a 28-entry table, 4.0.6 ships 46 default gems and a 23-entry table. Every name in the port's committed require-allowlist was checked to require cleanly on all three. _{review · docs/work/mvp/phase0/2026-09-05-phase0-scaffold-and-quality-gates-design.md · high · sha:manual-phase0-bundled-gems}