Extraction Hardening

README.md

@@ -49,7 +49,7 @@ The shared CLI exposes these project utilities:
 sow-toolkit build
 sow-toolkit build-module
 sow-toolkit build-haks [--hak <name>] [--archive <name>] [--source-manifest <path>] [--plan-only] [--skip-music] [--music-dataset <id>]
-sow-toolkit extract [<module-or-hak-file> ...]
+sow-toolkit extract [<build-relative-archive-or-glob> ...]
 sow-toolkit validate
 sow-toolkit compare
 sow-toolkit apply-hak-manifest [<manifest-path>]
@@ -185,10 +185,12 @@ scripts:
 
 extract:
   layout: nwn_canonical_json
-  hak_discovery: build_glob      # or configured_haks
+  archives:
+    - "{module.resref}.mod"
   cleanup_stale: true
+  consume_archives: false
   ignore_extensions: []
-  delete_module_archive_after_success: false
+  delete_module_archive_after_success: false # deprecated compatibility alias
 
 topdata:
   build: "{paths.build}/topdata"
@@ -222,11 +224,29 @@ cache paths must stay relative to the repository root unless a specific setting
 documents otherwise.
 
 Extraction is deliberately guarded because it writes source files from binary
-archives. Module resources require a configured `paths.source`; HAK assets
-require a configured `paths.assets`; both roots must resolve to safe subtrees.
-If a root is unset or resolves to the repository root, extraction fails before
-writing instead of creating extension directories like `mdl/` or `png/` at the
-repo top level. Stale cleanup uses the same safe-root rule.
+archives. `extract.archives` is a list of glob patterns relative to
+`paths.build`; the default is only the configured module `.mod`. HAK extraction
+is opt-in, for example:
+
+```yaml
+extract:
+  archives:
+    - "{module.resref}.mod"
+    - "sow_over*.hak"
+```
+
+Module resources require a configured `paths.source`; HAK assets require a
+configured `paths.assets`; both roots must resolve to safe subtrees. If a root
+is unset or resolves to the repository root, extraction fails before writing
+instead of creating extension directories like `mdl/` or `png/` at the repo top
+level. `.erf` files are rejected by extraction because they do not contain
+`module.ifo`, so they cannot safely update module-level area membership.
+
+`consume_archives: true` deletes the selected build archive files only after the
+entire extraction succeeds. The older `delete_module_archive_after_success`
+setting remains as a module-only compatibility alias when `consume_archives` is
+not set. Stale cleanup is scoped to roots actually touched by extracted
+resources, so the default module-only extraction does not prune assets.
 
 Music defaults (used when not explicitly configured):