feat(export)!: run unity.export once per unit instead of once per bundle

docs/assets.md

@@ -45,18 +45,20 @@ nnnotes depot verify [--quick] [--workers N]
 | `--stored-catalog` | a catalog version of the depot (`catalog versions`) instead of the current catalog |
 | `--png-level N` | zlib level 0-9 of the PNG files (default 6); part of the task keys |
 | `--flac-level N` | FLAC compression level 0-12 of the CRI audio and the movies' audio (default 8; every level decodes to the same samples; 12 writes files 0.2-1.3 % smaller in about five times the encoding time); part of the task keys |
-| `--only-class C,...` | export only objects of these Unity classes; part of the task keys |
+| `--only-class C,...` | export only the units whose root object is of these Unity classes (a prefab by `GameObject`, [stages.md](stages.md#units)) |
 | `--link` | how the layout files are made from the depot (below): `auto` (default; `[export] link`), `clone`, `hard` or `copy` |
 | `--strict` | exit 1 when a view has gaps: a required role whose address names no catalog key or no fitting sub-object (empty values and roles that do not apply are not gaps); in `voices`, a voice whose cue sheet has no catalog key or whose decoded sheet lacks its cue, and a story episode without a catalog key |
 | `--dry-run` | print the plan and stop |
 | `--explain` | print every setting of the run first: depot, context, selection, pipeline, stages not installed, parameters, workers, memory budget, recycling, layouts |
 
 A run resolves the context (region, language, catalog version) and indexes the catalog, identifies the selected
 bundles (the sha256 of each decrypted bundle, remembered by path, size and modification time; bundles not
-downloaded yet are fetched into the depot's `downloads/`), takes the census of each bundle, links the scripts and addresses, exports the bundles, runs the
+downloaded yet are fetched into the depot's `downloads/`), takes the census of each bundle, links the scripts and
+addresses, exports the units (one task per hierarchy or object outside any, [stages.md](stages.md#units)), runs the
 stages that need those results (atlas sprites, views), writes the layouts and the reports. The selected raw files
 (CRI audio and movies) not downloaded yet are fetched while the bundle stages run. The census also covers
-the bundles the selected ones depend on, so script classes and atlas textures in other bundles resolve.
+the bundles the selected ones depend on, so script classes and atlas textures in other bundles resolve, and the
+export covers the units of those bundles that the selected ones reference.
 
 Tasks run in spawned worker processes that stay alive between tasks. The tasks of a stage that read the same
 loaded data (a stage's batch, such as one bundle) form one job: one worker runs them one after another and loads the

docs/cli.md

@@ -174,7 +174,7 @@ every object of the selected bundles -> common formats (the depot and its layout
 | `--stored-catalog` `LABEL\|SHA` | a catalog version of the depot (`catalog versions`; default: the current catalog) |
 | `--png-level` `N` | PNG compression level 0-9 (changes the output) |
 | `--flac-level` `N` | FLAC compression level 0-12 of the CRI audio (default 8; every level decodes to the same samples; changes the files) |
-| `--only-class` `C,...` | export only objects of these classes |
+| `--only-class` `C,...` | export only the units whose root object is of these classes |
 | `--workers` `N` | worker processes (default: the CPUs this process may use; 0: this process) |
 | `--memory` `GiB` | memory budget of the running tasks and workers (default: 80 % of the physical memory) |
 | `--fetch-workers` `N` | parallel downloads (default 8) |
@@ -317,7 +317,7 @@ what `export assets` would run and why, without running it (--json: nnnotes.plan
 | `--stored-catalog` `LABEL\|SHA` | a catalog version of the depot (`catalog versions`; default: the current catalog) |
 | `--png-level` `N` | PNG compression level 0-9 (changes the output) |
 | `--flac-level` `N` | FLAC compression level 0-12 of the CRI audio (default 8; every level decodes to the same samples; changes the files) |
-| `--only-class` `C,...` | export only objects of these classes |
+| `--only-class` `C,...` | export only the units whose root object is of these classes |
 | `--workers` `N` | worker processes (default: the CPUs this process may use; 0: this process) |
 | `--memory` `GiB` | memory budget of the running tasks and workers (default: 80 % of the physical memory) |
 | `--fetch-workers` `N` | parallel downloads (default 8) |

docs/contracts.md

@@ -36,14 +36,15 @@ The canonical JSON (`nnnotes.core.canon`) of every document nnnotes writes:
 | object | `<serialized file>:<pathId>` | `CAB-2f1e…:-4153…`, `unity default resources:10` |
 | artifact of an object | `<object id>#<role>` | `CAB-2f1e…:-4153…#image` |
 | artifact of no object | `<stage>:<subject>#<role>` | `cri.audio:<acb sha256>#bgm_x.flac` |
-| task | `<stage>:<subject>` | `unity.export:membercard_assets_membercard_100101` |
+| task | `<stage>:<subject>` | `unity.census:membercard_assets_membercard_100101`, `unity.export:membercard_assets_membercard_100101:-4153…` |
 | stable bundle name | the bundle file name without `_<32 hex>` and `.bundle` | `membercard_assets_membercard_100101` |
 | stable address | `<stable bundle>/<container>` (`[<name>]` for a sub-object), else `<stable bundle>:<pathId>` | `membercard_assets_membercard_100101/assets/…/member_full.png` |
 
 Stage names contain no `:` or `#`; an artifact's owner contains no `#` (its role may). A bundle's serialized file
 names change whenever its content changes, while its path ids stay: an object id names one content version of an
 object, and the stable address finds the same object in another catalog version. Bundle stages use the stable
-bundle name as their subject, so a task keeps its id across versions while its key follows the content. When two
+bundle name as their subject and object stages the `<stable bundle>:<pathId>` address of their object, so a task
+keeps its id across versions while its key follows the content. When two
 bundles of a catalog have the same stable name, both keep their full file names.
 
 ## Task: nnnotes.task/1
@@ -52,13 +53,14 @@ One stage applied to one subject, with everything needed to run it
 ([task.schema.json](https://github.com/MetaSekaiLab/nnnotes/blob/main/src/nnnotes/schemas/task.schema.json)):
 
 ```json
-{"schema": "nnnotes.task/1", "id": "unity.export:membercard_assets_membercard_100101",
- "stage": {"name": "unity.export", "version": 1},
- "params": {"png": {"encoder": "pillow", "level": 6}, "blobMin": 4096},
+{"schema": "nnnotes.task/1", "id": "unity.export:membercard_assets_membercard_100101:-4153…",
+ "stage": {"name": "unity.export", "version": 2},
+ "params": {"blobMin": 4096, "png": {"level": 6}},
  "atoms": {"png.encode": "pillow-12.3.0/1", "texture.decode": "unitypy-1.25.3/1"},
  "inputs": [{"role": "bundle", "sha256": "…", "size": 123456, "name": "membercard_…_3fa…c2.bundle",
              "locators": [{"kind": "depot"}, {"kind": "download", "path": "bundles/membercard_…_3fa…c2.bundle"}]}],
- "context": {"scripts": {"CAB-…:12345": "Assembly-CSharp|Fwk.Sound|SplitAcbData"}},
+ "context": {"unit": "CAB-2f1e…:-4153…", "bundle": "membercard_assets_membercard_100101",
+             "scripts": {"CAB-…:12345": "Assembly-CSharp|Fwk.Sound|SplitAcbData"}},
  "key": "…", "cost": {"cpuSeconds": 1.2, "peakBytes": 450000000}}
 ```
 
@@ -97,7 +99,7 @@ One output file ([artifact.schema.json](https://github.com/MetaSekaiLab/nnnotes/
 ```json
 {"id": "CAB-…:-4153…#image",
  "content": {"sha256": "…", "size": 1234, "mediaType": "image/png", "ext": "png"},
- "provenance": {"stage": {"name": "unity.export", "version": 1, "params": "<key hash of the params>"},
+ "provenance": {"stage": {"name": "unity.export", "version": 2, "params": "<key hash of the params>"},
                 "atoms": {"texture.decode": "…", "png.encode": "…"},
                 "inputs": [{"role": "bundle", "sha256": "…"}],
                 "object": {"file": "CAB-…", "pathId": -4153, "classId": 28, "class": "Texture2D",
@@ -221,7 +223,6 @@ Documents written by particular stages (artifacts of no object: their ids are `<
 | `nnnotes.census/2` | `unity.census` | [census.schema.json](https://github.com/MetaSekaiLab/nnnotes/blob/main/src/nnnotes/schemas/census.schema.json) |
 | `nnnotes.scripts/1` | `link.scripts` | [scripts.schema.json](https://github.com/MetaSekaiLab/nnnotes/blob/main/src/nnnotes/schemas/scripts.schema.json) |
 | `nnnotes.addresses/1` | `link.addresses` | [addresses.schema.json](https://github.com/MetaSekaiLab/nnnotes/blob/main/src/nnnotes/schemas/addresses.schema.json) |
-| `nnnotes.artifacts/1` | `link.artifacts` | [artifacts.schema.json](https://github.com/MetaSekaiLab/nnnotes/blob/main/src/nnnotes/schemas/artifacts.schema.json) |
 | `nnnotes.view/1` | `view.<name>` | [view.schema.json](https://github.com/MetaSekaiLab/nnnotes/blob/main/src/nnnotes/schemas/view.schema.json) |
 
 The catalog versions of a depot, `nnnotes.catalogs/1` ([catalogs.schema.json](https://github.com/MetaSekaiLab/nnnotes/blob/main/src/nnnotes/schemas/catalogs.schema.json),

docs/schemas.md

@@ -16,7 +16,6 @@ schemas.load("plan")  # the schema as a dict
 |---|---|---|
 | `addresses` | `nnnotes.addresses/1` | the address table of a catalog version and the censuses of its bundles |
 | `artifact` | `nnnotes.artifact/1` | the content, provenance and semantics of one output file |
-| `artifacts` | `nnnotes.artifacts/1` | the artifact table: the artifacts of every object, with content id, size and extension |
 | `catalog-diff` | `nnnotes.catalog-diff/1` | the difference between two catalog versions (`catalog diff`) |
 | `catalog-index` | `nnnotes.catalog-index/1` | the index of a catalog pair: remote and APK catalogs, every location in catalog order |
 | `catalogs` | `nnnotes.catalogs/1` | the catalog versions of a depot (`catalog versions`) |