toko-tooling 0.44.7

Shared development tools, CI helpers and engineering rules for Toko Studios
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
# Rust workspace layout

These rules are part of the mandatory [engineering baseline](../TOKO-TOOLING.md).
They standardise maintained Rust package locations while preserving locally
owned APIs, canister identities, validation gates and deployment configuration.

## Standard layout

### Workspace licence metadata

Apply the baseline's
[canonical licence policy](../TOKO-TOOLING.md#canonical-licence-and-contribution-policy)
through Cargo workspace inheritance for packages covered by the repository's
Toko licence. In the product root `Cargo.toml`:

```toml
[workspace.package]
license-file = "LICENSE.md"
```

Every covered member's manifest, including a root package when present and
unpublished helpers, inherits it under `[package]`:

```toml
[package]
license-file.workspace = true
```

An independent `qualification/Cargo.toml` declares its own
`[workspace.package] license-file = "../LICENSE.md"`; its members use the same
inheritance syntax. Cargo resolves inherited licence paths relative to the owning
workspace root, so member directory depth does not change the declaration.
Do not use `workspace.license-file` (the `package` table is required), repeat
relative paths in children, add a `license` expression or copy the licence into
member directories. Packaging may include the canonical file in an archive
without creating another maintained source copy.

Confidential proprietary repositories omit first-party licence files and Cargo
`license`/`license-file` metadata. Set every private package to `publish = false`
(directly or through explicit workspace inheritance). Tooling adoption does not
require granting a public licence. An unpublished package in a licensed
repository remains covered; `publish = false` only blocks registry publication.

### Package locations

Every repository containing maintained Rust packages uses a virtual root,
including repositories with only one package. The standard package locations
are `crates/` for product packages, `apps/<fleet-name>/` for Canic fleets and
their deployed components, and `qualification/` for separate qualification-only
packages. Meaningful subdirectories are supported: both `crates/<package-name>/`
and `crates/<domain>/<package-name>/` are standard. Qualification has one package
tier, `qualification/<package-name>/`. Toko's grouped product packages need no
layout exception.
Repositories need only the trees they use. The baseline's
[product and qualification rule](../TOKO-TOOLING.md#product-and-qualification-workspaces)
owns this standard across repositories.

This is a deliberate fleet consistency convention: even a single library keeps
both the root workspace `Cargo.toml` and its package `crates/<package-name>/Cargo.toml`.
That example is the simplest shape, not a maximum directory depth. List actual
member paths explicitly in the owning manifest. Grouping introduces no extra
workspace, catalog, version owner or release group; discover members with Cargo
metadata rather than a fixed-depth glob or directory scan.
Retain the standard shape; adoption changes existing layouts through a scoped
migration rather than incidental cleanup:

```text
Cargo.toml                 # Virtual workspace; no [package]
Cargo.lock                 # Selected product dependency graph
crates/
  package-name/
    Cargo.toml             # [package].name = "package-name"
    src/
    tests/                 # When needed
  domain/                  # Optional meaningful product grouping
    grouped-package/
      Cargo.toml
      src/
apps/
  app-name/
    canic.toml             # Canic fleet configuration
    component-package/
      Cargo.toml           # [package].name = "component-package"
      src/
qualification/             # Only when separate qualification packages exist
  Cargo.toml               # Independent virtual workspace
  Cargo.lock               # Selected qualification graph
  package-name/            # No qualification/crates/ directory
    Cargo.toml             # publish = false; no product release group
    src/
```

- The repository root is a virtual workspace: its `Cargo.toml` declares
  `[workspace]`, without `[package]`, package targets or package dependency
  tables. Select the resolver explicitly using the supported toolchain; a layout
  change does not authorize a resolver, edition or MSRV upgrade.
- Use packages under `crates/` for product libraries, standalone binaries/CLIs,
  reusable tools, shared schemas and standalone product canisters. Packages
  maintained solely to test, benchmark, fuzz or qualify those products, including
  private fixture canisters and test-support packages, belong under
  `qualification/` in its independent workspace. A reusable testing tool shipped
  as a product stays in `crates/`; publication flags and names alone do not decide
  responsibility. No product normal, build or dev dependency may point back to
  a qualification package. Keep a small unit-test helper local to its product
  instead of creating a reverse dependency.
- Reserve `apps/<fleet-name>/` for Canic fleet configuration and the canister
  components deployed by that fleet. Package directories follow the baseline's
  [package naming rule]../TOKO-TOOLING.md#product-and-qualification-workspaces,
  for example `apps/demo/demo-user-hub/` for package `demo-user-hub`.
  A native publisher, command-line application or product generator belongs in
  `crates/`; a qualification-only harness or fixture belongs in `qualification/`.
  A standalone canister is not a Canic fleet merely because it is an application.
  Do not create general-purpose `apps/tooling/` or `apps/qualification/` trees,
  or reserve an `apps/` path for a future non-fleet service. Test-only fleet
  packages follow the qualification workspace's package layout; retained
  deployment configuration may reference those packages explicitly.
- Classify canisters by purpose, not execution format. Standalone product
  canisters use `crates/`; product fleet components use `apps/`; separate test,
  audit and benchmark canisters use `qualification/`, with optional meaningful
  grouping. Do not introduce a parallel top-level `canisters/` tree or a separate
  workspace merely because a package compiles to a canister. Preserve package
  names and update all build/deployment references when migrating existing test
  canisters. Small fixtures without their own manifest stay beside their tests.
- Keep ordinary module tests, examples and fixtures with their owning package;
  they do not need separate packages merely to follow this layout.
- Declare product members in the root workspace and exclude `qualification`.
  Declare qualification-only members in `qualification/Cargo.toml`, each with
  `publish = false`. Keep common package
  metadata in `[workspace.package]`, with inherited child values. Package versions
  follow the [release-group rules]#coordinated-versions-and-workspace-boundaries:
  a coordinated product workspace uses root inheritance; independent product
  groups all use package literals. Qualification versions are private metadata
  owned by their workspace, may use workspace inheritance, and do not advance
  with product releases. Keep each workspace's complete direct dependency catalog in
  `[workspace.dependencies]` under the [Cargo dependency rules]cargo-dependencies.md.
  Those rules allow documented package-specific MSRVs; a higher internal-tool
  floor must not become the public libraries' minimum through inheritance alone.
  Preserve package identities, selected dependencies and effective features.
  An `apps/` directory does not create an independent Cargo workspace: its
  product packages belong to the product root, catalog and declared release groups.
- Keep the selected `Cargo.lock`, workspace profiles and workspace-wide Cargo
  configuration at their owning root. Preserve intentional `default-members`,
  target distinctions and publication selections; a directory move must not
  silently widen normal builds or published packages.
- Application/deployment configuration, frontend code, scripts and documentation
  retain their locally owned locations. A Canic fleet under `apps/` may contain
  its deployment configuration, assets and component packages; package references
  follow that fleet's discovery contract.
  Moving a package does not rename a deployed canister or authorize deployment.
- Repositories without maintained Rust packages do not need a Cargo workspace
  or empty `crates/`, `apps/` or `qualification/` directories. Generated scratch projects, vendored
  upstream sources and frozen historical evidence are not maintained package
  locations; do not move them or rewrite history to satisfy this layout.

## Coordinated versions and workspace boundaries

Keep related product crates together for development. A Cargo workspace
does not require one release version: use a small number of explicit release
groups when independent contracts otherwise force unrelated breaking releases.
Each group has one coordinated version and one changelog. A workspace whose
packages genuinely evolve together remains a single group, with the existing
workspace-version inheritance and release commands.

Prefer release groups within the existing workspace over moving public crates
to new workspaces or repositories solely to give them independent versions.
This retains one dependency catalog, lockfile and development workflow. It does
not isolate Cargo resolution; the
[core and integration graph boundary](#core-and-integration-graph-boundary)
still governs the independent qualification graph.

- Group packages by actual shared contracts, dependency direction, consumer
  upgrades and release obligations. Keep tightly coupled generators/runtime
  helpers coordinated; do not create one group per crate by default. Shared
  ownership, directory placement or qualification alone does not require matching
  versions. Similar names or occasional unchanged releases do not justify a split.
- When an unrelated capability change forces downstream upgrades, trace the
  public-type, implementation and singleton edges before choosing release groups.
  Record the cause and affected consumers in the existing issue or change notes.
  A feature gate does not give a capability an independent package version.
  If an approved split separates a runtime from unrelated capabilities, move the
  implementation owner with its tightly coupled helpers; loosening an empty
  guard's pin cannot establish one runtime. Preserve real singleton refusal.
  Qualify that an unrelated group change leaves the runtime supplier and its
  existing consumers usable, and that incompatible runtime suppliers still fail.
- For independent public versions or workspace migrations beyond the standard
  product/qualification separation, show a recurring maintenance problem, why a local
  fix or release batching is insufficient, and the total migration and
  qualification cost for consumers.
  Preserve approved independent graphs and record maintainer agreement for the
  selected boundary or versioning-policy change. Carry an existing approval
  forward; do not request it again for implementing that agreed boundary.
  Approved product release groups share the product workspace and lockfile using the existing
  [explicit release-group contract]../docs/releases/releases.md#explicit-cargo-release-groups.
  Its admitted member versions are the scoped exception to workspace-version
  inheritance; root dependency inheritance and repository-wide CI remain.
  Release qualification defaults to the full gate until the consumer qualifies
  an explicit [group plan]../docs/releases/release-group-validation.md.
- In a product workspace with independent release groups, every product member
  belongs to one explicit group. Qualification-only tooling and fixtures are
  members of the separate qualification workspace, never of these groups. Remove
  the product root's `[workspace.package].version`; every product member declares a literal package version
  equal to its group's primary package. The primary is only that group's version
  authority, not a master package for the workspace. Other common metadata may
  still inherit from `[workspace.package]`.
- Cargo has no per-group version-inheritance mechanism. Do not add an intermediate
  group `Cargo.toml`, nested workspace, shadow version file or custom inheritance
  syntax to represent a release group. Keep existing crate paths, one root
  dependency catalog and lockfile, and the existing release runner. Group release
  material lives under `releases/<group>/`; package relocation is not part of
  adopting this convention.
- Treat every group symmetrically: each owns
  `releases/<group>/CHANGELOG.md`, and root `CHANGELOG.md` is an index. Release,
  resume and publication commands require an explicit `RELEASE_GROUP`; never
  silently default to the former root-version group or the whole public roster.
  Follow the [selection contract]../docs/releases/releases.md#explicit-cargo-release-groups
  and [history migration rules]changelogs.md#release-group-changelogs-and-shared-history.
- Leave unaffected groups' versions and changelogs unchanged. Cross-group
  requirements change only when needed for the selected dependency contract;
  they need not numerically match the consumer's own version. Exposed Rust types,
  runtime identities and wire/storage contracts still require real compatibility
  assessment. A changed dependency declaration cannot be republished under an
  already published package version.
- Qualification-only maintenance does not select a product group for publication
  or change the qualification packages' versions to match it. Changes to private
  product tools require their actual product-impact assessment. Apply the
  [publication-impact decision]../docs/releases/releases.md#decide-whether-publication-is-needed
  before bumping versions. Qualification selection is a validation relationship,
  not release-group membership.
- Start each group from its existing package/release history. Do not reset
  versions, rewrite tags or re-upload published identities when adopting groups.
  Keep one [canonical changelog per group]changelogs.md#release-group-changelogs-and-shared-history
  and preserve the earlier shared history. Boundary approval alone does not
  authorize version bumps, release execution or publication.
- Prefer batching related, already-planned breaking changes into one coordinated
  release before downstream adoption. Avoid repeated consumer migrations for
  adjacent changes, but do not hold urgent fixes for unrelated work or enlarge a
  release with speculative changes. Classify the combined release and downstream
  adoption using the [package-impact rules]changelogs.md#classify-the-released-packages-own-impact.
- Keep unrelated repositories independently versioned. Toko Tooling snapshot
  adoption, a common dependency or a common owner does not require fleet-wide
  version synchronization. Verify adoption through the consumer's
  [selected dependency graphs]../docs/validation/cargo-graph-checks.md#coordinated-release-adoption.

<a id="visible-release-group-map-in-cargotoml"></a>

### Package inventory and dependency declarations

For a product workspace with independent release groups, declare used local dependencies
in root `[workspace.dependencies]` with their local paths. Publishable members need
their full current version. Members with `publish = false` may omit the dependency
version, so Cargo can omit private path-only dev-dependencies from published packages.
Publishable members may depend on private members only through these path-only
development edges; versioned private dependencies and normal/build edges are rejected
before release preparation.
Use `make deps-list` for the complete package/version/group view; do not add unused
dependencies or suppress unused-dependency lints merely to maintain that display.
The qualification catalog
separately owns its private members and references to the product packages.
Cargo.toml does not need release-group blocks, changelog comments or dependency-role
sections. Use ordinary sorted declarations; optional comments may explain a
non-obvious constraint without duplicating the group policy.

Members inherit used dependencies with `workspace = true`. Remove unused
display-only declarations and their group dependency aliases together; retain group
membership. Do not add member dependencies just to consume catalog entries.
The existing `ci/cargo-release-groups.json`
is the executable policy; member manifests supply package versions. Root dependency
values remain actual Cargo requirements, not package-version inheritance. Do not
copy numeric versions into comments or add a generated summary or shadow catalog.

List each catalog alias in its owning release group's `dependencies` roster so
release preparation accounts for it, including unused and renamed aliases.
Path-only private entries remain unchanged; their package versions still advance
with their group. For every versioned root path dependency naming a workspace
member, spell the full current member version. Preserve its existing bare, `^`, `~` or `=` operator; do
not add exact pins merely for display. Group admission checks this equality for
all groups, including through the normal dependency checker. It also checks
complete group member coverage, declared alias ownership and each path's actual member manifest,
including unused aliases that Cargo does not resolve. It rejects both
abbreviated versions and compatible but stale lower bounds that Cargo itself
would accept. Release preparation updates the selected group's local requirements
inside its existing transaction; other groups and external dependency requirements
remain unchanged. Manual member-version edits must update the corresponding real
requirements too. Before adopting the check, align root declarations with current
members without changing package versions.

Review used declarations against actual member dependencies and the group policy when membership changes. `make deps-list` reads package versions and group membership without a second catalog. A single-group workspace needs no JSON policy solely for display.

An explicit task to adopt this convention includes converting inherited versions
to their existing numeric values, moving ledgers with preserved history and
updating the policy, callers and fixtures. It does not authorize numeric version
bumps, package moves, publication or changes to existing release identities.
Reconcile unfinished attempts against their recorded source and policy; do not
reinterpret old journals after changing version ownership or ledger paths.

## Core and integration graph boundary

Apply the baseline's [dependency selection rule](../TOKO-TOOLING.md#current-dependencies-and-upstream-independence)
uniformly. Separate qualification workspaces are already the standard for separate
qualification packages; do not add further workspaces per supplier or move a
shipped test library out of the product workspace to conceal its dependencies.
An independent lock isolates resolution, not every release obligation: required
tests must still exercise the selected product source and its real boundaries.
Allow older native-only transitive suppliers where those boundaries permit them;
require identity agreement where values actually cross a typed API, or a runtime
singleton is active. Avoid blanket "matching supplier family" requirements across
unrelated targets, workspaces or repositories.

Reusable engines own their core contracts; adapters and applications own the
composition of those contracts with a framework or deployment stack. An adapter
may require matching Platform, Wire, Memory, runtime and framework identities.
Those requirements belong to that integration, not automatically to every core
library it consumes. Preserve dependencies required by the core's actual public
types, behavior and retained-data contracts.

- Apply the baseline's [endpoint ownership rule]../TOKO-TOOLING.md#ic-application-encoding.
  Trace codec use, protocol contracts and executable exports separately. A domain
  protocol may stay with its library; framework-specific method rosters, mounting
  and guards belong to the integration owner. Generated private native handlers
  are not public exports. Preserve precommit response admission, storage formats
  and recovery guarantees when moving bindings; a codec replacement requires its
  own explicit format assessment. Qualify native use without endpoint mounting
  and the real adapter's authorization and transport behavior independently.
- Keep consumer-framework dependencies out of reusable core libraries and their
  ordinary tests. Put framework-specific mounting, lifecycle, deployment and
  composed endpoint qualification at the adapter/application owner or an
  explicitly scoped integration harness. A `dev-dependency`, CLI, example or
  unpublished member can create the same maintenance constraint as a runtime
  dependency; inspect actual callers rather than dependency-role comments alone.
- Preserve real core regression coverage. Replacing a framework-hosted test means
  retaining its engine invariant in owner-local tests and its composition proof
  at the integration boundary; moving a test is not permission to drop that proof.
- Core qualification must have an owner-local path that does not require its
  downstream adapter to release first. Merely placing a composed fixture in a
  separate workspace is insufficient if core gates still require it unconditionally.
  Keep composition qualification explicit and required where the changed contract
  affects it. Demonstrate that an incompatible adapter graph fails its own check
  while independent core checks retain accurate results; no silent skipping or
  stale-source evidence may substitute for required integration acceptance.
- Before declaring a core upgrade blocked, name the package, target/features,
  conflicting identities and introducing paths. Distinguish a core contract
  change from an adapter's compatibility constraint. Do not require unrelated
  consumers or every workspace to adopt one fleet-wide dependency generation.
- Delete unused edges and keep composition tests with their responsible adapter
  or qualification owner. Separate qualification packages use the independent
  `qualification/` workspace by default, before a conflict occurs. Cargo resolves
  workspace members together, including optional and
  development dependencies; `default-members`, `-p`, feature gates and comments
  alone do not establish independent lockfile resolution. See
  [Cargo's resolver contract]https://doc.rust-lang.org/cargo/reference/resolver.html#features.
- Record the qualification root, member scope, lockfile and focused commands in
  the local overlay. Adopting this standard needs no additional architectural
  exception once migration is authorized. Preserve package identities and public
  release versions; do not move a product adapter into qualification merely
  because its dependency graph is inconvenient.
- An integration may retain an older qualified matching stack while the core
  advances. Its evidence qualifies only its selected source/dependency identities.
  A path dependency on current core source must be qualified again when those
  inputs change; an old integration pass cannot qualify the new core. Keep core
  and integration checks explicit, with required integration acceptance attached
  to the affected adapter/product change rather than every unrelated core edit.
- Preserve actual runtime singleton, exposed-type, wire/storage and lifecycle
  obligations within each composed graph. Isolation does not authorize bypassing
  a guard, claiming incompatible types interoperate, retaining compatibility
  shims, publishing unqualified combinations or skipping release-owned gates.

## Workspace member roles

Workspace membership follows responsibility, not an optional comment grouping:

- Product libraries, applications and reusable product tools belong to the root.
- Separate qualification-only runners, benchmarks, fuzzers, fixture canisters
  and test-support packages belong to `qualification/` and are unpublished.
- Ordinary package-local tests, examples and fixtures remain with their product;
  this rule does not turn every test file into another crate or workspace.

Classify mixed-use code by its real product contract. A reusable product such as
Testkit is not qualification-only just because other products use it in tests.
Do not use `publish = false` to move a product build dependency out of its owning
graph. Mark qualification package roles in the existing LOC metadata, keeping
reports consistent with the actual source responsibility.

Dependency-role headers inside each workspace's `[workspace.dependencies]` remain
governed by the
[Cargo dependency rules](cargo-dependencies.md#dependency-roles-and-deployment-checks).
They do not assign release-group membership or change enabled dependency kinds.

## Independent workspaces and exceptions

The standard is one product workspace plus one independent qualification
workspace when separate qualification packages exist. Each has one catalog and
lockfile. Follow the baseline's
[single-tier qualification layout](../TOKO-TOOLING.md#product-and-qualification-workspaces):
each package is a direct child of `qualification/`, named after its package.
Both roots are virtual workspaces. Product domain grouping does not authorize
nested qualification packages or additional workspace catalogs.

Additional independent workspaces or a nonstandard package layout need a scoped
maintainer exception naming the root, members, reason, lock and validation
coverage. Preserve existing independent resolution boundaries until their
replacement is qualified; standardization does not authorize merging incompatible
graphs, upgrading suppliers or skipping required checks.

### Qualification and release-group relationships

A release group contains only product-workspace packages. A qualification package
may validate several groups but belongs to none of them. The consumer's explicit
validation plan maps each group/change to required qualification roots, packages,
targets, features and commands. An unqualified mapping retains the existing
complete gate; separate workspaces do not waive release acceptance.

Qualification inherits no product release version and owns no product release
ledger. Product releases may update qualification's product path requirements and
resolved lock identities. Prepare and validate all affected metadata in one
transaction; preserve unrelated dependency selections and private package versions,
and roll back the complete candidate on failure. A shared qualification lock may
appear once as shared release metadata without making its packages group members.

Toko Tooling owns reusable multi-lock rendering, admission and rollback mechanics.
Consumers own their validation mapping and product-specific checks. Declaring
additional metadata in the current runner does not itself render or qualify it.
Do not copy generic release machinery into every consumer, or claim multi-lock
support merely from this policy. Qualify shared mechanics before consumer release
adoption; keep any existing qualified adapter narrowly scoped until replacement.

### Approved IcyDB layout

The 2026-10-07 permission to retain IcyDB's `crates/`, `canisters/`, `schema/`
and `testing/` trees is historical migration context. The maintainer's 2026-11-09
common product/qualification standard supersedes that general layout exemption.
During scoped adoption, classify actual product schemas/tools and qualification
fixtures separately, preserve package identities and move them into the standard
owners. Do not collapse IcyDB's independently resolved Canic qualification into
the product graph. This policy change is not authority to edit IcyDB or silently
move packages during unrelated maintenance; complete its migration as a coherent,
separately scoped consumer task.

## Adoption and verification

Adopt the reviewed [baseline snapshot](../docs/adoption/consuming-snapshots.md)
and read this rule at the same upstream revision; do not vendor the reference guide.
Coordinate consumer work through issues and preserve unrelated working changes.
The product/qualification standard was introduced in 0.38.0; atomic multi-lock
release preparation is available from 0.38.1 under the
[qualification release contract](../docs/releases/releases.md).
Consumers must verify the supplying release is actually published, then adopt
its exact selection and authenticated snapshot before claiming adoption. A pending
version or this document does not establish publication. Do not patch consumer
snapshot-owned rules or use unpublished producer files as adopted policy.
In the owning repository's authorized change:

1. Inventory maintained manifests, workspace roots, selected lockfiles and
   approved exceptions. Retain packages already in the standard layout;
   preserve Canic fleet component grouping under `apps/`. General application or
   tooling grouping alone does not qualify a package for `apps/`. Move separate
   qualification packages to the independent qualification tree, remove them
   from product groups and keep their existing private versions. Migrate old
   general layout exemptions to the common standard rather than treating them as
   permanent grandfathering; any new exception must be explicit and scoped.
   Record old-to-new package paths before any necessary moves.
2. Update workspace membership, dependency paths, package include/readme/license
   paths, build scripts, fixtures, source-relative paths, Make/CI commands,
   publication inputs and deployment package references together. Change any
   maintained scaffolding at its generator. Retire obsolete source locations
   rather than leaving duplicate packages or symlink aliases.
   Formatting, release inventories and source checks must cover all declared
   workspace members in both roots, using Cargo metadata or
   a verified member inventory rather than assuming every package matches
   `crates/*`, `qualification/*` or `apps/*`. Retain supported product grouping;
   do not flatten supported paths merely to simplify a script. Keep required group qualification mapped explicitly,
   with atomic lock/metadata handling and rollback evidence. Demonstrate that an
   incompatible qualification selection refuses there without blocking independent
   product resolution; do not weaken genuine runtime/type identity checks.
3. Preserve package names, versions, APIs, features, publication policy, canister
   identities and selected dependencies. Review packaging contents and
   `CARGO_MANIFEST_DIR`-relative inputs; a successful directory move alone does
   not establish equivalent behavior. For coordinated packages still sharing
   their released versions, follow the
   [archive qualification guidance]cargo-dependencies.md#qualifying-coordinated-package-archives-before-a-version-bump.
4. Run the owning focused locked metadata, formatting and path/packaging checks
   for every affected workspace with prepared tools and caches. Keep the existing
   Linux/macOS qualification obligations and local command authority. Adoption
   does not add a new gate or authorize publication, cleanup or version changes.
   Qualify directly affected consumers with focused checks before handoff;
   reserve local full-suite runs for release or an explicit request under the
   baseline.
5. Verify the adopted snapshot and update local instructions and documentation.
   Distinguish committed adoption from local preparation and native execution
   evidence from source inspection.

Source reports must independently exclude Cargo's selected build-output directory
using metadata, including custom target directories. The standard layout keeps
default build output outside package trees, but is not a substitute for correct
file inventory in the reporting helper.