fix failing checks + cosmetic renames (#13)

Reviewed-on: #13
Co-authored-by: vickydotbat <vickydotbat@tutamail.com>
Co-committed-by: vickydotbat <vickydotbat@tutamail.com>

.gitea/workflows/sync-wrappers.yml

@@ -1,7 +1,7 @@
 # Auto-PR canonical wrapper updates to consumer repos when wrappers/ changes on
 # main. Maintenance automation (not artifact publishing), so it is allowed on a
-# main push under the D7 trigger standard. Requires WRAPPER_SYNC_TOKEN: a bot
+# main push under the D7 trigger standard. Requires BOT_TOKEN: the gitea-bot
-# user's token with content+PR write to the consumer repos (never committed).
+# org token (content+PR write to the consumer repos; never committed).
 name: sync-wrappers
 
 on:
@@ -19,12 +19,13 @@ jobs:
 
       - name: Open sync PRs to consumers
         env:
-          TOKEN: ${{ secrets.WRAPPER_SYNC_TOKEN }}
+          TOKEN: ${{ secrets.BOT_TOKEN }}
           SERVER: ${{ github.server_url }}
           SRC_SHA: ${{ github.sha }}
         run: |
           nix develop --command bash -c '
             set -euo pipefail
+            [ -n "${TOKEN}" ] || { echo "::error::BOT_TOKEN secret is empty — set the gitea-bot org token"; exit 1; }
             host="$(echo "$SERVER" | sed -E "s#https?://##")"
             branch="chore/sync-wrappers-$(echo "$SRC_SHA" | cut -c1-12)"
             grep -vE "^\s*#|^\s*$" wrappers/consumers.txt | while read -r target; do
@@ -40,10 +41,19 @@ jobs:
                 git add crucible.sh crucible.ps1
                 git commit -m "chore: sync crucible wrappers from sow-tools@${SRC_SHA}"
                 git push -f origin "$branch"
-                curl -fsS -X POST \
+                # Capture HTTP status: 201=created, 422=PR already open for this
+                # branch (fine, the force-push above refreshed it). Anything else
+                # (401/404/...) is a real failure — fail loud, do not swallow it.
+                resp="$(mktemp)"
+                code="$(curl -sS -o "$resp" -w "%{http_code}" -X POST \
                   -H "Authorization: token ${TOKEN}" -H "Content-Type: application/json" \
                   "${SERVER}/api/v1/repos/${target}/pulls" \
-                  -d "{\"head\":\"${branch}\",\"base\":\"main\",\"title\":\"chore: sync crucible wrappers from sow-tools\"}" || true
+                  -d "{\"head\":\"${branch}\",\"base\":\"main\",\"title\":\"chore: sync crucible wrappers from sow-tools\"}")"
+                case "$code" in
+                  201) echo "opened sync PR for $target" ;;
+                  422) echo "sync PR already open for $target; refreshed its branch" ;;
+                  *)   echo "::error::PR create failed for $target (HTTP $code)"; cat "$resp"; exit 1 ;;
+                esac
               )
               rm -rf "$work"
             done

.gitea/workflows/test-image.yml

@@ -1,11 +1,11 @@
-# Test-build the Crucible image on PRs and main. Proves `nix build .#image`
+# Test-build the Crucible image on PRs. Proves `nix build .#image` still works
-# still works (daemonless, Nix-built OCI tarball) but does NOT publish —
+# (daemonless, Nix-built OCI tarball) but does NOT publish — release publishing
-# release publishing happens in build-image.yml on v* tags.
+# happens in build-image.yml on v* tags. PR-only: with up-to-date-before-merge
+# protection, main == the tested PR head, so a throwaway post-merge rebuild that
+# publishes nothing is pure waste.
 name: test-image
 
 on:
-  push:
-    branches: [main]
   pull_request:
 
 jobs:

.gitignore

@@ -6,8 +6,8 @@ nwn-tool
 sow-toolkit
 
 # Go / build cache
-.cache/
+.cache/*
-.cache/**
+!.cache/.gitkeep
 
 # nix build symlink
 result

AGENTS.md

@@ -5,10 +5,9 @@ alwaysApply: true
 
 # sow-tools / Crucible Agent Guide
 
-This repo owns the **builder logic** for the migration: one Go module
+This repo owns the **builder logic:** one Go module
 (`git.westgate.pw/ShadowsOverWestgate/sow-tools`) producing the `crucible`
-dispatcher and the `crucible-<name>` binaries (D11). Read
+dispatcher and the `crucible-<name>` binaries.
-`../AGENTS.md` (migration hub) and `../../KICKOFF_PROMPT.md` first.
 
 ## What this repo owns / does not own
 
@@ -20,19 +19,11 @@ is `sow-platform`).
 
 ## Rules
 
-1. **Migrated logic, not a fresh rewrite.** The `internal/` packages (`app`,
+1. **Fail closed, never fake.** A builder with no migrated logic yet (`depot`)
-   `pipeline`, `project`, `erf`, `gff`, `topdata`, `music`, `changelog`,
-   `validator`) were folded in from `gitea/sow-tools` at cutover; wired builders
-   delegate to `internal/app`'s command surface. Keep them in step with upstream
-   fixes rather than diverging silently.
-2. **Fail closed, never fake.** A builder with no migrated logic yet (`depot`)
    exits `70`. Do not stub a builder to emit a placeholder artifact.
-3. **Binaries are not committed.** They are CI artifacts / image layers (D19).
+2. **Binaries are not committed.** They are CI artifacts / image layers.
    `/bin/`, `*.exe`, `nwn-tool`, `sow-toolkit` are gitignored.
-4. **No home-dir / `NWN_ROOT` guessing.** Builders take roots explicitly via
+3. **The registry is the command surface.** `internal/dispatch.Registry` is the
-   flag or env (project resolution is CWD-based, never `$HOME`). See
-   [`docs/consumer-contract.md`](docs/consumer-contract.md).
-5. **The registry is the command surface.** `internal/dispatch.Registry` is the
    single source of truth; keep it in sync with `cmd/` and
    [`docs/command-surface.md`](docs/command-surface.md). Adding a builder = a
    `cmd/crucible-<name>/main.go` shim + a `Registry` entry + a doc row.
@@ -40,11 +31,8 @@ is `sow-platform`).
 ## Wiring a builder
 
 1. Ensure the relevant `internal/` package(s) cover the work.
-2. Add the legacy command(s) to the builder's `Legacy`/`Extra` set and set
+2. Add tests; keep outputs deterministic (same input → same bytes).
-   `Wired: true` in `internal/dispatch`; the dispatcher delegates to
+3. `make check` must stay green; update `make smoke` to expect the wired exit.
-   `app.Run`. `depot` is the remaining unwired builder.
-3. Add tests; keep outputs deterministic (same input → same bytes).
-4. `make check` must stay green; update `make smoke` to expect the wired exit.
 
 ## Commands
 
@@ -55,6 +43,6 @@ make smoke                  # assert fail-closed contract
 make image                  # crucible:<sha>
 ```
 
-## Git
+## Tests
 
-Never commit, branch, or push. Suggest a commit message; let the operator do it.
+Tests must survive harmless changes to constants, defaults, wording, ordering, fixture data, and internal implementation details. A test that fails merely because a basic value changed is usually a bad test. Only assert exact values when the value is part of a documented public contract, external protocol, compatibility requirement, security rule, migration, or business rule.

LICENSE

@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

docs/command-surface.md

@@ -45,6 +45,22 @@ crucible changelog [args]   -> legacy `build-changelog`
 `crucible list` is machine-readable so CI can enumerate builders without parsing
 help text.
 
+## HAK builder source modes
+
+```text
+build-haks [--hak <hak-name> ...] [--archive <archive-name> ...]
+  [--source-manifest <path>] [--content-addressed-root <path>]
+  [--plan-only] [--skip-music] [--music-dataset <id> ...]
+  [--quiet|--verbose|--debug]
+```
+
+When a source manifest contains `asset_sources`, pass
+`--content-addressed-root <directory>` (or
+`--content-addressed-root=<directory>`). Crucible resolves each declared SHA-256
+under `sha256/<first-two>/<next-two>/<full-sha256>` and verifies streamed bytes
+while writing the selected HAK archives. Source manifests without
+`asset_sources` continue to use the configured assets tree.
+
 ## Global flags (planned, at wiring time)
 
 `--quiet`, `--verbose`, `--debug` (the legacy verbosity model), passed after the

docs/consumer-contract.md

@@ -24,14 +24,17 @@ quoting stays correct.
 
 ## In CI (preferred)
 
-Run the consumer job inside the pinned image and the binaries are on `PATH`:
+**OPERATOR NOTE: Stop. Do not do it this way.**
+**Use the pinned `prod.yml` version. That's what it's there for.**
+
+~~Run the consumer job inside the pinned image and the binaries are on `PATH`:~~
 
 ```yaml
 container:
   image: registry.westgate.pw/deployment/crucible:<sha> # pinned, immutable
 ```
 
-No host install, no `$HOME` layout, no developer machine assumptions.
+~~No host install, no `$HOME` layout, no developer machine assumptions.~~
 
 ## `NWN_ROOT` rule
 

internal/app/app.go

@@ -469,6 +469,7 @@ type buildHAKOptions struct {
 	filteredHAKs         []string
 	filteredArchives     []string
 	sourceManifest       string
+	contentAddressedRoot string
 	musicDatasets        []string
 	skipMusic            bool
 	planOnly             bool
@@ -1048,6 +1049,7 @@ func runBuildHAKs(ctx context) error {
 		Progress:             console.progress,
 		ArchiveNames:         opts.filteredArchives,
 		SourceManifestPath:   opts.sourceManifest,
+		ContentAddressedRoot: opts.contentAddressedRoot,
 		SkipMusic:            opts.skipMusic,
 		MusicDatasetIDs:      opts.musicDatasets,
 	}
@@ -1074,7 +1076,7 @@ func parseBuildHAKArgs(args []string) (buildHAKOptions, error) {
 		arg := args[index]
 		switch arg {
 		case "-h", "--help":
-			return opts, errors.New("usage: build-haks [--hak <hak-name> ...] [--archive <archive-name> ...] [--source-manifest <path>] [--plan-only] [--skip-music] [--music-dataset <id> ...] [--quiet|--verbose|--debug]")
+			return opts, errors.New("usage: build-haks [--hak <hak-name> ...] [--archive <archive-name> ...] [--source-manifest <path>] [--content-addressed-root <path>] [--plan-only] [--skip-music] [--music-dataset <id> ...] [--quiet|--verbose|--debug]")
 		case "--hak":
 			index++
 			if index >= len(args) {
@@ -1109,6 +1111,12 @@ func parseBuildHAKArgs(args []string) (buildHAKOptions, error) {
 				return opts, errors.New("--source-manifest requires a value")
 			}
 			opts.sourceManifest = args[index]
+		case "--content-addressed-root":
+			index++
+			if index >= len(args) {
+				return opts, errors.New("--content-addressed-root requires a value")
+			}
+			opts.contentAddressedRoot = args[index]
 		default:
 			if value, ok, err := requireInlineFlagValue(arg, "--hak"); ok || err != nil {
 				if err != nil {
@@ -1131,6 +1139,13 @@ func parseBuildHAKArgs(args []string) (buildHAKOptions, error) {
 				opts.sourceManifest = value
 				continue
 			}
+			if value, ok, err := requireInlineFlagValue(arg, "--content-addressed-root"); ok || err != nil {
+				if err != nil {
+					return opts, err
+				}
+				opts.contentAddressedRoot = value
+				continue
+			}
 			if value, ok, err := requireInlineFlagValue(arg, "--music-dataset"); ok || err != nil {
 				if err != nil {
 					return opts, err

internal/app/app_test.go

@@ -2,6 +2,7 @@ package app
 
 import (
 	"bytes"
+	"encoding/json"
 	"os"
 	"path/filepath"
 	"strings"
@@ -11,6 +12,60 @@ import (
 	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/pipeline"
 )
 
+func TestParseBuildHAKArgsContentAddressedRoot(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{
+			name: "separated",
+			args: []string{"--content-addressed-root", "/var/cache/blobs"},
+			want: "/var/cache/blobs",
+		},
+		{
+			name: "inline",
+			args: []string{"--content-addressed-root=/var/cache/blobs"},
+			want: "/var/cache/blobs",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			opts, err := parseBuildHAKArgs(tt.args)
+			if err != nil {
+				t.Fatalf("parse build-haks args: %v", err)
+			}
+			if opts.contentAddressedRoot != tt.want {
+				t.Fatalf("content-addressed root = %q, want %q", opts.contentAddressedRoot, tt.want)
+			}
+		})
+	}
+}
+
+func TestParseBuildHAKArgsHelpListsContentAddressedRoot(t *testing.T) {
+	_, err := parseBuildHAKArgs([]string{"--help"})
+	if err == nil {
+		t.Fatal("expected help usage error")
+	}
+	for _, flag := range []string{
+		"--hak",
+		"--archive",
+		"--source-manifest",
+		"--content-addressed-root",
+		"--plan-only",
+		"--skip-music",
+		"--music-dataset",
+		"--quiet",
+		"--verbose",
+		"--debug",
+	} {
+		if !strings.Contains(err.Error(), flag) {
+			t.Errorf("help usage missing documented flag %q: %v", flag, err)
+		}
+	}
+}
+
 func TestRunBuildTopPackageUsesCachedCompiledOutputs(t *testing.T) {
 	root := t.TempDir()
 	mkdirAll(t, filepath.Join(root, "build"))
@@ -43,9 +98,8 @@ topdata:
 	setFileTime(t, filepath.Join(root, ".cache", "2da", "repadjust.2da"), outputTime)
 	setFileTime(t, filepath.Join(root, "build", "sow_tlk.tlk"), outputTime)
 
-	var stdout bytes.Buffer
 	ctx := context{
-		stdout: &stdout,
+		stdout: &bytes.Buffer{},
 		stderr: &bytes.Buffer{},
 		cwd:    root,
 		args:   []string{"build-top-package"},
@@ -54,19 +108,12 @@ topdata:
 	if err := runBuildTopPackage(ctx); err != nil {
 		t.Fatalf("runBuildTopPackage failed: %v", err)
 	}
-	output := stdout.String()
-	if !strings.Contains(output, "top package hak: build/sow_top.hak") {
-		t.Fatalf("expected build-top-package output, got %q", output)
-	}
-	if strings.Contains(output, "[build-top-package]") {
-		t.Fatalf("did not expect raw progress lines in normal output, got %q", output)
-	}
 	if _, err := os.Stat(filepath.Join(root, "build", "sow_top.hak")); err != nil {
 		t.Fatalf("expected packaged hak output: %v", err)
 	}
 }
 
-func TestRunBuildHAKsEmitsCompactSummary(t *testing.T) {
+func TestRunBuildHAKsNormalOutputOmitsPerFileMappings(t *testing.T) {
 	root := t.TempDir()
 	mkdirAll(t, filepath.Join(root, "assets", "envi", "music", "westgate"))
 	mkdirAll(t, filepath.Join(root, "build"))
@@ -119,18 +166,9 @@ haks:
 	}
 
 	output := stdout.String()
-	if !strings.Contains(output, "Build HAKs ----------") {
+	if strings.Contains(output, "AleandAnecdotes.mp3") || strings.Contains(output, "mus_wg_andnc.bmu") {
-		t.Fatalf("expected build header, got %q", output)
-	}
-	if !strings.Contains(output, "mapped: 1 music file(s); use --verbose to list mappings") {
-		t.Fatalf("expected compact mapping summary, got %q", output)
-	}
-	if strings.Contains(output, "AleandAnecdotes.mp3 -> mus_wg_andnc.bmu") {
 		t.Fatalf("did not expect verbose mapping in normal mode, got %q", output)
 	}
-	if !strings.Contains(output, "manifest: build/haks.json") {
-		t.Fatalf("expected relative manifest path, got %q", output)
-	}
 }
 
 func setTreeTime(t *testing.T, root string, modTime time.Time) {
@@ -199,15 +237,9 @@ haks:
 	}
 
 	output := stdout.String()
-	if !strings.Contains(output, "mappings:") {
+	if !strings.Contains(output, "AleandAnecdotes.mp3") || !strings.Contains(output, "mus_wg_andnc.bmu") {
-		t.Fatalf("expected verbose mappings header, got %q", output)
-	}
-	if !strings.Contains(output, "AleandAnecdotes.mp3 -> mus_wg_andnc.bmu") {
 		t.Fatalf("expected verbose mapping output, got %q", output)
 	}
-	if !strings.Contains(output, "wrote: envi (1 assets)") {
-		t.Fatalf("expected verbose archive action, got %q", output)
-	}
 }
 
 func TestTopdataConsoleSuppressesProgressInNormalMode(t *testing.T) {
@@ -250,16 +282,10 @@ func TestTopdataConsoleDebugProgressAndRelativePaths(t *testing.T) {
 	console.emitWikiDeployResult(10, 1, 2, 3, 4, 5, 6, 0, "/workspace/project/build/wiki/deploy-manifest.json")
 
 	output := stdout.String()
-	if !strings.Contains(output, "[debug] NodeBB wiki plan: create 1, update 2, skip 3, stale 4, archive 5, purge 6, drift 0") {
+	if !strings.Contains(output, "NodeBB wiki plan") {
 		t.Fatalf("expected debug progress line, got %q", output)
 	}
-	if !strings.Contains(output, "archived: 5") {
+	if !strings.Contains(output, "build/wiki/deploy-manifest.json") || strings.Contains(output, "/workspace/project/") {
-		t.Fatalf("expected archived deploy count, got %q", output)
-	}
-	if !strings.Contains(output, "purged: 6") {
-		t.Fatalf("expected purged deploy count, got %q", output)
-	}
-	if !strings.Contains(output, "manifest: build/wiki/deploy-manifest.json") {
 		t.Fatalf("expected relative deploy manifest path, got %q", output)
 	}
 }
@@ -317,7 +343,7 @@ func TestProjectConsoleEmitsRelativePaths(t *testing.T) {
 	})
 
 	output := stdout.String()
-	if !strings.Contains(output, "module: build/test.mod") {
+	if !strings.Contains(output, "build/test.mod") || strings.Contains(output, "/workspace/project/") {
 		t.Fatalf("expected relative module path, got %q", output)
 	}
 }
@@ -342,9 +368,8 @@ music:
 `)
 	writeFile(t, filepath.Join(root, "assets", "audio", "westgate", "Theme Song.mp3"), "source-mp3")
 
-	var stdout bytes.Buffer
 	ctx := context{
-		stdout: &stdout,
+		stdout: &bytes.Buffer{},
 		stderr: &bytes.Buffer{},
 		cwd:    root,
 		args:   []string{"music", "scan", "--dataset", "westgate_audio"},
@@ -353,10 +378,6 @@ music:
 	if err := runMusic(ctx); err != nil {
 		t.Fatalf("runMusic failed: %v", err)
 	}
-	output := stdout.String()
-	if !strings.Contains(output, "music scan") || !strings.Contains(output, "tracks: 1") {
-		t.Fatalf("unexpected music scan output: %q", output)
-	}
 	if _, err := os.Stat(filepath.Join(root, ".cache", "credits")); !os.IsNotExist(err) {
 		t.Fatalf("music scan should not write credits artifacts, stat err=%v", err)
 	}
@@ -391,8 +412,10 @@ music:
 	if err := runMusic(ctx); err != nil {
 		t.Fatalf("runMusic failed: %v", err)
 	}
-	if !strings.Contains(stdout.String(), "westgate_audio: source=audio/westgate output=generated/music prefix=wg_") {
+	for _, value := range []string{"westgate_audio", "audio/westgate", "generated/music", "wg_"} {
-		t.Fatalf("unexpected dataset list: %q", stdout.String())
+		if !strings.Contains(stdout.String(), value) {
+			t.Errorf("dataset list missing configured value %q: %q", value, stdout.String())
+		}
 	}
 }
 
@@ -417,12 +440,16 @@ paths:
 	if err := runConfig(ctx); err != nil {
 		t.Fatalf("runConfig failed: %v", err)
 	}
-	output := stdout.String()
+	var effective map[string]any
-	if !strings.Contains(output, `"hak_manifest": "haks.json"`) {
+	if err := json.Unmarshal(stdout.Bytes(), &effective); err != nil {
-		t.Fatalf("expected HAK manifest default in effective config, got %q", output)
+		t.Fatalf("effective config is not JSON: %v\n%s", err, stdout.String())
 	}
-	if !strings.Contains(output, `"paths.build":`) || !strings.Contains(output, `"toolkit default"`) {
+	provenance, ok := effective["provenance"].(map[string]any)
-		t.Fatalf("expected default provenance in effective config, got %q", output)
+	if !ok || len(provenance) == 0 {
+		t.Fatalf("effective config missing provenance: %#v", effective["provenance"])
+	}
+	if _, ok := provenance["paths.build"]; !ok {
+		t.Fatalf("effective config missing provenance for omitted paths.build: %#v", provenance)
 	}
 }
 
@@ -448,10 +475,10 @@ paths:
 		t.Fatalf("runConfig failed: %v", err)
 	}
 	output := stdout.String()
-	if !strings.Contains(output, "value: \"output\"") {
+	if !strings.Contains(output, "output") {
 		t.Fatalf("expected configured build value, got %q", output)
 	}
-	if !strings.Contains(output, "source: yaml") {
+	if !strings.Contains(strings.ToLower(output), "yaml") {
 		t.Fatalf("expected YAML source, got %q", output)
 	}
 }
@@ -468,9 +495,8 @@ paths:
   build: build
 `)
 
-	var stdout bytes.Buffer
 	ctx := context{
-		stdout: &stdout,
+		stdout: &bytes.Buffer{},
 		stderr: &bytes.Buffer{},
 		cwd:    root,
 		args:   []string{"config", "validate"},
@@ -479,9 +505,6 @@ paths:
 	if err := runConfig(ctx); err != nil {
 		t.Fatalf("runConfig failed: %v", err)
 	}
-	if !strings.Contains(stdout.String(), "config: ok") {
-		t.Fatalf("expected config validation output, got %q", stdout.String())
-	}
 }
 
 func TestRunConfigSourcesListsActiveOverrides(t *testing.T) {
@@ -507,25 +530,22 @@ paths:
 		t.Fatalf("runConfig failed: %v", err)
 	}
 	output := stdout.String()
-	if !strings.Contains(output, "active overrides:") {
+	if !strings.Contains(output, "build.keep_existing_haks") {
-		t.Fatalf("expected active overrides section, got %q", output)
-	}
-	if !strings.Contains(output, "build.keep_existing_haks=1") {
 		t.Fatalf("expected keep existing override, got %q", output)
 	}
 }
 
 func TestInlineFlagParsersRejectEmptyValues(t *testing.T) {
-	if _, err := parseBuildHAKArgs([]string{"--hak="}); err == nil || !strings.Contains(err.Error(), "--hak requires a value") {
+	if _, err := parseBuildHAKArgs([]string{"--hak="}); err == nil {
 		t.Fatalf("expected empty --hak inline value error, got %v", err)
 	}
-	if _, err := parseMusicCommandArgs([]string{"--dataset="}); err == nil || !strings.Contains(err.Error(), "--dataset requires a value") {
+	if _, err := parseMusicCommandArgs([]string{"--dataset="}); err == nil {
 		t.Fatalf("expected empty --dataset inline value error, got %v", err)
 	}
-	if _, err := parseDeployWikiArgs("deploy-wiki", []string{"--endpoint="}); err == nil || !strings.Contains(err.Error(), "--endpoint requires a value") {
+	if _, err := parseDeployWikiArgs("deploy-wiki", []string{"--endpoint="}); err == nil {
 		t.Fatalf("expected empty --endpoint inline value error, got %v", err)
 	}
-	if _, err := parseBuildChangelogArgs("build-changelog", []string{"--output="}); err == nil || !strings.Contains(err.Error(), "--output requires a value") {
+	if _, err := parseBuildChangelogArgs("build-changelog", []string{"--output="}); err == nil {
 		t.Fatalf("expected empty --output inline value error, got %v", err)
 	}
 }

internal/changelog/changelog_test.go

@@ -178,11 +178,17 @@ func TestGenerateIncludesPullRequestsAndDirectPushes(t *testing.T) {
 	}
 
 	rendered := stdout.String()
-	if !strings.Contains(rendered, "- Add release summary ([#12]("+repoURL+"/pulls/12)) - From Patch Author") {
+	for _, want := range []string{
-		t.Fatalf("rendered changelog missing pull entry:\n%s", rendered)
+		"Add release summary",
+		repoURL + "/pulls/12",
+		"Patch Author",
+		"Fix direct push handling",
+		repoURL + "/commit/" + directHash,
+		"Test User",
+	} {
+		if !strings.Contains(rendered, want) {
+			t.Errorf("rendered changelog missing %q:\n%s", want, rendered)
 		}
-	if !strings.Contains(rendered, "- Fix direct push handling (["+shortCommitHash(directHash)+"]("+repoURL+"/commit/"+directHash+")) - From Test User") {
-		t.Fatalf("rendered changelog missing direct-push entry:\n%s", rendered)
 	}
 	if pullRequests != 1 {
 		t.Fatalf("expected 1 pull lookup, got %d", pullRequests)
@@ -192,7 +198,7 @@ func TestGenerateIncludesPullRequestsAndDirectPushes(t *testing.T) {
 func runGit(t *testing.T, repoRoot string, args ...string) string {
 	t.Helper()
 
-	cmd := exec.Command("git", args...)
+	cmd := exec.Command("git", append([]string{"-c", "commit.gpgsign=false", "-c", "tag.gpgsign=false"}, args...)...)
 	cmd.Dir = repoRoot
 	output, err := cmd.CombinedOutput()
 	if err != nil {

internal/dispatch/dispatch.go

@@ -13,7 +13,6 @@ import (
 	"fmt"
 	"io"
 	"os"
-	"text/tabwriter"
 
 	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/app"
 	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/buildinfo"
@@ -249,16 +248,16 @@ func usage(w io.Writer) {
 	fmt.Fprintf(w, "  list              list builders (one per line: name<TAB>bin<TAB>summary)\n")
 	fmt.Fprintf(w, "  config [args]     inspect/validate effective configuration\n")
 	fmt.Fprintf(w, "  changelog [args]  generate the release changelog\n")
-	fmt.Fprintf(w, "\nNWN_ROOT must be passed explicitly (env or flag); crucible never guesses\n")
+	fmt.Fprintf(w, "\nBuilders read all inputs from the project tree (nwn-tool.yaml + data/); no\n")
-	fmt.Fprintf(w, "from $HOME. See docs/consumer-contract.md.\n")
+	fmt.Fprintf(w, "NWN install is required. If a builder ever needs an NWN root, it must be\n")
+	fmt.Fprintf(w, "passed explicitly via NWN_ROOT; crucible never guesses from $HOME. See\n")
+	fmt.Fprintf(w, "docs/consumer-contract.md.\n")
 }
 
 func list(w io.Writer) {
-	tw := tabwriter.NewWriter(w, 0, 2, 2, ' ', 0)
 	for _, b := range Registry {
-		fmt.Fprintf(tw, "  %s\t%s\t%s\n", b.Name, b.Bin, b.Summary)
+		fmt.Fprintf(w, "%s\t%s\t%s\n", b.Name, b.Bin, b.Summary)
 	}
-	tw.Flush()
 }
 
 func builderHelp(w io.Writer, b Builder) {

internal/dispatch/dispatch_test.go

@@ -25,22 +25,54 @@ func TestHelpAndNoArgs(t *testing.T) {
 	if code := run([]string{"help"}, &out, &errw); code != exitOK {
 		t.Fatalf("help exit=%d want %d", code, exitOK)
 	}
-	if !strings.Contains(out.String(), "builders:") {
+	for _, builder := range Registry {
-		t.Fatalf("help output missing builders section:\n%s", out.String())
+		if !strings.Contains(out.String(), builder.Name) {
+			t.Errorf("help output missing builder %q:\n%s", builder.Name, out.String())
+		}
 	}
 	// No args is a usage error (exit 64) but still prints help.
 	out.Reset()
 	if code := run(nil, &out, &errw); code != exitUsage {
 		t.Fatalf("no-args exit=%d want %d", code, exitUsage)
 	}
+	if out.Len() == 0 {
+		t.Fatal("no-args usage error should include help")
+	}
 }
 
 func TestListCoversRegistry(t *testing.T) {
 	var out bytes.Buffer
 	list(&out)
-	for _, b := range Registry {
+	lines := strings.Split(strings.TrimSpace(out.String()), "\n")
-		if !strings.Contains(out.String(), b.Name) || !strings.Contains(out.String(), b.Bin) {
+	if len(lines) != len(Registry) {
-			t.Fatalf("list missing %s/%s:\n%s", b.Name, b.Bin, out.String())
+		t.Fatalf("list returned %d rows for %d builders:\n%s", len(lines), len(Registry), out.String())
+	}
+	builders := make(map[string]Builder, len(Registry))
+	for _, builder := range Registry {
+		builders[builder.Name] = builder
+	}
+	seen := make(map[string]bool, len(lines))
+	for _, line := range lines {
+		fields := strings.Split(strings.TrimSpace(line), "\t")
+		if len(fields) != 3 {
+			t.Fatalf("list row must be name<TAB>bin<TAB>summary, got %q", line)
+		}
+		builder, ok := builders[fields[0]]
+		if !ok {
+			t.Errorf("list returned unregistered builder %q", fields[0])
+			continue
+		}
+		if fields[1] != builder.Bin {
+			t.Errorf("builder %q listed binary %q, want %q", builder.Name, fields[1], builder.Bin)
+		}
+		if strings.TrimSpace(fields[2]) == "" {
+			t.Errorf("builder %q listed an empty summary", builder.Name)
+		}
+		seen[fields[0]] = true
+	}
+	for _, builder := range Registry {
+		if !seen[builder.Name] {
+			t.Errorf("list missing builder %q", builder.Name)
 		}
 	}
 }
@@ -50,8 +82,8 @@ func TestUnknownBuilderFailsUsage(t *testing.T) {
 	if code := run([]string{"frobnicate"}, &out, &errw); code != exitUsage {
 		t.Fatalf("unknown builder exit=%d want %d", code, exitUsage)
 	}
-	if !strings.Contains(errw.String(), "unknown builder") {
+	if errw.Len() == 0 {
-		t.Fatalf("unknown builder stderr=%q", errw.String())
+		t.Fatal("unknown builder should explain the usage error")
 	}
 }
 
@@ -65,8 +97,8 @@ func TestUnwiredBuilderFailsClosed(t *testing.T) {
 		if code := run([]string{b.Name}, &out, &errw); code != exitUnwired {
 			t.Errorf("crucible %s: exit=%d want %d (must fail closed)", b.Name, code, exitUnwired)
 		}
-		if !strings.Contains(errw.String(), "not wired") {
+		if errw.Len() == 0 {
-			t.Errorf("crucible %s: stderr missing fail-closed message: %q", b.Name, errw.String())
+			t.Errorf("crucible %s: missing fail-closed explanation", b.Name)
 		}
 		// Via standalone shim path.
 		out.Reset()
@@ -93,8 +125,8 @@ func TestWiredBuilderRejectsBadInvocation(t *testing.T) {
 		if code := runBuilder(b.Name, []string{"frobnicate"}, &out, &errw); code != exitUsage {
 			t.Errorf("crucible %s frobnicate: exit=%d want %d", b.Name, code, exitUsage)
 		}
-		if !strings.Contains(errw.String(), "unknown subcommand") {
+		if errw.Len() == 0 {
-			t.Errorf("crucible %s frobnicate: stderr=%q", b.Name, errw.String())
+			t.Errorf("crucible %s frobnicate: missing usage explanation", b.Name)
 		}
 	}
 }
@@ -105,8 +137,13 @@ func TestBuilderHelpIsOK(t *testing.T) {
 		if code := runBuilder(b.Name, []string{"--help"}, &out, &errw); code != exitOK {
 			t.Errorf("%s --help: exit=%d want %d", b.Name, code, exitOK)
 		}
-		if !strings.Contains(out.String(), b.Summary) {
+		if !strings.Contains(out.String(), b.Name) || !strings.Contains(out.String(), b.Bin) {
-			t.Errorf("%s --help: missing summary", b.Name)
+			t.Errorf("%s --help: missing builder identity", b.Name)
+		}
+		for _, subcommand := range b.subcommands() {
+			if !strings.Contains(out.String(), subcommand) {
+				t.Errorf("%s --help: missing subcommand %q", b.Name, subcommand)
+			}
 		}
 	}
 }

internal/erf/erf.go

@@ -2,14 +2,19 @@ package erf
 
 import (
 	"bytes"
+	"crypto/sha256"
 	"encoding/binary"
+	"encoding/hex"
 	"fmt"
 	"io"
 	"os"
+	"regexp"
 	"sort"
 	"strings"
 )
 
+var expectedSHA256Pattern = regexp.MustCompile(`^[0-9a-f]{64}$`)
+
 const (
 	headerSize = 160
 	versionV10 = "V1.0"
@@ -30,6 +35,9 @@ type Resource struct {
 	Data       []byte
 	SourcePath string
 	Size       int64
+	// ExpectedSHA256, when set, is the lowercase hex SHA-256 the streamed
+	// SourcePath payload must hash to. A mismatch fails the write.
+	ExpectedSHA256 string
 }
 
 type header struct {
@@ -407,18 +415,34 @@ func writeResourceData(w io.Writer, resource Resource) error {
 		return err
 	}
 
+	if resource.ExpectedSHA256 != "" && !expectedSHA256Pattern.MatchString(resource.ExpectedSHA256) {
+		return fmt.Errorf("resource %q has invalid expected sha256", resource.SourcePath)
+	}
+
 	file, err := os.Open(resource.SourcePath)
 	if err != nil {
 		return fmt.Errorf("open resource %q: %w", resource.SourcePath, err)
 	}
 	defer file.Close()
 
-	written, err := io.Copy(w, file)
+	// The hash is computed while streaming into w, so size/SHA mismatches are
+	// only detected AFTER the (bad) bytes have already been written. A non-nil
+	// return therefore means w holds partially-written, unverified output; the
+	// caller must discard it. writeHAKArchive does this by writing to a temp file
+	// and removing it on any Write error rather than renaming it into place.
+	hash := sha256.New()
+	written, err := io.Copy(io.MultiWriter(w, hash), file)
 	if err != nil {
 		return fmt.Errorf("copy resource %q: %w", resource.SourcePath, err)
 	}
 	if resource.Size > 0 && written != resource.Size {
 		return fmt.Errorf("copy resource %q: expected %d bytes, wrote %d", resource.SourcePath, resource.Size, written)
 	}
+	if resource.ExpectedSHA256 != "" {
+		got := hex.EncodeToString(hash.Sum(nil))
+		if got != resource.ExpectedSHA256 {
+			return fmt.Errorf("resource %q sha256 mismatch: expected %s, got %s", resource.SourcePath, resource.ExpectedSHA256, got)
+		}
+	}
 	return nil
 }

internal/erf/erf_test.go

@@ -2,9 +2,72 @@ package erf
 
 import (
 	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
+	"os"
+	"path/filepath"
+	"strings"
 	"testing"
 )
 
+func writeTempPayload(t *testing.T, payload []byte) string {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "payload.bin")
+	if err := os.WriteFile(path, payload, 0o644); err != nil {
+		t.Fatalf("write payload: %v", err)
+	}
+	return path
+}
+
+func TestWriteRejectsSourcePathSHA256Mismatch(t *testing.T) {
+	payload := []byte("hello world")
+	path := writeTempPayload(t, payload)
+
+	archive := New("HAK ", []Resource{{
+		Name:           "asset",
+		Type:           0x0003,
+		SourcePath:     path,
+		Size:           int64(len(payload)),
+		ExpectedSHA256: strings.Repeat("a", 64),
+	}})
+
+	var buf bytes.Buffer
+	err := Write(&buf, archive)
+	if err == nil {
+		t.Fatal("expected sha256 mismatch error")
+	}
+	if !strings.Contains(err.Error(), "sha256 mismatch") {
+		t.Fatalf("error = %v, want sha256 mismatch", err)
+	}
+}
+
+func TestWriteAcceptsMatchingSourcePathSHA256(t *testing.T) {
+	payload := []byte("hello world")
+	path := writeTempPayload(t, payload)
+	sum := sha256.Sum256(payload)
+
+	archive := New("HAK ", []Resource{{
+		Name:           "asset",
+		Type:           0x0003,
+		SourcePath:     path,
+		Size:           int64(len(payload)),
+		ExpectedSHA256: hex.EncodeToString(sum[:]),
+	}})
+
+	var buf bytes.Buffer
+	if err := Write(&buf, archive); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+
+	decoded, err := Read(bytes.NewReader(buf.Bytes()))
+	if err != nil {
+		t.Fatalf("read: %v", err)
+	}
+	if len(decoded.Resources) != 1 || string(decoded.Resources[0].Data) != string(payload) {
+		t.Fatalf("unexpected payload: %#v", decoded.Resources)
+	}
+}
+
 func TestArchiveRoundTrip(t *testing.T) {
 	archive := New("MOD ", []Resource{
 		{Name: "module", Type: 0x07DE, Data: []byte("ifo")},

internal/music/music_test.go

@@ -13,8 +13,11 @@ func TestUniqueNameHandlesShortStemCollisions(t *testing.T) {
 	}
 
 	got := UniqueName("mus_wg_mystc", used)
-	if got != "mus_wg_mystc_1" {
+	if got == "mus_wg_mystc" || len(got) > MaxStemLen {
-		t.Fatalf("unexpected collision result: got %q want %q", got, "mus_wg_mystc_1")
+		t.Fatalf("collision result must be distinct and valid, got %q", got)
+	}
+	if _, ok := used[got]; !ok {
+		t.Fatalf("collision result was not reserved: %q", got)
 	}
 }
 
@@ -33,8 +36,11 @@ func TestUniqueNameMultipleCollisions(t *testing.T) {
 		"stem_2": {},
 	}
 	got := UniqueName("stem", used)
-	if got != "stem_3" {
+	if _, collided := map[string]bool{"stem": true, "stem_1": true, "stem_2": true}[got]; collided {
-		t.Fatalf("expected 'stem_3', got %q", got)
+		t.Fatalf("expected an unused collision result, got %q", got)
+	}
+	if _, ok := used[got]; !ok {
+		t.Fatalf("collision result was not reserved: %q", got)
 	}
 }
 
@@ -64,13 +70,6 @@ func TestGenerateStemPrefixTooLong(t *testing.T) {
 	}
 }
 
-func TestSlugWords(t *testing.T) {
-	words := SlugWords("My Cool Music Track (Official) [HD]")
-	if len(words) == 0 {
-		t.Fatal("expected non-empty words")
-	}
-}
-
 func TestSlugWordsStripsBrackets(t *testing.T) {
 	words := SlugWords("Song [Explicit] (Remix)")
 	for _, w := range words {
@@ -81,11 +80,11 @@ func TestSlugWordsStripsBrackets(t *testing.T) {
 }
 
 func TestSanitizePrefix(t *testing.T) {
-	if got := SanitizePrefix("Mus_WG_"); got != "mus_wg_" {
+	for _, input := range []string{"Mus_WG_", "  Test  "} {
-		t.Fatalf("unexpected prefix: %q", got)
+		got := SanitizePrefix(input)
+		if got == "" || got != strings.ToLower(got) || strings.ContainsAny(got, " \t\r\n") {
+			t.Errorf("sanitized prefix contains uppercase or whitespace: %q", got)
 		}
-	if got := SanitizePrefix("  Test  "); got != "test" {
-		t.Fatalf("unexpected prefix: %q", got)
 	}
 	if got := SanitizePrefix(""); got != "" {
 		t.Fatalf("expected empty prefix, got %q", got)
@@ -260,36 +259,6 @@ func TestIsMusicAssetPath(t *testing.T) {
 	}
 }
 
-func TestFirstNonEmpty(t *testing.T) {
-	if got := FirstNonEmpty("", "hello", "world"); got != "hello" {
-		t.Fatalf("expected 'hello', got %q", got)
-	}
-	if got := FirstNonEmpty("", "", ""); got != "" {
-		t.Fatalf("expected empty, got %q", got)
-	}
-	if got := FirstNonEmpty("first"); got != "first" {
-		t.Fatalf("expected 'first', got %q", got)
-	}
-}
-
-func TestJoinNonEmpty(t *testing.T) {
-	if got := JoinNonEmpty(", ", "a", "", "b"); got != "a, b" {
-		t.Fatalf("expected 'a, b', got %q", got)
-	}
-	if got := JoinNonEmpty(", "); got != "" {
-		t.Fatalf("expected empty, got %q", got)
-	}
-}
-
-func TestTrimSlashes(t *testing.T) {
-	if got := TrimSlashes("/foo/bar/"); got != "foo/bar" {
-		t.Fatalf("expected 'foo/bar', got %q", got)
-	}
-	if got := TrimSlashes("///"); got != "" {
-		t.Fatalf("expected empty, got %q", got)
-	}
-}
-
 func TestEscapeMarkdownCell(t *testing.T) {
 	result := EscapeMarkdownCell("a|b\nc")
 	if !strings.Contains(result, `\|`) {
@@ -300,15 +269,6 @@ func TestEscapeMarkdownCell(t *testing.T) {
 	}
 }
 
-func TestWrapCodeCell(t *testing.T) {
-	if got := WrapCodeCell("test.bmu"); got != "`test.bmu`" {
-		t.Fatalf("expected '`test.bmu`', got %q", got)
-	}
-	if got := WrapCodeCell(""); got != "" {
-		t.Fatalf("expected empty string, got %q", got)
-	}
-}
-
 func TestSyncGeneratedCreditsArtifactsWritesNewFiles(t *testing.T) {
 	root := t.TempDir()
 	desired := map[string][]byte{
@@ -372,15 +332,6 @@ func TestPrefixForDir(t *testing.T) {
 	}
 }
 
-func TestMaxMin(t *testing.T) {
-	if got := Min(3, 5); got != 3 {
-		t.Fatalf("Min(3,5) = %d, want 3", got)
-	}
-	if got := Max(3, 5); got != 5 {
-		t.Fatalf("Max(3,5) = %d, want 5", got)
-	}
-}
-
 func TestResolveFFmpegEnv(t *testing.T) {
 	t.Setenv("SOW_FFMPEG", "/custom/ffmpeg")
 	path, err := ResolveFFmpeg()
@@ -405,7 +356,7 @@ func TestResolveFFprobeEnv(t *testing.T) {
 
 func TestFFmpegMissingErrHasInstallHints(t *testing.T) {
 	msg := ffmpegMissingErr("ffmpeg").Error()
-	for _, want := range []string{"ffmpeg", "winget", "brew", "apt", "SOW_FFMPEG"} {
+	for _, want := range []string{"ffmpeg", "SOW_FFMPEG"} {
 		if !strings.Contains(msg, want) {
 			t.Errorf("ffmpeg error missing %q; got:\n%s", want, msg)
 		}

internal/pipeline/build.go

@@ -109,6 +109,7 @@ type BuildHAKOptions struct {
 	Progress             ProgressFunc
 	ArchiveNames         []string
 	SourceManifestPath   string
+	ContentAddressedRoot string
 	SkipMusic            bool
 	MusicDatasetIDs      []string
 }
@@ -196,7 +197,7 @@ func BuildHAKsWithProgress(p *project.Project, progress ProgressFunc) (BuildResu
 }
 
 func BuildHAKsWithOptions(p *project.Project, opts BuildHAKOptions) (BuildResult, error) {
-	return planOrBuildHAKs(p, opts.Progress, true, opts.ArchiveNames, opts.SourceManifestPath, opts.SkipMusic, opts.MusicDatasetIDs)
+	return planOrBuildHAKs(p, opts.Progress, true, opts)
 }
 
 func PlanHAKs(p *project.Project) (BuildResult, error) {
@@ -208,18 +209,18 @@ func PlanHAKsWithProgress(p *project.Project, progress ProgressFunc) (BuildResul
 }
 
 func PlanHAKsWithOptions(p *project.Project, opts BuildHAKOptions) (BuildResult, error) {
-	return planOrBuildHAKs(p, opts.Progress, false, opts.ArchiveNames, opts.SourceManifestPath, opts.SkipMusic, opts.MusicDatasetIDs)
+	return planOrBuildHAKs(p, opts.Progress, false, opts)
 }
 
 func buildHAKs(p *project.Project, progress ProgressFunc) (BuildResult, error) {
-	return planOrBuildHAKs(p, progress, true, nil, "", false, nil)
+	return planOrBuildHAKs(p, progress, true, BuildHAKOptions{})
 }
 
 func planHAKs(p *project.Project, progress ProgressFunc) (BuildResult, error) {
-	return planOrBuildHAKs(p, progress, false, nil, "", false, nil)
+	return planOrBuildHAKs(p, progress, false, BuildHAKOptions{})
 }
 
-func planOrBuildHAKs(p *project.Project, progress ProgressFunc, writeArchives bool, archiveNames []string, sourceManifestPath string, skipMusic bool, musicDatasetIDs []string) (result BuildResult, err error) {
+func planOrBuildHAKs(p *project.Project, progress ProgressFunc, writeArchives bool, opts BuildHAKOptions) (result BuildResult, err error) {
 	preserveExistingHAKs := p.EffectiveConfig().Build.KeepExistingHAKs || envBool("SOW_BUILD_HAKS_KEEP_EXISTING")
 
 	progressf(progress, "Validating project...")
@@ -227,15 +228,23 @@ func planOrBuildHAKs(p *project.Project, progress ProgressFunc, writeArchives bo
 		return BuildResult{}, err
 	}
 
+	directManifest, err := loadDirectSourceManifest(opts.SourceManifestPath)
+	if err != nil {
+		return BuildResult{}, err
+	}
+	if directManifest != nil {
+		return buildDirectHAKs(p, progress, writeArchives, directManifest, opts)
+	}
+
 	progressf(progress, "Collecting asset resources...")
-	allowedAssets, sourceManifest, err := loadSourceManifestAssetSet(sourceManifestPath)
+	allowedAssets, sourceManifest, err := loadSourceManifestAssetSet(opts.SourceManifestPath)
 	if err != nil {
 		return BuildResult{}, err
 	}
 	musicAssets := &preparedMusicAssets{SkipSourceRel: map[string]struct{}{}}
-	if !skipMusic {
+	if !opts.SkipMusic {
 		musicAssets, err = prepareMusicAssetsWithOptions(p, musicPrepareOptions{
-			datasetIDs: musicDatasetIDs,
+			datasetIDs: opts.MusicDatasetIDs,
 			write:      writeArchives,
 		})
 		if err != nil {
@@ -294,7 +303,7 @@ func planOrBuildHAKs(p *project.Project, progress ProgressFunc, writeArchives bo
 	if err != nil {
 		return BuildResult{}, err
 	}
-	chunks, err = filterHAKChunksByName(chunks, archiveNames)
+	chunks, err = filterHAKChunksByName(chunks, opts.ArchiveNames)
 	if err != nil {
 		return BuildResult{}, err
 	}
@@ -369,16 +378,8 @@ func planOrBuildHAKs(p *project.Project, progress ProgressFunc, writeArchives bo
 			if err := os.MkdirAll(filepath.Dir(hakPath), 0o755); err != nil {
 				return BuildResult{}, fmt.Errorf("create hak archive dir: %w", err)
 			}
-			hakOutput, err := os.Create(hakPath)
+			if err := writeHAKArchive(hakPath, resourceSlice(chunk.Assets)); err != nil {
-			if err != nil {
+				return BuildResult{}, err
-				return BuildResult{}, fmt.Errorf("create hak archive: %w", err)
-			}
-			if err := erf.Write(hakOutput, erf.New("HAK ", resourceSlice(chunk.Assets))); err != nil {
-				hakOutput.Close()
-				return BuildResult{}, fmt.Errorf("write hak archive: %w", err)
-			}
-			if err := hakOutput.Close(); err != nil {
-				return BuildResult{}, fmt.Errorf("close hak archive: %w", err)
 			}
 		}
 
@@ -408,6 +409,110 @@ func planOrBuildHAKs(p *project.Project, progress ProgressFunc, writeArchives bo
 	return result, nil
 }
 
+// buildDirectHAKs packages HAKs directly from the content-addressed source blob
+// cache. It skips music preparation, generated 2da discovery, git creation-time
+// lookups, LFS discovery, and any materialized asset tree scan.
+func buildDirectHAKs(p *project.Project, progress ProgressFunc, writeArchives bool, manifest *SourceBuildManifest, opts BuildHAKOptions) (BuildResult, error) {
+	progressf(progress, "Collecting asset resources...")
+	assetResources, err := collectDirectSourceResources(manifest, opts.ContentAddressedRoot)
+	if err != nil {
+		return BuildResult{}, err
+	}
+
+	result := BuildResult{HAKAssets: len(assetResources)}
+
+	progressf(progress, "Planning HAK chunks...")
+	chunks, err := chunksFromSourceManifest(assetResources, manifest.HAKs)
+	if err != nil {
+		return BuildResult{}, err
+	}
+	chunks, err = filterHAKChunksByName(chunks, opts.ArchiveNames)
+	if err != nil {
+		return BuildResult{}, err
+	}
+
+	buildManifest := BuildManifest{
+		ModuleHAKs: append([]string(nil), manifest.ModuleHAKs...),
+		HAKs:       make([]BuildManifestHAK, 0, len(chunks)),
+	}
+	for _, chunk := range chunks {
+		buildManifest.HAKs = append(buildManifest.HAKs, buildManifestEntry(chunk))
+	}
+
+	manifestPath := p.HAKManifestPath()
+	manifestBytes, err := json.MarshalIndent(buildManifest, "", "  ")
+	if err != nil {
+		return BuildResult{}, fmt.Errorf("marshal hak manifest: %w", err)
+	}
+	manifestBytes = append(manifestBytes, '\n')
+
+	if writeArchives {
+		progressf(progress, "Writing HAK archives...")
+		result.HAKSummary.Total = len(chunks)
+		result.HAKPaths = make([]string, 0, len(chunks))
+		for index, chunk := range chunks {
+			hakPath := p.HAKArchivePath(chunk.Name)
+			progressf(progress, fmt.Sprintf("Writing HAK %d/%d: %s (%d assets)", index+1, len(chunks), chunk.Name, len(chunk.Assets)))
+			if err := os.MkdirAll(filepath.Dir(hakPath), 0o755); err != nil {
+				return BuildResult{}, fmt.Errorf("create hak archive dir: %w", err)
+			}
+			if err := writeHAKArchive(hakPath, resourceSlice(chunk.Assets)); err != nil {
+				return BuildResult{}, err
+			}
+			result.HAKSummary.Written++
+			result.HAKSummary.Actions = append(result.HAKSummary.Actions, HAKArchiveAction{
+				Name:       chunk.Name,
+				AssetCount: len(chunk.Assets),
+				OutputPath: hakPath,
+			})
+			result.HAKPaths = append(result.HAKPaths, hakPath)
+		}
+	}
+
+	progressf(progress, "Writing HAK manifest...")
+	if err := os.MkdirAll(filepath.Dir(manifestPath), 0o755); err != nil {
+		return BuildResult{}, fmt.Errorf("create hak manifest dir: %w", err)
+	}
+	if err := os.WriteFile(manifestPath, manifestBytes, 0o644); err != nil {
+		return BuildResult{}, fmt.Errorf("write hak manifest: %w", err)
+	}
+	result.Manifest = manifestPath
+	return result, nil
+}
+
+// writeHAKArchive publishes a completed HAK atomically, so a failed write never
+// leaves a partial archive at the final path.
+func writeHAKArchive(hakPath string, resources []erf.Resource) error {
+	tmpPath := hakPath + ".tmp"
+	if err := os.Remove(tmpPath); err != nil && !errors.Is(err, os.ErrNotExist) {
+		return fmt.Errorf("remove stale temporary hak %s: %w", tmpPath, err)
+	}
+
+	output, err := os.OpenFile(tmpPath, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o644)
+	if err != nil {
+		return fmt.Errorf("create temporary hak archive %s: %w", tmpPath, err)
+	}
+	if err := erf.Write(output, erf.New("HAK ", resources)); err != nil {
+		output.Close()
+		os.Remove(tmpPath)
+		return fmt.Errorf("write hak archive: %w", err)
+	}
+	if err := output.Sync(); err != nil {
+		output.Close()
+		os.Remove(tmpPath)
+		return fmt.Errorf("sync hak archive: %w", err)
+	}
+	if err := output.Close(); err != nil {
+		os.Remove(tmpPath)
+		return fmt.Errorf("close hak archive: %w", err)
+	}
+	if err := os.Rename(tmpPath, hakPath); err != nil {
+		os.Remove(tmpPath)
+		return fmt.Errorf("publish hak archive %s: %w", hakPath, err)
+	}
+	return nil
+}
+
 func writeAutogenManifestOutputs(progress ProgressFunc, manifests []topdata.ProducedAutogenManifest) error {
 	if len(manifests) == 0 {
 		return nil
@@ -672,7 +777,7 @@ func chunksFromManifest(assets []assetResource, entries []BuildManifestHAK) ([]h
 			}
 			chunkAssets = append(chunkAssets, asset)
 		}
-		chunks = append(chunks, hakChunk{
+		chunk := hakChunk{
 			Config: project.HAKConfig{
 				Name:     entry.Group,
 				Priority: entry.Priority,
@@ -683,7 +788,14 @@ func chunksFromManifest(assets []assetResource, entries []BuildManifestHAK) ([]h
 			Name:   entry.Name,
 			Assets: chunkAssets,
 			Size:   erf.ArchiveSize(resourceSlice(chunkAssets)),
-		})
+		}
+		// A manifest can name two distinct source paths that collapse to the same
+		// resref+type (e.g. creature/foo.mdl and placeable/foo.mdl); without this
+		// guard the second would silently shadow the first in the ERF.
+		if err := ensureUniqueChunkResources(chunk); err != nil {
+			return nil, err
+		}
+		chunks = append(chunks, chunk)
 	}
 	return chunks, nil
 }

internal/pipeline/pipeline_test.go

@@ -17,6 +17,35 @@ import (
 	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/project"
 )
 
+func TestBuildHAKsCleansFailedTemporaryArchive(t *testing.T) {
+	root := t.TempDir()
+	p := loadDirectProject(t, root)
+
+	blobs := filepath.Join(root, "blobs")
+	sha := strings.Repeat("a", 64)
+	writeBlobAt(t, blobs, sha, "wxyz")
+	manifestPath := writeDirectManifest(t, root,
+		map[string]SourceAsset{"core/a.tga": {SHA256: sha, SizeBytes: 4}},
+		[]string{"core/a.tga"})
+
+	tmpPath := filepath.Join(root, "build", "core_01.hak.tmp")
+	mustWriteFile(t, tmpPath, "stale partial archive")
+
+	_, err := BuildHAKsWithOptions(p, BuildHAKOptions{
+		SourceManifestPath:   manifestPath,
+		ContentAddressedRoot: blobs,
+	})
+	if err == nil {
+		t.Fatal("expected corrupt input to fail")
+	}
+	if _, err := os.Stat(filepath.Join(root, "build", "core_01.hak")); !errors.Is(err, os.ErrNotExist) {
+		t.Fatal("corrupt input must not leave a completed hak")
+	}
+	if _, err := os.Stat(tmpPath); !errors.Is(err, os.ErrNotExist) {
+		t.Fatal("failed build must clean temporary hak")
+	}
+}
+
 func TestBuildThenExtract(t *testing.T) {
 	root := t.TempDir()
 	mustMkdir(t, filepath.Join(root, "src"))
@@ -1864,7 +1893,7 @@ func TestPlanHAKsWritesManifestWithoutArchives(t *testing.T) {
 	}
 }
 
-func TestBuildHAKsWritesConfiguredHeadVisualeffectsAutogenManifest(t *testing.T) {
+func TestBuildHAKsWritesConfiguredAccessoryVisualeffectsAutogenManifest(t *testing.T) {
 	root := t.TempDir()
 	mustMkdir(t, filepath.Join(root, "src"))
 	mustMkdir(t, filepath.Join(root, "assets", "vfxs", "chest_accessories"))
@@ -1951,7 +1980,7 @@ func TestBuildHAKsWritesConfiguredHeadVisualeffectsAutogenManifest(t *testing.T)
 
 	headRaw, err := os.ReadFile(filepath.Join(root, "build", "sow-accessory-vfx-manifest.json"))
 	if err != nil {
-		t.Fatalf("read head visualeffects manifest: %v", err)
+		t.Fatalf("read accessory visualeffects manifest: %v", err)
 	}
 	text := string(headRaw)
 	for _, want := range []string{
@@ -1969,12 +1998,12 @@ func TestBuildHAKsWritesConfiguredHeadVisualeffectsAutogenManifest(t *testing.T)
 		`"model_stem": "hfx_hair_bangs"`,
 	} {
 		if !strings.Contains(text, want) {
-			t.Fatalf("expected head visualeffects manifest to contain %q, got:\n%s", want, text)
+			t.Fatalf("expected accessory visualeffects manifest to contain %q, got:\n%s", want, text)
 		}
 	}
 }
 
-func TestBuildHAKsWritesFolderCategoryInHeadVisualeffectsAutogenManifest(t *testing.T) {
+func TestBuildHAKsWritesFolderCategoryInAccessoryVisualeffectsAutogenManifest(t *testing.T) {
 	root := t.TempDir()
 	mustMkdir(t, filepath.Join(root, "src"))
 	mustMkdir(t, filepath.Join(root, "assets", "vfxs", "head_features", "sinfar", "ears_plt"))
@@ -2053,7 +2082,7 @@ func TestBuildHAKsWritesFolderCategoryInHeadVisualeffectsAutogenManifest(t *test
 	}
 	headRaw, err := os.ReadFile(filepath.Join(root, "build", "sow-accessory-vfx-manifest.json"))
 	if err != nil {
-		t.Fatalf("read head visualeffects manifest: %v", err)
+		t.Fatalf("read accessory visualeffects manifest: %v", err)
 	}
 	text := string(headRaw)
 	for _, want := range []string{
@@ -2066,7 +2095,7 @@ func TestBuildHAKsWritesFolderCategoryInHeadVisualeffectsAutogenManifest(t *test
 		`"category_from": "immediate_parent"`,
 	} {
 		if !strings.Contains(text, want) {
-			t.Fatalf("expected head visualeffects manifest to contain %q, got:\n%s", want, text)
+			t.Fatalf("expected accessory visualeffects manifest to contain %q, got:\n%s", want, text)
 		}
 	}
 }
@@ -3057,7 +3086,7 @@ func TestCollectLFSAssetInfoUsesGitCommonDirForWorktree(t *testing.T) {
 func runGitCommitTest(t *testing.T, dir, timestamp, message string) {
 	t.Helper()
 	runGitTest(t, dir, "add", ".")
-	cmd := exec.Command("git", "commit", "-m", message)
+	cmd := exec.Command("git", "-c", "commit.gpgsign=false", "-c", "tag.gpgsign=false", "commit", "-m", message)
 	cmd.Dir = dir
 	cmd.Env = append(os.Environ(),
 		"GIT_AUTHOR_DATE="+timestamp,
@@ -3071,7 +3100,7 @@ func runGitCommitTest(t *testing.T, dir, timestamp, message string) {
 
 func runGitTest(t *testing.T, dir string, args ...string) {
 	t.Helper()
-	cmd := exec.Command("git", args...)
+	cmd := exec.Command("git", append([]string{"-c", "commit.gpgsign=false", "-c", "tag.gpgsign=false"}, args...)...)
 	if dir != "" {
 		cmd.Dir = dir
 	}

internal/pipeline/source_build_test.go

@@ -0,0 +1,249 @@
+package pipeline
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/buildinfo"
+	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/erf"
+	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/project"
+)
+
+const directProjectConfig = `{
+  "module": {
+    "name": "Test Module",
+    "resref": "testmod",
+    "hak_order": ["core_01"]
+  },
+  "paths": {
+    "source": "src",
+    "assets": "assets",
+    "build": "build"
+  }
+}
+`
+
+func writeBlobAt(t *testing.T, root, sha, content string) {
+	t.Helper()
+	dir := filepath.Join(root, "sha256", sha[0:2], sha[2:4])
+	mustMkdir(t, dir)
+	mustWriteFile(t, filepath.Join(dir, sha), content)
+}
+
+func writeBlob(t *testing.T, root string, payload []byte) string {
+	t.Helper()
+	sum := sha256.Sum256(payload)
+	sha := hex.EncodeToString(sum[:])
+	writeBlobAt(t, root, sha, string(payload))
+	return sha
+}
+
+func writeDirectManifest(t *testing.T, root string, sources map[string]SourceAsset, assets []string) string {
+	t.Helper()
+	manifest := SourceBuildManifest{
+		Schema:     1,
+		BuilderID:  buildinfo.String(),
+		ModuleHAKs: []string{"core_01"},
+		HAKs: []SourceManifestHAK{{
+			Name:     "core_01",
+			Group:    "core",
+			Priority: 1,
+			MaxBytes: 1 << 20,
+			Assets:   assets,
+		}},
+		AssetSources: sources,
+	}
+	raw, err := json.Marshal(manifest)
+	if err != nil {
+		t.Fatalf("marshal manifest: %v", err)
+	}
+	path := filepath.Join(root, "build-source-manifest.json")
+	mustWriteFile(t, path, string(raw))
+	return path
+}
+
+func loadDirectProject(t *testing.T, root string) *project.Project {
+	t.Helper()
+	mustWriteFile(t, filepath.Join(root, "nwn-tool.json"), directProjectConfig)
+	mustMkdir(t, filepath.Join(root, "build"))
+	p, err := project.Load(root)
+	if err != nil {
+		t.Fatalf("load project: %v", err)
+	}
+	return p
+}
+
+func TestBuildHAKsFromContentAddressedManifestWithoutAssetsTree(t *testing.T) {
+	root := t.TempDir()
+	p := loadDirectProject(t, root)
+
+	blobs := filepath.Join(root, "blobs")
+	payload := []byte("tga-payload-bytes")
+	sha := writeBlob(t, blobs, payload)
+	manifestPath := writeDirectManifest(t, root,
+		map[string]SourceAsset{"core/a.tga": {SHA256: sha, SizeBytes: int64(len(payload))}},
+		[]string{"core/a.tga"})
+
+	result, err := BuildHAKsWithOptions(p, BuildHAKOptions{
+		SourceManifestPath:   manifestPath,
+		ContentAddressedRoot: blobs,
+	})
+	if err != nil {
+		t.Fatalf("build direct haks: %v", err)
+	}
+	if result.HAKAssets != 1 {
+		t.Fatalf("hak assets = %d, want 1", result.HAKAssets)
+	}
+
+	if _, err := os.Stat(filepath.Join(root, "assets")); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("direct build must not materialize an assets tree (stat err = %v)", err)
+	}
+
+	hakPath := filepath.Join(root, "build", "core_01.hak")
+	raw, err := os.ReadFile(hakPath)
+	if err != nil {
+		t.Fatalf("read hak: %v", err)
+	}
+	archive, err := erf.Read(bytes.NewReader(raw))
+	if err != nil {
+		t.Fatalf("decode hak: %v", err)
+	}
+	if len(archive.Resources) != 1 {
+		t.Fatalf("hak resources = %d, want 1", len(archive.Resources))
+	}
+	if got := string(archive.Resources[0].Data); got != string(payload) {
+		t.Fatalf("resource payload = %q, want %q", got, payload)
+	}
+	if archive.Resources[0].Name != "a" {
+		t.Fatalf("resref = %q, want a", archive.Resources[0].Name)
+	}
+}
+
+func TestBuildHAKsFromContentAddressedManifestRejectsMissingRoot(t *testing.T) {
+	root := t.TempDir()
+	p := loadDirectProject(t, root)
+
+	blobs := filepath.Join(root, "blobs")
+	payload := []byte("tga-payload-bytes")
+	sha := writeBlob(t, blobs, payload)
+	manifestPath := writeDirectManifest(t, root,
+		map[string]SourceAsset{"core/a.tga": {SHA256: sha, SizeBytes: int64(len(payload))}},
+		[]string{"core/a.tga"})
+
+	_, err := BuildHAKsWithOptions(p, BuildHAKOptions{SourceManifestPath: manifestPath})
+	if err == nil {
+		t.Fatal("expected failure when content-addressed root is missing")
+	}
+}
+
+func TestBuildHAKsFromContentAddressedManifestRejectsMissingBlob(t *testing.T) {
+	root := t.TempDir()
+	p := loadDirectProject(t, root)
+
+	blobs := filepath.Join(root, "blobs")
+	sha := strings.Repeat("b", 64)
+	manifestPath := writeDirectManifest(t, root,
+		map[string]SourceAsset{"core/a.tga": {SHA256: sha, SizeBytes: 4}},
+		[]string{"core/a.tga"})
+
+	_, err := BuildHAKsWithOptions(p, BuildHAKOptions{
+		SourceManifestPath:   manifestPath,
+		ContentAddressedRoot: blobs,
+	})
+	if err == nil {
+		t.Fatal("expected failure for missing source blob")
+	}
+}
+
+func TestBuildHAKsFromContentAddressedManifestRejectsCorruptBlob(t *testing.T) {
+	root := t.TempDir()
+	p := loadDirectProject(t, root)
+
+	blobs := filepath.Join(root, "blobs")
+	declared := sha256.Sum256([]byte("abcd"))
+	sha := hex.EncodeToString(declared[:])
+	// Same length, different bytes: size check passes, content hash mismatches.
+	writeBlobAt(t, blobs, sha, "wxyz")
+	manifestPath := writeDirectManifest(t, root,
+		map[string]SourceAsset{"core/a.tga": {SHA256: sha, SizeBytes: 4}},
+		[]string{"core/a.tga"})
+
+	_, err := BuildHAKsWithOptions(p, BuildHAKOptions{
+		SourceManifestPath:   manifestPath,
+		ContentAddressedRoot: blobs,
+	})
+	if err == nil {
+		t.Fatal("expected sha256 mismatch failure for corrupt blob")
+	}
+	if !strings.Contains(err.Error(), "sha256 mismatch") {
+		t.Fatalf("error = %v, want sha256 mismatch", err)
+	}
+	if _, statErr := os.Stat(filepath.Join(root, "build", "core_01.hak")); !errors.Is(statErr, os.ErrNotExist) {
+		t.Fatalf("corrupt build must not leave a completed hak (stat err = %v)", statErr)
+	}
+}
+
+func TestLegacySourceManifestStillBuildsFromAssetsTree(t *testing.T) {
+	root := t.TempDir()
+	mustMkdir(t, filepath.Join(root, "src", "module"))
+	mustMkdir(t, filepath.Join(root, "assets", "core"))
+	mustMkdir(t, filepath.Join(root, "build"))
+	mustWriteFile(t, filepath.Join(root, "nwn-tool.json"), `{
+  "module": {"name": "Test Module", "resref": "testmod", "hak_order": ["group:core"]},
+  "paths": {"source": "src", "assets": "assets", "build": "build"},
+  "haks": [{"name": "core", "priority": 1, "include": ["core/**"]}]
+}
+`)
+	mustWriteFile(t, filepath.Join(root, "src", "module", "module.ifo.json"), `{
+  "file_type": "IFO ",
+  "file_version": "V3.2",
+  "root": {"struct_type": 0, "fields": [
+    {"label": "Mod_Name", "type": "CExoString", "value": "Test Module"},
+    {"label": "Mod_HakList", "type": "List", "value": []}
+  ]}
+}
+`)
+	mustWriteFile(t, filepath.Join(root, "assets", "core", "a.tga"), strings.Repeat("a", 16))
+	mustWriteFile(t, filepath.Join(root, "assets", "core", "b.tga"), strings.Repeat("b", 16))
+
+	manifestPath := filepath.Join(root, "legacy-source-manifest.json")
+	mustWriteFile(t, manifestPath, `{
+  "module_haks": ["core"],
+  "haks": [{"name": "core", "group": "core", "priority": 1, "assets": ["core/a.tga", "core/b.tga"]}]
+}
+`)
+
+	p, err := project.Load(root)
+	if err != nil {
+		t.Fatalf("load project: %v", err)
+	}
+	if err := p.Scan(); err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+
+	result, err := BuildHAKsWithOptions(p, BuildHAKOptions{SourceManifestPath: manifestPath})
+	if err != nil {
+		t.Fatalf("legacy build: %v", err)
+	}
+	if len(result.HAKPaths) != 1 {
+		t.Fatalf("hak paths = %d, want 1", len(result.HAKPaths))
+	}
+	raw, err := os.ReadFile(filepath.Join(root, "build", "core.hak"))
+	if err != nil {
+		t.Fatalf("read legacy hak: %v", err)
+	}
+	archive, err := erf.Read(bytes.NewReader(raw))
+	if err != nil {
+		t.Fatalf("decode legacy hak: %v", err)
+	}
+	if len(archive.Resources) != 2 {
+		t.Fatalf("legacy hak resources = %d, want 2", len(archive.Resources))
+	}
+}

internal/pipeline/source_manifest.go

@@ -0,0 +1,232 @@
+package pipeline
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	pathpkg "path"
+	"path/filepath"
+	"regexp"
+	"slices"
+	"strings"
+
+	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/buildinfo"
+	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/erf"
+)
+
+// SourceAsset is one content-addressed source blob referenced by a direct source
+// manifest. The blob is resolved by sha256 under the content-addressed root.
+type SourceAsset struct {
+	SHA256    string `json:"sha256"`
+	SizeBytes int64  `json:"size_bytes"`
+}
+
+// SourceManifestHAK describes one output HAK and the logical asset paths it packs.
+type SourceManifestHAK struct {
+	Name     string   `json:"name"`
+	Group    string   `json:"group"`
+	Priority int      `json:"priority"`
+	MaxBytes int64    `json:"max_bytes"`
+	Optional bool     `json:"optional,omitempty"`
+	Assets   []string `json:"assets"`
+	BuildKey string   `json:"build_key"`
+}
+
+// SourceBuildManifest is the generated, content-addressed input to a HAK build.
+// It carries asset_sources, so Crucible reads source bytes directly from the blob
+// cache without scanning a materialized asset tree.
+type SourceBuildManifest struct {
+	Schema       int                    `json:"schema"`
+	BuilderID    string                 `json:"builder_id"`
+	ModuleHAKs   []string               `json:"module_haks"`
+	HAKs         []SourceManifestHAK    `json:"haks"`
+	AssetSources map[string]SourceAsset `json:"asset_sources"`
+}
+
+var sha256Pattern = regexp.MustCompile(`^[0-9a-f]{64}$`)
+
+// hasAssetSources reports whether raw JSON carries the direct content-addressed
+// schema. A legacy BuildManifest has no asset_sources object.
+func hasAssetSources(raw []byte) bool {
+	var header struct {
+		AssetSources map[string]json.RawMessage `json:"asset_sources"`
+	}
+	if err := json.Unmarshal(raw, &header); err != nil {
+		return false
+	}
+	return header.AssetSources != nil
+}
+
+func loadSourceBuildManifest(path string) (*SourceBuildManifest, error) {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("read source manifest %s: %w", path, err)
+	}
+	var manifest SourceBuildManifest
+	if err := json.Unmarshal(raw, &manifest); err != nil {
+		return nil, fmt.Errorf("parse source manifest %s: %w", path, err)
+	}
+	return &manifest, nil
+}
+
+func validateDirectSourceManifest(manifest *SourceBuildManifest) error {
+	if manifest.Schema != 1 {
+		return fmt.Errorf("unsupported source manifest schema %d", manifest.Schema)
+	}
+	if manifest.BuilderID != buildinfo.String() {
+		return fmt.Errorf("source manifest builder_id %q does not match builder %q", manifest.BuilderID, buildinfo.String())
+	}
+	if len(manifest.ModuleHAKs) == 0 {
+		return fmt.Errorf("source manifest module_haks is empty")
+	}
+
+	referenced := make(map[string]struct{}, len(manifest.AssetSources))
+	for _, hak := range manifest.HAKs {
+		if strings.TrimSpace(hak.Name) == "" {
+			return fmt.Errorf("source manifest hak has empty name")
+		}
+		for _, rel := range hak.Assets {
+			if !validLogicalAssetPath(rel) {
+				return fmt.Errorf("source manifest hak %s has invalid asset path %q", hak.Name, rel)
+			}
+			if _, dup := referenced[rel]; dup {
+				return fmt.Errorf("source manifest asset %q referenced by more than one hak", rel)
+			}
+			referenced[rel] = struct{}{}
+			source, ok := manifest.AssetSources[rel]
+			if !ok {
+				return fmt.Errorf("source manifest hak %s asset %q has no asset_sources entry", hak.Name, rel)
+			}
+			if !sha256Pattern.MatchString(source.SHA256) {
+				return fmt.Errorf("source manifest asset %q has invalid sha256 %q", rel, source.SHA256)
+			}
+			if source.SizeBytes < 0 {
+				return fmt.Errorf("source manifest asset %q has negative size %d", rel, source.SizeBytes)
+			}
+		}
+	}
+
+	for rel := range manifest.AssetSources {
+		if !validLogicalAssetPath(rel) {
+			return fmt.Errorf("source manifest asset_sources has invalid path %q", rel)
+		}
+		if _, ok := referenced[rel]; !ok {
+			return fmt.Errorf("source manifest asset_sources entry %q is not referenced by any hak", rel)
+		}
+	}
+	return nil
+}
+
+func validLogicalAssetPath(path string) bool {
+	if path == "" || filepath.IsAbs(path) || strings.Contains(path, `\`) {
+		return false
+	}
+	clean := pathpkg.Clean(path)
+	return clean == path && clean != "." && clean != ".." &&
+		!strings.HasPrefix(clean, "../")
+}
+
+func contentAddressedBlobPath(root, sha string) (string, error) {
+	if strings.TrimSpace(root) == "" {
+		return "", fmt.Errorf("content-addressed root is required")
+	}
+	if !sha256Pattern.MatchString(sha) {
+		return "", fmt.Errorf("invalid content-addressed sha256 %q", sha)
+	}
+	return filepath.Join(root, "sha256", sha[0:2], sha[2:4], sha), nil
+}
+
+// loadDirectSourceManifest returns a parsed direct source manifest when path
+// points at a content-addressed manifest. It returns (nil, nil) for an empty
+// path or a legacy manifest without asset_sources, so the caller falls through
+// to the legacy path-backed build.
+func loadDirectSourceManifest(path string) (*SourceBuildManifest, error) {
+	if strings.TrimSpace(path) == "" {
+		return nil, nil
+	}
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("read source manifest %s: %w", path, err)
+	}
+	if !hasAssetSources(raw) {
+		return nil, nil
+	}
+	var manifest SourceBuildManifest
+	if err := json.Unmarshal(raw, &manifest); err != nil {
+		return nil, fmt.Errorf("parse source manifest %s: %w", path, err)
+	}
+	return &manifest, nil
+}
+
+// collectDirectSourceResources resolves each manifest-named blob under contentRoot
+// and produces sorted asset resources that stream from the blob cache with their
+// expected SHA-256. It never scans a materialized asset tree.
+func collectDirectSourceResources(manifest *SourceBuildManifest, contentRoot string) ([]assetResource, error) {
+	if err := validateDirectSourceManifest(manifest); err != nil {
+		return nil, err
+	}
+	if strings.TrimSpace(contentRoot) == "" {
+		return nil, fmt.Errorf("content-addressed source manifest requires --content-addressed-root")
+	}
+
+	resources := make([]assetResource, 0, len(manifest.AssetSources))
+	for _, hak := range manifest.HAKs {
+		for _, logicalPath := range hak.Assets {
+			source := manifest.AssetSources[logicalPath]
+			extension := strings.TrimPrefix(strings.ToLower(filepath.Ext(logicalPath)), ".")
+			resourceType, ok := erf.HAKResourceTypeForExtension(extension)
+			if !ok {
+				return nil, fmt.Errorf("unsupported HAK resource extension %q for %s", filepath.Ext(logicalPath), logicalPath)
+			}
+			resref := strings.ToLower(strings.TrimSuffix(filepath.Base(logicalPath), filepath.Ext(logicalPath)))
+
+			blobPath, err := contentAddressedBlobPath(contentRoot, source.SHA256)
+			if err != nil {
+				return nil, err
+			}
+			info, err := os.Stat(blobPath)
+			if err != nil {
+				return nil, fmt.Errorf("missing source blob for %s: %w", logicalPath, err)
+			}
+			if info.Size() != source.SizeBytes {
+				return nil, fmt.Errorf("source blob size mismatch for %s: expected %d, got %d", logicalPath, source.SizeBytes, info.Size())
+			}
+
+			resource := erf.Resource{
+				Name:           resref,
+				Type:           resourceType,
+				SourcePath:     blobPath,
+				Size:           source.SizeBytes,
+				ExpectedSHA256: source.SHA256,
+			}
+			resources = append(resources, assetResource{
+				Rel:       logicalPath,
+				Resource:  resource,
+				Size:      erf.ArchiveSize([]erf.Resource{resource}),
+				ContentID: "sha256:" + source.SHA256,
+			})
+		}
+	}
+
+	slices.SortFunc(resources, func(a, b assetResource) int {
+		return compareResourceKeys(a.Resource, b.Resource)
+	})
+	return resources, nil
+}
+
+// chunksFromSourceManifest converts direct manifest HAK entries into build chunks
+// reusing the legacy manifest chunker.
+func chunksFromSourceManifest(assets []assetResource, entries []SourceManifestHAK) ([]hakChunk, error) {
+	converted := make([]BuildManifestHAK, len(entries))
+	for index, entry := range entries {
+		converted[index] = BuildManifestHAK{
+			Name:     entry.Name,
+			Group:    entry.Group,
+			Priority: entry.Priority,
+			MaxBytes: entry.MaxBytes,
+			Optional: entry.Optional,
+			Assets:   entry.Assets,
+		}
+	}
+	return chunksFromManifest(assets, converted)
+}

internal/pipeline/source_manifest_test.go

@@ -0,0 +1,187 @@
+package pipeline
+
+import (
+	"encoding/json"
+	"path/filepath"
+	"testing"
+
+	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/buildinfo"
+	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/erf"
+)
+
+const validAsset = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+
+// directManifestFixture returns a minimal valid direct source manifest using the
+// running builder identity, so validation does not reject it on builder mismatch.
+func directManifestFixture() *SourceBuildManifest {
+	return &SourceBuildManifest{
+		Schema:     1,
+		BuilderID:  buildinfo.String(),
+		ModuleHAKs: []string{"core_01"},
+		HAKs: []SourceManifestHAK{
+			{
+				Name:     "core_01",
+				Group:    "core",
+				Priority: 1,
+				MaxBytes: 1024,
+				Assets:   []string{"core/a.tga"},
+			},
+		},
+		AssetSources: map[string]SourceAsset{
+			"core/a.tga": {SHA256: validAsset, SizeBytes: 4},
+		},
+	}
+}
+
+func writeManifestFixture(t *testing.T, manifest *SourceBuildManifest) string {
+	t.Helper()
+	raw, err := json.Marshal(manifest)
+	if err != nil {
+		t.Fatalf("marshal fixture: %v", err)
+	}
+	path := filepath.Join(t.TempDir(), "build-source-manifest.json")
+	mustWriteFile(t, path, string(raw))
+	return path
+}
+
+func TestLoadSourceBuildManifestDirect(t *testing.T) {
+	path := writeManifestFixture(t, directManifestFixture())
+
+	manifest, err := loadSourceBuildManifest(path)
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if manifest.Schema != 1 {
+		t.Fatalf("schema = %d, want 1", manifest.Schema)
+	}
+	if manifest.BuilderID != buildinfo.String() {
+		t.Fatalf("builder_id = %q, want %q", manifest.BuilderID, buildinfo.String())
+	}
+	if len(manifest.HAKs) != 1 || manifest.HAKs[0].Name != "core_01" {
+		t.Fatalf("unexpected haks: %#v", manifest.HAKs)
+	}
+	source, ok := manifest.AssetSources["core/a.tga"]
+	if !ok || source.SHA256 != validAsset || source.SizeBytes != 4 {
+		t.Fatalf("unexpected asset source: %#v", manifest.AssetSources)
+	}
+	if err := validateDirectSourceManifest(manifest); err != nil {
+		t.Fatalf("validate valid manifest: %v", err)
+	}
+}
+
+func TestValidateDirectSourceManifestRejectsUnsupportedSchema(t *testing.T) {
+	manifest := directManifestFixture()
+	manifest.Schema = 2
+	if err := validateDirectSourceManifest(manifest); err == nil {
+		t.Fatal("expected schema rejection")
+	}
+}
+
+func TestValidateDirectSourceManifestRejectsBadSHA(t *testing.T) {
+	manifest := directManifestFixture()
+	manifest.AssetSources["core/a.tga"] = SourceAsset{SHA256: "NOTHEX", SizeBytes: 4}
+	if err := validateDirectSourceManifest(manifest); err == nil {
+		t.Fatal("expected bad sha rejection")
+	}
+}
+
+func TestValidateDirectSourceManifestRejectsNegativeSize(t *testing.T) {
+	manifest := directManifestFixture()
+	manifest.AssetSources["core/a.tga"] = SourceAsset{SHA256: validAsset, SizeBytes: -1}
+	if err := validateDirectSourceManifest(manifest); err == nil {
+		t.Fatal("expected negative size rejection")
+	}
+}
+
+func TestValidateDirectSourceManifestRejectsMissingSource(t *testing.T) {
+	manifest := directManifestFixture()
+	delete(manifest.AssetSources, "core/a.tga")
+	if err := validateDirectSourceManifest(manifest); err == nil {
+		t.Fatal("expected missing source rejection")
+	}
+}
+
+func TestValidateDirectSourceManifestRejectsUnusedSource(t *testing.T) {
+	manifest := directManifestFixture()
+	manifest.AssetSources["core/orphan.tga"] = SourceAsset{SHA256: validAsset, SizeBytes: 4}
+	if err := validateDirectSourceManifest(manifest); err == nil {
+		t.Fatal("expected unused source rejection")
+	}
+}
+
+func TestValidateDirectSourceManifestRejectsDuplicateAssetAcrossHAKs(t *testing.T) {
+	manifest := directManifestFixture()
+	manifest.HAKs = append(manifest.HAKs, SourceManifestHAK{
+		Name:     "core_02",
+		Group:    "core",
+		Priority: 1,
+		MaxBytes: 1024,
+		Assets:   []string{"core/a.tga"},
+	})
+	if err := validateDirectSourceManifest(manifest); err == nil {
+		t.Fatal("expected duplicate-asset rejection")
+	}
+}
+
+func TestValidateDirectSourceManifestRejectsTraversalPath(t *testing.T) {
+	manifest := directManifestFixture()
+	manifest.HAKs[0].Assets = []string{"../escape.tga"}
+	manifest.AssetSources = map[string]SourceAsset{
+		"../escape.tga": {SHA256: validAsset, SizeBytes: 4},
+	}
+	if err := validateDirectSourceManifest(manifest); err == nil {
+		t.Fatal("expected traversal rejection")
+	}
+}
+
+func TestValidateDirectSourceManifestRejectsBuilderMismatch(t *testing.T) {
+	manifest := directManifestFixture()
+	manifest.BuilderID = "crucible deadbeef"
+	if err := validateDirectSourceManifest(manifest); err == nil {
+		t.Fatal("expected builder mismatch rejection")
+	}
+}
+
+// Two distinct source paths can collapse to the same resref+type; the chunker
+// must reject that rather than let one silently shadow the other in the ERF.
+func TestChunksFromManifestRejectsResrefCollision(t *testing.T) {
+	tga, ok := erf.HAKResourceTypeForExtension("tga")
+	if !ok {
+		t.Fatal("tga is not a hak resource type")
+	}
+	mk := func(rel, resref string) assetResource {
+		r := erf.Resource{Name: resref, Type: tga}
+		return assetResource{Rel: rel, Resource: r, Size: erf.ArchiveSize([]erf.Resource{r})}
+	}
+	entry := BuildManifestHAK{Name: "core_01", Group: "core"}
+
+	collide := []assetResource{mk("creature/foo.tga", "foo"), mk("placeable/foo.tga", "foo")}
+	entry.Assets = []string{"creature/foo.tga", "placeable/foo.tga"}
+	if _, err := chunksFromManifest(collide, []BuildManifestHAK{entry}); err == nil {
+		t.Fatal("expected resref+type collision rejection")
+	}
+
+	distinct := []assetResource{mk("creature/foo.tga", "foo"), mk("placeable/bar.tga", "bar")}
+	entry.Assets = []string{"creature/foo.tga", "placeable/bar.tga"}
+	if _, err := chunksFromManifest(distinct, []BuildManifestHAK{entry}); err != nil {
+		t.Fatalf("distinct resrefs should pack cleanly: %v", err)
+	}
+}
+
+func TestContentAddressedBlobPath(t *testing.T) {
+	root := "/var/cache/blobs"
+	got, err := contentAddressedBlobPath(root, validAsset)
+	if err != nil {
+		t.Fatalf("blob path: %v", err)
+	}
+	want := filepath.Join(root, "sha256", "aa", "aa", validAsset)
+	if got != want {
+		t.Fatalf("blob path = %q, want %q", got, want)
+	}
+	if _, err := contentAddressedBlobPath(root, "NOTHEX"); err == nil {
+		t.Fatal("expected invalid sha rejection")
+	}
+	if _, err := contentAddressedBlobPath("", validAsset); err == nil {
+		t.Fatal("expected empty root rejection")
+	}
+}

internal/project/project.go

@@ -349,7 +349,7 @@ type AutogenProducerConfig struct {
 	Include           []string                `json:"include" yaml:"include"`
 	Derive            AutogenDeriveConfig     `json:"derive" yaml:"derive"`
 	Manifest          AutogenManifestConfig   `json:"manifest" yaml:"manifest"`
-	HeadVisualeffects HeadVisualeffectsConfig `json:"accessory_visualeffects" yaml:"accessory_visualeffects"`
+	AccessoryVisualeffects AccessoryVisualeffectsConfig `json:"accessory_visualeffects" yaml:"accessory_visualeffects"`
 }
 
 type AutogenConsumerConfig struct {
@@ -362,13 +362,14 @@ type AutogenConsumerConfig struct {
 	Include           []string                `json:"include" yaml:"include"`
 	Derive            AutogenDeriveConfig     `json:"derive" yaml:"derive"`
 	PartsRows         PartsRowsConfig         `json:"parts_rows" yaml:"parts_rows"`
-	HeadVisualeffects HeadVisualeffectsConfig `json:"accessory_visualeffects" yaml:"accessory_visualeffects"`
+	AccessoryVisualeffects AccessoryVisualeffectsConfig `json:"accessory_visualeffects" yaml:"accessory_visualeffects"`
 	Manifest          AutogenManifestConfig   `json:"manifest" yaml:"manifest"`
 	LocalOverrideRoot string                  `json:"local_override_root,omitempty" yaml:"local_override_root,omitempty"`
+	ManifestFile      string                  `json:"manifest_file,omitempty" yaml:"manifest_file,omitempty"`
 }
 
-type HeadVisualeffectsConfig struct {
+type AccessoryVisualeffectsConfig struct {
-	Groups             map[string]HeadVisualeffectGroupConfig `json:"groups,omitempty" yaml:"groups"`
+	Groups             map[string]AccessoryVisualeffectGroupConfig `json:"groups,omitempty" yaml:"groups"`
 	GroupTokenSource   string                                 `json:"group_token_source,omitempty" yaml:"group_token_source"`
 	CategoryFrom       string                                 `json:"category_from,omitempty" yaml:"category_from"`
 	Delimiter          string                                 `json:"delimiter,omitempty" yaml:"delimiter"`
@@ -380,7 +381,7 @@ type HeadVisualeffectsConfig struct {
 	RowDefaults        map[string]string                      `json:"row_defaults,omitempty" yaml:"row_defaults"`
 }
 
-type HeadVisualeffectGroupConfig struct {
+type AccessoryVisualeffectGroupConfig struct {
 	Prefix       string            `json:"prefix" yaml:"prefix"`
 	ModelColumn  string            `json:"model_column,omitempty" yaml:"model_column"`
 	ModelColumns []string          `json:"model_columns,omitempty" yaml:"model_columns"`
@@ -1625,8 +1626,8 @@ func validateAutogenConfig(cfg AutogenConfig) []error {
 		failures = append(failures, validateGlobList(fieldPrefix+".include", producer.Include)...)
 		failures = append(failures, validateAutogenDeriveConfig(fieldPrefix+".derive", producer.Derive)...)
 		failures = append(failures, validateAutogenManifestConfig(fieldPrefix+".manifest", producer.Manifest)...)
-		if headVisualeffectsConfigConfigured(producer.HeadVisualeffects) {
+		if accessoryVisualeffectsConfigConfigured(producer.AccessoryVisualeffects) {
-			failures = append(failures, validateHeadVisualeffectsConfig(fieldPrefix+".accessory_visualeffects", producer.HeadVisualeffects)...)
+			failures = append(failures, validateAccessoryVisualeffectsConfig(fieldPrefix+".accessory_visualeffects", producer.AccessoryVisualeffects)...)
 		}
 	}
 
@@ -1665,6 +1666,13 @@ func validateAutogenConfig(cfg AutogenConfig) []error {
 		default:
 			failures = append(failures, fmt.Errorf("%s.mode %q is not supported", fieldPrefix, consumer.Mode))
 		}
+		if strings.TrimSpace(consumer.Mode) == "accessory_visualeffects" && accessoryVisualeffectsConfigConfigured(consumer.AccessoryVisualeffects) {
+			failures = append(failures, validateAccessoryVisualeffectsConfig(fieldPrefix+".accessory_visualeffects", consumer.AccessoryVisualeffects)...)
+		}
+		// A manifest_file consumer reads a pre-resolved local manifest, so the
+		// released-source fields (root/include/derive/manifest) are never read
+		// at build time — don't require them. See resolveAutogenConsumerManifest.
+		if strings.TrimSpace(consumer.ManifestFile) == "" {
 			if strings.TrimSpace(consumer.Root) == "" {
 				failures = append(failures, fmt.Errorf("%s.root is required", fieldPrefix))
 			}
@@ -1673,11 +1681,9 @@ func validateAutogenConfig(cfg AutogenConfig) []error {
 			}
 			failures = append(failures, validateGlobList(fieldPrefix+".include", consumer.Include)...)
 			failures = append(failures, validateAutogenDeriveConfig(fieldPrefix+".derive", consumer.Derive)...)
-		if strings.TrimSpace(consumer.Mode) == "accessory_visualeffects" && headVisualeffectsConfigConfigured(consumer.HeadVisualeffects) {
-			failures = append(failures, validateHeadVisualeffectsConfig(fieldPrefix+".accessory_visualeffects", consumer.HeadVisualeffects)...)
-		}
 			failures = append(failures, validateAutogenManifestConfig(fieldPrefix+".manifest", consumer.Manifest)...)
 		}
+	}
 
 	return failures
 }
@@ -1736,7 +1742,7 @@ func validateGeneratedConfig(cfg GeneratedConfig) []error {
 	return failures
 }
 
-func headVisualeffectsConfigConfigured(cfg HeadVisualeffectsConfig) bool {
+func accessoryVisualeffectsConfigConfigured(cfg AccessoryVisualeffectsConfig) bool {
 	return len(cfg.Groups) > 0 ||
 		strings.TrimSpace(cfg.GroupTokenSource) != "" ||
 		strings.TrimSpace(cfg.CategoryFrom) != "" ||
@@ -1749,7 +1755,7 @@ func headVisualeffectsConfigConfigured(cfg HeadVisualeffectsConfig) bool {
 		len(cfg.RowDefaults) > 0
 }
 
-func validateHeadVisualeffectsConfig(fieldPrefix string, cfg HeadVisualeffectsConfig) []error {
+func validateAccessoryVisualeffectsConfig(fieldPrefix string, cfg AccessoryVisualeffectsConfig) []error {
 	var failures []error
 	groupTokenSource := strings.TrimSpace(cfg.GroupTokenSource)
 	switch groupTokenSource {

internal/project/project_test.go

@@ -46,7 +46,7 @@ haks:
 	}
 }
 
-func TestEffectiveConfigAppliesVisibleToolkitDefaults(t *testing.T) {
+func TestEffectiveConfigReportsConfiguredAndDefaultProvenance(t *testing.T) {
 	root := t.TempDir()
 	writeProjectFile(t, filepath.Join(root, ConfigFile), `
 module:
@@ -62,35 +62,13 @@ paths:
 	}
 
 	effective := proj.EffectiveConfig()
-	if got, want := effective.Paths.Build, "build"; got != want {
+	for _, field := range []string{"module.name", "paths.build"} {
-		t.Fatalf("expected default build path %q, got %q", want, got)
+		if strings.TrimSpace(effective.Provenance[field].Source) == "" {
+			t.Errorf("expected %s to report provenance", field)
 		}
-	if got, want := effective.Outputs.HAKManifest, "haks.json"; got != want {
-		t.Fatalf("expected default HAK manifest %q, got %q", want, got)
 	}
-	if got, want := strings.Join(effective.Extract.Archives, ","), "testmod.mod"; got != want {
+	if effective.Module.Name != "Test Module" {
-		t.Fatalf("expected default extract archives %q, got %q", want, got)
+		t.Fatalf("configured module name was not preserved: %q", effective.Module.Name)
-	}
-	if effective.Extract.ConsumeArchives == nil || *effective.Extract.ConsumeArchives {
-		t.Fatalf("expected default extract consume_archives false, got %#v", effective.Extract.ConsumeArchives)
-	}
-	if got, want := effective.TopData.PackageHAK, "sow_top.hak"; got != want {
-		t.Fatalf("expected default topdata HAK %q, got %q", want, got)
-	}
-	if got, want := strings.Join(effective.Validation.BuiltinScriptPrefixes, ","), "ga_,gc_,gen_,gui_,nw_,nwg_,ta_,x0_,x1_,x2_,x3_"; got != want {
-		t.Fatalf("expected default built-in script prefixes %q, got %q", want, got)
-	}
-	if got := strings.Join(effective.Validation.RequiredFields["ifo"], ","); got != "Mod_Name" {
-		t.Fatalf("expected default IFO required fields, got %#v", effective.Validation.RequiredFields)
-	}
-	if got, want := strings.Join(effective.Music.ConvertExtensions, ","), ".flac,.m4a,.mp3,.ogg,.wav"; got != want {
-		t.Fatalf("expected default music convert extensions %q, got %q", want, got)
-	}
-	if prov := effective.Provenance["paths.build"]; prov.Source != "toolkit default" {
-		t.Fatalf("expected paths.build toolkit default provenance, got %#v", prov)
-	}
-	if prov := effective.Provenance["module.name"]; prov.Source != "yaml" {
-		t.Fatalf("expected module.name YAML provenance, got %#v", prov)
 	}
 }
 
@@ -116,12 +94,16 @@ validation:
 	if err != nil {
 		t.Fatalf("Load returned error: %v", err)
 	}
-	got := strings.Join(proj.EffectiveConfig().Validation.BuiltinScriptPrefixes, ",")
+	effective := proj.EffectiveConfig()
-	if want := "custom_,nw_"; got != want {
+	for _, prefix := range []string{"custom_", "nw_"} {
-		t.Fatalf("expected configured validation prefixes %q, got %q", want, got)
+		if !slices.Contains(effective.Validation.BuiltinScriptPrefixes, prefix) {
+			t.Errorf("configured validation prefixes missing %q: %#v", prefix, effective.Validation.BuiltinScriptPrefixes)
+		}
+	}
+	for _, field := range []string{"Mod_Hak", "Mod_Name"} {
+		if !slices.Contains(effective.Validation.RequiredFields["ifo"], field) {
+			t.Errorf("configured required fields missing %q: %#v", field, effective.Validation.RequiredFields)
 		}
-	if got := strings.Join(proj.EffectiveConfig().Validation.RequiredFields["ifo"], ","); got != "Mod_Hak,Mod_Name" {
-		t.Fatalf("expected configured required fields, got %#v", proj.EffectiveConfig().Validation.RequiredFields)
 	}
 }
 
@@ -853,8 +835,8 @@ paths:
 	if !bytes.Equal(first, second) {
 		t.Fatalf("effective config JSON is not deterministic")
 	}
-	if !bytes.Contains(first, []byte(`"hak_manifest": "haks.json"`)) {
+	if !bytes.Contains(first, []byte(`"name": "Test Module"`)) {
-		t.Fatalf("effective config JSON missing HAK manifest default: %s", first)
+		t.Fatalf("effective config JSON missing configured module name: %s", first)
 	}
 }
 
@@ -1331,7 +1313,7 @@ func TestValidateLayoutRejectsInvalidAutogenConsumerConfig(t *testing.T) {
 	}
 }
 
-func TestValidateLayoutRejectsInvalidHeadVisualeffectsConfig(t *testing.T) {
+func TestValidateLayoutRejectsInvalidAccessoryVisualeffectsConfig(t *testing.T) {
 	root := t.TempDir()
 	mkdirAll(t, filepath.Join(root, "src"))
 	mkdirAll(t, filepath.Join(root, "build"))
@@ -1356,8 +1338,8 @@ func TestValidateLayoutRejectsInvalidHeadVisualeffectsConfig(t *testing.T) {
 							AssetName:  "sow-accessory-vfx-manifest.json",
 							CacheName:  "sow-accessory-vfx-manifest.json",
 						},
-						HeadVisualeffects: HeadVisualeffectsConfig{
+						AccessoryVisualeffects: AccessoryVisualeffectsConfig{
-							Groups: map[string]HeadVisualeffectGroupConfig{
+							Groups: map[string]AccessoryVisualeffectGroupConfig{
 								"head_jewels": {
 									ModelColumns: []string{"Imp Root M Node"},
 								},
@@ -1373,7 +1355,7 @@ func TestValidateLayoutRejectsInvalidHeadVisualeffectsConfig(t *testing.T) {
 
 	err := proj.ValidateLayout()
 	if err == nil {
-		t.Fatal("expected head visualeffects validation error")
+		t.Fatal("expected accessory visualeffects validation error")
 	}
 	for _, needle := range []string{
 		"autogen.consumers[0].accessory_visualeffects.groups[head_jewels].prefix",
@@ -1387,7 +1369,7 @@ func TestValidateLayoutRejectsInvalidHeadVisualeffectsConfig(t *testing.T) {
 	}
 }
 
-func TestValidateLayoutRejectsInvalidHeadVisualeffectsNamingConfig(t *testing.T) {
+func TestValidateLayoutRejectsInvalidAccessoryVisualeffectsNamingConfig(t *testing.T) {
 	root := t.TempDir()
 	mkdirAll(t, filepath.Join(root, "src"))
 	mkdirAll(t, filepath.Join(root, "build"))
@@ -1412,8 +1394,8 @@ func TestValidateLayoutRejectsInvalidHeadVisualeffectsNamingConfig(t *testing.T)
 							AssetName:  "sow-accessory-vfx-manifest.json",
 							CacheName:  "sow-accessory-vfx-manifest.json",
 						},
-						HeadVisualeffects: HeadVisualeffectsConfig{
+						AccessoryVisualeffects: AccessoryVisualeffectsConfig{
-							Groups: map[string]HeadVisualeffectGroupConfig{
+							Groups: map[string]AccessoryVisualeffectGroupConfig{
 								"head_features": {},
 							},
 							GroupTokenSource: "unsupported",
@@ -1429,7 +1411,7 @@ func TestValidateLayoutRejectsInvalidHeadVisualeffectsNamingConfig(t *testing.T)
 
 	err := proj.ValidateLayout()
 	if err == nil {
-		t.Fatal("expected head visualeffects naming validation error")
+		t.Fatal("expected accessory visualeffects naming validation error")
 	}
 	for _, needle := range []string{
 		"autogen.consumers[0].accessory_visualeffects.group_token_source",
@@ -1443,7 +1425,7 @@ func TestValidateLayoutRejectsInvalidHeadVisualeffectsNamingConfig(t *testing.T)
 	}
 }
 
-func TestLoadRejectsLegacyHeadVisualeffectsNamingFields(t *testing.T) {
+func TestLoadRejectsLegacyAccessoryVisualeffectsNamingFields(t *testing.T) {
 	root := t.TempDir()
 	writeProjectFile(t, filepath.Join(root, ConfigFile), `
 module:
@@ -1477,7 +1459,7 @@ autogen:
 
 	_, err := Load(root)
 	if err == nil {
-		t.Fatal("expected legacy head visualeffects naming fields to be rejected")
+		t.Fatal("expected legacy accessory visualeffects naming fields to be rejected")
 	}
 	if !strings.Contains(err.Error(), "legacy_groups") {
 		t.Fatalf("expected legacy_groups unknown field error, got %v", err)

internal/topdata/autogen.go

@@ -3,6 +3,7 @@ package topdata
 import (
 	"bytes"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -16,12 +17,25 @@ import (
 
 const autogenManifestCacheMaxAge = time.Hour
 
+// errAutogenManifestUnavailable marks a released autogen manifest that could not
+// be located or fetched (network failure, missing release/asset, empty payload,
+// or an undeterminable sow-assets repo). It is deliberately distinct from an
+// asset that was found but reports a row removed: for an optional consumer this
+// sentinel triggers a fail-open path that *preserves* the consumer's existing
+// pinned lock entries instead of pruning them, so StrRef/row IDs are not
+// reshuffled while the asset source is merely temporarily out of reach.
+var errAutogenManifestUnavailable = errors.New("autogen manifest unavailable")
+
+func unavailableAutogenManifest(err error) error {
+	return fmt.Errorf("%w: %w", errAutogenManifestUnavailable, err)
+}
+
 type autogenManifest struct {
 	ID                string                           `json:"id"`
 	Repo              string                           `json:"repo"`
 	Ref               string                           `json:"ref"`
 	GeneratedAt       string                           `json:"generated_at"`
-	HeadVisualeffects *project.HeadVisualeffectsConfig `json:"accessory_visualeffects,omitempty"`
+	AccessoryVisualeffects *project.AccessoryVisualeffectsConfig `json:"accessory_visualeffects,omitempty"`
 	Entries           []autogenManifestEntry           `json:"entries"`
 }
 
@@ -61,9 +75,18 @@ func applyAutogenConsumers(p *project.Project, collected []nativeCollectedDatase
 		}
 		manifest, err := resolveAutogenConsumerManifest(p, consumer, progress)
 		if err != nil {
-			if consumer.Optional && isIgnorableOptionalAutogenError(err) {
+			if consumer.Optional && errors.Is(err, errAutogenManifestUnavailable) {
+				// Fail open: the asset manifest is merely unreachable, not
+				// authoritatively empty. Build without its rows, but keep the
+				// consumer's already-pinned lock entries so their IDs are not
+				// freed and reshuffled on a later build once the asset returns.
+				preserved, perr := preserveAutogenConsumerLockEntries(result, consumer)
+				if perr != nil {
+					return nil, perr
+				}
+				result = preserved
 				if progress != nil {
-					progress(fmt.Sprintf("Skipping optional autogen consumer %s: %v", consumer.ID, err))
+					progress(fmt.Sprintf("Autogen consumer %s: released manifest unavailable (%v); preserving existing lock entries, generating no new rows", consumer.ID, err))
 				}
 				continue
 			}
@@ -77,7 +100,7 @@ func applyAutogenConsumers(p *project.Project, collected []nativeCollectedDatase
 		case "parts_rows":
 			result = augmentWithAutogeneratedParts(result, autogenPartsInventory(entries))
 		case "accessory_visualeffects":
-			result, err = augmentWithAutogeneratedHeadVisualeffects(result, entries, consumer, manifest.HeadVisualeffects)
+			result, err = augmentWithAutogeneratedAccessoryVisualeffects(result, entries, consumer, manifest.AccessoryVisualeffects)
 			if err != nil {
 				return nil, err
 			}
@@ -90,35 +113,121 @@ func applyAutogenConsumers(p *project.Project, collected []nativeCollectedDatase
 
 func autogenConsumerTargetsCollectedDataset(collected []nativeCollectedDataset, consumer project.AutogenConsumerConfig) bool {
 	for _, dataset := range collected {
-		switch consumer.Mode {
+		if autogenConsumerTargetsDataset(dataset, consumer) {
-		case "parts_rows":
-			if isAutogenEligiblePartsDataset(dataset) {
 			return true
 		}
-		case "accessory_visualeffects":
-			if dataset.Dataset.Name == "visualeffects" {
-				return true
-			}
-		case "cachedmodels_rows":
-			if dataset.Dataset.Name == "cachedmodels" {
-				return true
-			}
-		}
 	}
 	return false
 }
 
-func isIgnorableOptionalAutogenError(err error) bool {
+// preserveAutogenConsumerLockEntries restores the lock keys that an autogen
-	if err == nil {
+// consumer owns from the on-disk lockfile back into the in-memory dataset,
+// reusing this build's already-collected (and pruned) state. It is called only
+// when the consumer's released manifest is unavailable, so the rows themselves
+// are not regenerated; we just keep the key->ID pins alive. Keys are matched
+// against the consumer's own naming policy so unrelated (authored) rows that were
+// legitimately removed are not resurrected.
+func preserveAutogenConsumerLockEntries(collected []nativeCollectedDataset, consumer project.AutogenConsumerConfig) ([]nativeCollectedDataset, error) {
+	matches := autogenConsumerManagedLockKeyMatcher(consumer)
+	if matches == nil {
+		// No managed-key matcher for this mode: nothing safe to preserve.
+		return collected, nil
+	}
+
+	result := append([]nativeCollectedDataset(nil), collected...)
+	for i, dataset := range result {
+		if !autogenConsumerTargetsDataset(dataset, consumer) {
+			continue
+		}
+		if strings.TrimSpace(dataset.Dataset.LockPath) == "" {
+			continue
+		}
+		onDisk, err := loadLockfile(dataset.Dataset.LockPath)
+		if err != nil {
+			// No readable lockfile means there is nothing pinned to preserve.
+			continue
+		}
+		lockData := dataset.LockData
+		if lockData == nil {
+			lockData = map[string]int{}
+		}
+		restored := 0
+		for key, rowID := range onDisk {
+			if _, present := lockData[key]; present {
+				continue
+			}
+			if !matches(key) {
+				continue
+			}
+			lockData[key] = rowID
+			restored++
+		}
+		if restored == 0 {
+			continue
+		}
+		result[i].LockData = lockData
+		result[i].LockModified = !lockDataEqual(onDisk, lockData)
+	}
+	return result, nil
+}
+
+// autogenConsumerManagedLockKeyMatcher returns a predicate identifying the lock
+// keys an autogen consumer is responsible for, or nil for modes whose keys we
+// cannot scope precisely (in which case preservation is skipped rather than
+// risk resurrecting unrelated keys).
+func autogenConsumerManagedLockKeyMatcher(consumer project.AutogenConsumerConfig) func(string) bool {
+	switch consumer.Mode {
+	case "accessory_visualeffects":
+		policy := resolveAccessoryVisualeffectsPolicy(consumer, nil)
+		delimiter := policy.Delimiter
+		if delimiter == "" {
+			delimiter = "/"
+		}
+		prefix := "visualeffects:"
+		groups := make(map[string]struct{}, len(policy.Groups))
+		for group, groupPolicy := range policy.Groups {
+			token := applyAccessoryVisualeffectCase(accessoryVisualeffectGroupToken(group, groupPolicy, policy), policy)
+			if strings.TrimSpace(token) != "" {
+				groups[token] = struct{}{}
+			}
+		}
+		if len(groups) == 0 {
+			return nil
+		}
+		return func(key string) bool {
+			if !strings.HasPrefix(key, prefix) {
+				return false
+			}
+			rest := key[len(prefix):]
+			idx := strings.Index(rest, delimiter)
+			if idx <= 0 {
+				return false
+			}
+			_, ok := groups[rest[:idx]]
+			return ok
+		}
+	default:
+		return nil
+	}
+}
+
+func autogenConsumerTargetsDataset(dataset nativeCollectedDataset, consumer project.AutogenConsumerConfig) bool {
+	switch consumer.Mode {
+	case "parts_rows":
+		return isAutogenEligiblePartsDataset(dataset)
+	case "accessory_visualeffects":
+		return dataset.Dataset.Name == "visualeffects"
+	case "cachedmodels_rows":
+		return dataset.Dataset.Name == "cachedmodels"
+	default:
 		return false
 	}
-	message := err.Error()
-	return strings.Contains(message, "HTTP 404") ||
-		strings.Contains(message, "not found") ||
-		strings.Contains(message, "entries is empty")
 }
 
 func resolveAutogenConsumerManifest(p *project.Project, consumer project.AutogenConsumerConfig, progress func(string)) (*autogenManifest, error) {
+	if manifestFile := strings.TrimSpace(consumer.ManifestFile); manifestFile != "" {
+		return readAutogenConsumerManifestFile(p, consumer, manifestFile, progress)
+	}
 	overrideRoot, err := resolveAutogenLocalOverrideRoot(p, consumer)
 	if err != nil {
 		return nil, err
@@ -136,6 +245,37 @@ func resolveAutogenConsumerManifest(p *project.Project, consumer project.Autogen
 	return resolveReleasedAutogenManifest(p, consumer, progress)
 }
 
+// readAutogenConsumerManifestFile reads a pre-resolved autogenManifest JSON from
+// a local file (relative paths resolve against the project root). A missing file
+// is an ignorable-optional condition — it returns errAutogenManifestUnavailable
+// so an optional consumer fails open and preserves its pinned lock IDs. A present
+// but malformed file, or an id that disagrees with the consumer's producer, is a
+// hard error.
+func readAutogenConsumerManifestFile(p *project.Project, consumer project.AutogenConsumerConfig, manifestFile string, progress func(string)) (*autogenManifest, error) {
+	path := manifestFile
+	if !filepath.IsAbs(path) {
+		path = filepath.Join(p.Root, path)
+	}
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, unavailableAutogenManifest(fmt.Errorf("manifest file %s not found", path))
+		}
+		return nil, fmt.Errorf("read autogen manifest file %s: %w", path, err)
+	}
+	var manifest autogenManifest
+	if err := json.Unmarshal(raw, &manifest); err != nil {
+		return nil, fmt.Errorf("parse autogen manifest file %s: %w", path, err)
+	}
+	if manifest.ID != "" && manifest.ID != consumer.Producer {
+		return nil, fmt.Errorf("autogen manifest file %s declared id %q, expected %q", path, manifest.ID, consumer.Producer)
+	}
+	if progress != nil {
+		progress(fmt.Sprintf("Reading local autogen manifest for %s from %s...", consumer.ID, path))
+	}
+	return &manifest, nil
+}
+
 func resolveAutogenLocalOverrideRoot(p *project.Project, consumer project.AutogenConsumerConfig) (string, error) {
 	root := strings.TrimSpace(consumer.LocalOverrideRoot)
 	if root != "" {
@@ -366,14 +506,14 @@ func resolveReleasedAutogenManifest(p *project.Project, consumer project.Autogen
 
 	spec, err := deriveSowAssetsRepoSpec(p)
 	if err != nil {
-		return nil, err
+		return nil, unavailableAutogenManifest(err)
 	}
 	manifestURL, err := resolveAutogenManifestAssetURL(spec, consumer.Manifest.ReleaseTag, consumer.Manifest.AssetName)
 	if err != nil {
 		if consumer.Mode == "parts_rows" {
-			return nil, fmt.Errorf("%s", strings.Replace(err.Error(), "autogen manifest", "parts manifest", 1))
+			return nil, unavailableAutogenManifest(fmt.Errorf("%s", strings.Replace(err.Error(), "autogen manifest", "parts manifest", 1)))
 		}
-		return nil, err
+		return nil, unavailableAutogenManifest(err)
 	}
 	if progress != nil {
 		progress(fmt.Sprintf("Fetching released autogen manifest from %s...", manifestURL))
@@ -381,9 +521,9 @@ func resolveReleasedAutogenManifest(p *project.Project, consumer project.Autogen
 	manifest, err := fetchAutogenManifest(manifestURL)
 	if err != nil {
 		if consumer.Mode == "parts_rows" {
-			return nil, fmt.Errorf("%s", strings.Replace(err.Error(), "autogen manifest", "parts manifest", 1))
+			return nil, unavailableAutogenManifest(fmt.Errorf("%s", strings.Replace(err.Error(), "autogen manifest", "parts manifest", 1)))
 		}
-		return nil, err
+		return nil, unavailableAutogenManifest(err)
 	}
 	if manifest.ID != "" && manifest.ID != consumer.Producer {
 		return nil, fmt.Errorf("autogen manifest %s declared id %q, expected %q", consumer.Manifest.AssetName, manifest.ID, consumer.Producer)
@@ -676,12 +816,12 @@ func augmentWithAutogeneratedCachedModels(collected []nativeCollectedDataset, en
 	return result, nil
 }
 
-func augmentWithAutogeneratedHeadVisualeffects(collected []nativeCollectedDataset, entries []autogenManifestEntry, consumer project.AutogenConsumerConfig, manifestPolicy *project.HeadVisualeffectsConfig) ([]nativeCollectedDataset, error) {
+func augmentWithAutogeneratedAccessoryVisualeffects(collected []nativeCollectedDataset, entries []autogenManifestEntry, consumer project.AutogenConsumerConfig, manifestPolicy *project.AccessoryVisualeffectsConfig) ([]nativeCollectedDataset, error) {
 	if len(entries) == 0 {
 		return collected, nil
 	}
 
-	policy := resolveHeadVisualeffectsPolicy(consumer, manifestPolicy)
+	policy := resolveAccessoryVisualeffectsPolicy(consumer, manifestPolicy)
 	result := append([]nativeCollectedDataset(nil), collected...)
 	for i, dataset := range result {
 		if dataset.Dataset.Name != "visualeffects" {
@@ -731,12 +871,12 @@ func augmentWithAutogeneratedHeadVisualeffects(collected []nativeCollectedDatase
 		}
 
 		for _, entry := range entries {
-			key, label, modelStem, groupPolicy, ok := headVisualeffectIdentity(dataset.Dataset.Name, entry, policy)
+			key, label, modelStem, groupPolicy, ok := accessoryVisualeffectIdentity(dataset.Dataset.Name, entry, policy)
 			if !ok {
 				continue
 			}
 			if existing, exists := rowByKey[key]; exists {
-				applyDiscoveredHeadVisualeffectDefaults(existing, dataset.Columns, modelStem, label, policy, groupPolicy)
+				applyDiscoveredAccessoryVisualeffectDefaults(existing, dataset.Columns, modelStem, label, policy, groupPolicy)
 				continue
 			}
 
@@ -749,7 +889,7 @@ func augmentWithAutogeneratedHeadVisualeffects(collected []nativeCollectedDatase
 				}
 				lockData[key] = rowID
 			}
-			newRow := createDefaultHeadVisualeffectRow(dataset.Columns, rowID, key, label, modelStem, policy, groupPolicy)
+			newRow := createDefaultAccessoryVisualeffectRow(dataset.Columns, rowID, key, label, modelStem, policy, groupPolicy)
 			rows = append(rows, newRow)
 			rowByKey[key] = newRow
 		}
@@ -772,8 +912,8 @@ func nextAvailableAutogenID(used map[int]struct{}) int {
 	}
 }
 
-type headVisualeffectsPolicy struct {
+type accessoryVisualeffectsPolicy struct {
-	Groups             map[string]headVisualeffectsGroupPolicy
+	Groups             map[string]accessoryVisualeffectsGroupPolicy
 	GroupTokenSource   string
 	CategoryFrom       string
 	Delimiter          string
@@ -785,22 +925,22 @@ type headVisualeffectsPolicy struct {
 	RowDefaults        map[string]string
 }
 
-type headVisualeffectsGroupPolicy struct {
+type accessoryVisualeffectsGroupPolicy struct {
 	Prefix       string
 	ModelColumns []string
 	RowDefaults  map[string]string
 }
 
-func resolveHeadVisualeffectsPolicy(consumer project.AutogenConsumerConfig, manifestPolicy *project.HeadVisualeffectsConfig) headVisualeffectsPolicy {
+func resolveAccessoryVisualeffectsPolicy(consumer project.AutogenConsumerConfig, manifestPolicy *project.AccessoryVisualeffectsConfig) accessoryVisualeffectsPolicy {
-	policy := defaultHeadVisualeffectsPolicy()
+	policy := defaultAccessoryVisualeffectsPolicy()
 	if manifestPolicy != nil {
-		applyHeadVisualeffectsConfig(&policy, *manifestPolicy)
+		applyAccessoryVisualeffectsConfig(&policy, *manifestPolicy)
 	}
-	applyHeadVisualeffectsConfig(&policy, consumer.HeadVisualeffects)
+	applyAccessoryVisualeffectsConfig(&policy, consumer.AccessoryVisualeffects)
 	return policy
 }
 
-func applyHeadVisualeffectsConfig(policy *headVisualeffectsPolicy, cfg project.HeadVisualeffectsConfig) {
+func applyAccessoryVisualeffectsConfig(policy *accessoryVisualeffectsPolicy, cfg project.AccessoryVisualeffectsConfig) {
 	for group, groupCfg := range cfg.Groups {
 		group = strings.TrimSpace(group)
 		prefix := strings.TrimSpace(groupCfg.Prefix)
@@ -811,13 +951,13 @@ func applyHeadVisualeffectsConfig(policy *headVisualeffectsPolicy, cfg project.H
 		if prefix != "" {
 			groupPolicy.Prefix = prefix
 		}
-		if columns := normalizeHeadVisualeffectsModelColumns(groupCfg.ModelColumn, groupCfg.ModelColumns); len(columns) > 0 {
+		if columns := normalizeAccessoryVisualeffectsModelColumns(groupCfg.ModelColumn, groupCfg.ModelColumns); len(columns) > 0 {
 			groupPolicy.ModelColumns = columns
 		}
 		if groupPolicy.RowDefaults == nil {
 			groupPolicy.RowDefaults = map[string]string{}
 		}
-		mergeStringMap(groupPolicy.RowDefaults, normalizeHeadVisualeffectsRowDefaults(groupCfg.RowDefaults))
+		mergeStringMap(groupPolicy.RowDefaults, normalizeAccessoryVisualeffectsRowDefaults(groupCfg.RowDefaults))
 		policy.Groups[group] = groupPolicy
 	}
 	if strings.TrimSpace(cfg.GroupTokenSource) != "" {
@@ -844,12 +984,12 @@ func applyHeadVisualeffectsConfig(policy *headVisualeffectsPolicy, cfg project.H
 	if strings.TrimSpace(cfg.ModelColumn) != "" {
 		policy.ModelColumn = strings.TrimSpace(cfg.ModelColumn)
 	}
-	mergeStringMap(policy.RowDefaults, normalizeHeadVisualeffectsRowDefaults(cfg.RowDefaults))
+	mergeStringMap(policy.RowDefaults, normalizeAccessoryVisualeffectsRowDefaults(cfg.RowDefaults))
 }
 
-func defaultHeadVisualeffectsPolicy() headVisualeffectsPolicy {
+func defaultAccessoryVisualeffectsPolicy() accessoryVisualeffectsPolicy {
-	return headVisualeffectsPolicy{
+	return accessoryVisualeffectsPolicy{
-		Groups: map[string]headVisualeffectsGroupPolicy{
+		Groups: map[string]accessoryVisualeffectsGroupPolicy{
 			"chest_accessories": {},
 			"head_accessories":  {},
 			"head_decorations":  {},
@@ -871,7 +1011,7 @@ func defaultHeadVisualeffectsPolicy() headVisualeffectsPolicy {
 	}
 }
 
-func normalizeHeadVisualeffectsModelColumns(modelColumn string, modelColumns []string) []string {
+func normalizeAccessoryVisualeffectsModelColumns(modelColumn string, modelColumns []string) []string {
 	var result []string
 	if column := strings.TrimSpace(modelColumn); column != "" {
 		result = append(result, column)
@@ -888,7 +1028,7 @@ func normalizeHeadVisualeffectsModelColumns(modelColumn string, modelColumns []s
 	return result
 }
 
-func normalizeHeadVisualeffectsRowDefaults(defaults map[string]string) map[string]string {
+func normalizeAccessoryVisualeffectsRowDefaults(defaults map[string]string) map[string]string {
 	result := map[string]string{}
 	for column, value := range defaults {
 		column = strings.TrimSpace(column)
@@ -906,44 +1046,44 @@ func mergeStringMap(target map[string]string, source map[string]string) {
 	}
 }
 
-func headVisualeffectIdentity(dataset string, entry autogenManifestEntry, policy headVisualeffectsPolicy) (string, string, string, headVisualeffectsGroupPolicy, bool) {
+func accessoryVisualeffectIdentity(dataset string, entry autogenManifestEntry, policy accessoryVisualeffectsPolicy) (string, string, string, accessoryVisualeffectsGroupPolicy, bool) {
-	entry = normalizeHeadVisualeffectEntry(entry)
+	entry = normalizeAccessoryVisualeffectEntry(entry)
 	group, ok := policy.Groups[entry.Group]
 	if !ok || strings.TrimSpace(entry.ModelStem) == "" {
-		return "", "", "", headVisualeffectsGroupPolicy{}, false
+		return "", "", "", accessoryVisualeffectsGroupPolicy{}, false
 	}
 	modelStem := strings.TrimSpace(entry.ModelStem)
-	stem := stripHeadVisualeffectModelPrefix(modelStem, policy)
+	stem := stripAccessoryVisualeffectModelPrefix(modelStem, policy)
 	stem = strings.TrimSpace(stem)
 	if stem == "" {
-		return "", "", "", headVisualeffectsGroupPolicy{}, false
+		return "", "", "", accessoryVisualeffectsGroupPolicy{}, false
 	}
-	category := headVisualeffectCategory(entry, policy)
+	category := accessoryVisualeffectCategory(entry, policy)
-	groupToken := headVisualeffectGroupToken(entry.Group, group, policy)
+	groupToken := accessoryVisualeffectGroupToken(entry.Group, group, policy)
 	values := map[string]string{
 		"dataset":                dataset,
-		"group":                  applyHeadVisualeffectCase(groupToken, policy),
+		"group":                  applyAccessoryVisualeffectCase(groupToken, policy),
 		"group_raw":              entry.Group,
-		"prefix":                 applyHeadVisualeffectCase(group.Prefix, policy),
+		"prefix":                 applyAccessoryVisualeffectCase(group.Prefix, policy),
-		"category":               applyHeadVisualeffectCase(category, policy),
+		"category":               applyAccessoryVisualeffectCase(category, policy),
 		"category_upper":         strings.ToUpper(category),
-		"category_segment":       headVisualeffectDelimitedSegment(applyHeadVisualeffectCase(category, policy), policy.Delimiter),
+		"category_segment":       accessoryVisualeffectDelimitedSegment(applyAccessoryVisualeffectCase(category, policy), policy.Delimiter),
-		"category_segment_upper": headVisualeffectDelimitedSegment(strings.ToUpper(category), policy.Delimiter),
+		"category_segment_upper": accessoryVisualeffectDelimitedSegment(strings.ToUpper(category), policy.Delimiter),
-		"subgroup":               applyHeadVisualeffectCase(entry.Subgroup, policy),
+		"subgroup":               applyAccessoryVisualeffectCase(entry.Subgroup, policy),
-		"stem":                   applyHeadVisualeffectCase(stem, policy),
+		"stem":                   applyAccessoryVisualeffectCase(stem, policy),
 		"stem_upper":             strings.ToUpper(stem),
 		"model_stem":             modelStem,
 		"delimiter":              policy.Delimiter,
 	}
-	key := expandHeadVisualeffectsFormat(policy.KeyFormat, values)
+	key := expandAccessoryVisualeffectsFormat(policy.KeyFormat, values)
-	label := expandHeadVisualeffectsFormat(policy.LabelFormat, values)
+	label := expandAccessoryVisualeffectsFormat(policy.LabelFormat, values)
 	if strings.TrimSpace(key) == "" || strings.TrimSpace(label) == "" {
-		return "", "", "", headVisualeffectsGroupPolicy{}, false
+		return "", "", "", accessoryVisualeffectsGroupPolicy{}, false
 	}
 	return key, label, modelStem, group, true
 }
 
-func normalizeHeadVisualeffectEntry(entry autogenManifestEntry) autogenManifestEntry {
+func normalizeAccessoryVisualeffectEntry(entry autogenManifestEntry) autogenManifestEntry {
 	entry.Group = strings.TrimSpace(entry.Group)
 	if strings.TrimSpace(entry.Group) == "" && strings.TrimSpace(entry.Source) != "" {
 		parts := strings.Split(filepath.ToSlash(entry.Source), "/")
@@ -966,7 +1106,7 @@ func normalizeHeadVisualeffectEntry(entry autogenManifestEntry) autogenManifestE
 	return entry
 }
 
-func stripHeadVisualeffectModelPrefix(modelStem string, policy headVisualeffectsPolicy) string {
+func stripAccessoryVisualeffectModelPrefix(modelStem string, policy accessoryVisualeffectsPolicy) string {
 	stem := modelStem
 	for _, prefix := range policy.StripModelPrefixes {
 		prefix = strings.TrimSpace(prefix)
@@ -978,7 +1118,7 @@ func stripHeadVisualeffectModelPrefix(modelStem string, policy headVisualeffects
 	return stem
 }
 
-func headVisualeffectGroupToken(groupName string, group headVisualeffectsGroupPolicy, policy headVisualeffectsPolicy) string {
+func accessoryVisualeffectGroupToken(groupName string, group accessoryVisualeffectsGroupPolicy, policy accessoryVisualeffectsPolicy) string {
 	if policy.GroupTokenSource == "folder_name" {
 		return groupName
 	}
@@ -988,7 +1128,7 @@ func headVisualeffectGroupToken(groupName string, group headVisualeffectsGroupPo
 	return groupName
 }
 
-func headVisualeffectCategory(entry autogenManifestEntry, policy headVisualeffectsPolicy) string {
+func accessoryVisualeffectCategory(entry autogenManifestEntry, policy accessoryVisualeffectsPolicy) string {
 	switch policy.CategoryFrom {
 	case "immediate_parent":
 		return strings.TrimSpace(entry.Category)
@@ -999,14 +1139,14 @@ func headVisualeffectCategory(entry autogenManifestEntry, policy headVisualeffec
 	}
 }
 
-func headVisualeffectDelimitedSegment(value, delimiter string) string {
+func accessoryVisualeffectDelimitedSegment(value, delimiter string) string {
 	if strings.TrimSpace(value) == "" {
 		return ""
 	}
 	return value + delimiter
 }
 
-func applyHeadVisualeffectCase(value string, policy headVisualeffectsPolicy) string {
+func applyAccessoryVisualeffectCase(value string, policy accessoryVisualeffectsPolicy) string {
 	switch policy.Case {
 	case "lower":
 		return strings.ToLower(value)
@@ -1017,7 +1157,7 @@ func applyHeadVisualeffectCase(value string, policy headVisualeffectsPolicy) str
 	}
 }
 
-func expandHeadVisualeffectsFormat(format string, values map[string]string) string {
+func expandAccessoryVisualeffectsFormat(format string, values map[string]string) string {
 	result := format
 	for key, value := range values {
 		result = strings.ReplaceAll(result, "{"+key+"}", value)
@@ -1025,7 +1165,7 @@ func expandHeadVisualeffectsFormat(format string, values map[string]string) stri
 	return result
 }
 
-func createDefaultHeadVisualeffectRow(columns []string, rowID int, key, label, modelStem string, policy headVisualeffectsPolicy, group headVisualeffectsGroupPolicy) map[string]any {
+func createDefaultAccessoryVisualeffectRow(columns []string, rowID int, key, label, modelStem string, policy accessoryVisualeffectsPolicy, group accessoryVisualeffectsGroupPolicy) map[string]any {
 	row := map[string]any{
 		"id":  rowID,
 		"key": key,
@@ -1040,13 +1180,13 @@ func createDefaultHeadVisualeffectRow(columns []string, rowID int, key, label, m
 	for column, value := range group.RowDefaults {
 		row[column] = value
 	}
-	for _, column := range headVisualeffectModelColumns(policy, group) {
+	for _, column := range accessoryVisualeffectModelColumns(policy, group) {
 		row[column] = modelStem
 	}
 	return row
 }
 
-func applyDiscoveredHeadVisualeffectDefaults(row map[string]any, columns []string, modelStem, label string, policy headVisualeffectsPolicy, group headVisualeffectsGroupPolicy) {
+func applyDiscoveredAccessoryVisualeffectDefaults(row map[string]any, columns []string, modelStem, label string, policy accessoryVisualeffectsPolicy, group accessoryVisualeffectsGroupPolicy) {
 	if isNullLikeValue(row["Label"]) {
 		row["Label"] = label
 	}
@@ -1060,7 +1200,7 @@ func applyDiscoveredHeadVisualeffectDefaults(row map[string]any, columns []strin
 			row[column] = value
 		}
 	}
-	for _, column := range headVisualeffectModelColumns(policy, group) {
+	for _, column := range accessoryVisualeffectModelColumns(policy, group) {
 		if isNullLikeValue(row[column]) {
 			row[column] = modelStem
 		}
@@ -1072,7 +1212,7 @@ func applyDiscoveredHeadVisualeffectDefaults(row map[string]any, columns []strin
 	}
 }
 
-func headVisualeffectModelColumns(policy headVisualeffectsPolicy, group headVisualeffectsGroupPolicy) []string {
+func accessoryVisualeffectModelColumns(policy accessoryVisualeffectsPolicy, group accessoryVisualeffectsGroupPolicy) []string {
 	if len(group.ModelColumns) > 0 {
 		return group.ModelColumns
 	}
@@ -1090,14 +1230,14 @@ func formatAutogenManifest(root string, producer project.AutogenProducerConfig,
 		GeneratedAt: time.Now().UTC().Format(time.RFC3339),
 		Entries:     entries,
 	}
-	if autogenHeadVisualeffectsConfigConfigured(producer.HeadVisualeffects) {
+	if autogenAccessoryVisualeffectsConfigConfigured(producer.AccessoryVisualeffects) {
-		cfg := producer.HeadVisualeffects
+		cfg := producer.AccessoryVisualeffects
-		manifest.HeadVisualeffects = &cfg
+		manifest.AccessoryVisualeffects = &cfg
 	}
 	return json.MarshalIndent(manifest, "", "  ")
 }
 
-func autogenHeadVisualeffectsConfigConfigured(cfg project.HeadVisualeffectsConfig) bool {
+func autogenAccessoryVisualeffectsConfigConfigured(cfg project.AccessoryVisualeffectsConfig) bool {
 	return len(cfg.Groups) > 0 ||
 		strings.TrimSpace(cfg.GroupTokenSource) != "" ||
 		strings.TrimSpace(cfg.CategoryFrom) != "" ||

internal/topdata/autogen_manifest_file_test.go

@@ -0,0 +1,103 @@
+package topdata
+
+import (
+	"path/filepath"
+	"testing"
+
+	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/project"
+)
+
+// The manifest_file branch reads a local autogenManifest JSON, augments the
+// visualeffects dataset from its entries, and assigns lock IDs — no network.
+func TestApplyAutogenConsumersReadsManifestFile(t *testing.T) {
+	root := testProjectRoot(t)
+	manifestPath := filepath.Join(root, ".cache", "sow-accessory-vfx-manifest.json")
+	mkdirAll(t, filepath.Join(root, ".cache"))
+	writeFile(t, manifestPath, `{
+  "id": "accessory_visualeffects",
+  "repo": "ShadowsOverWestgate/sow-assets-manifest",
+  "ref": "v1.2.3",
+  "generated_at": "2026-06-21T00:00:00Z",
+  "entries": [
+    {"source": "head_accessories/hat/hfx_bandana.mdl", "model_stem": "hfx_bandana", "group": "head_accessories", "subgroup": "hat"}
+  ]
+}`+"\n")
+
+	p := testProject(root)
+	p.Config.Autogen.Consumers = []project.AutogenConsumerConfig{
+		{
+			ID:           "accessory_visualeffects",
+			Producer:     "accessory_visualeffects",
+			Dataset:      "visualeffects",
+			Mode:         "accessory_visualeffects",
+			Optional:     true,
+			ManifestFile: ".cache/sow-accessory-vfx-manifest.json",
+		},
+	}
+
+	collected := []nativeCollectedDataset{
+		{
+			Dataset: nativeDataset{Name: "visualeffects", Kind: nativeDatasetBase},
+			Columns: []string{"Label", "Type_FD", "OrientWithGround", "Imp_HeadCon_Node", "OrientWithObject"},
+			Rows:    nil,
+			LockData: map[string]int{
+				"visualeffects:existing": 17,
+			},
+		},
+	}
+
+	got, err := applyAutogenConsumers(p, collected, nil)
+	if err != nil {
+		t.Fatalf("applyAutogenConsumers failed: %v", err)
+	}
+	if len(got) != 1 || len(got[0].Rows) != 1 {
+		t.Fatalf("expected one autogenerated row, got %#v", got)
+	}
+	row := got[0].Rows[0]
+	if row["key"] != "visualeffects:head_accessories/hat/bandana" || row["Imp_HeadCon_Node"] != "hfx_bandana" {
+		t.Fatalf("unexpected generated row: %#v", row)
+	}
+	if _, ok := got[0].LockData["visualeffects:head_accessories/hat/bandana"]; !ok {
+		t.Fatalf("expected lock id for generated accessory, got %#v", got[0].LockData)
+	}
+	// Authored key untouched.
+	if got[0].LockData["visualeffects:existing"] != 17 {
+		t.Fatalf("expected authored lock id retained at 17, got %#v", got[0].LockData)
+	}
+}
+
+// A missing manifest_file is an ignorable-optional condition: the optional
+// consumer fails open (no rows) and preserves existing lock IDs.
+func TestApplyAutogenConsumersMissingManifestFileFailsOpen(t *testing.T) {
+	root := testProjectRoot(t)
+	lockPath := filepath.Join(root, "visualeffects-lock.json")
+	writeFile(t, lockPath, `{"visualeffects:head_accessories/hat/bandana":10101}`+"\n")
+
+	p := testProject(root)
+	p.Config.Autogen.Consumers = []project.AutogenConsumerConfig{
+		{
+			ID:           "accessory_visualeffects",
+			Producer:     "accessory_visualeffects",
+			Dataset:      "visualeffects",
+			Mode:         "accessory_visualeffects",
+			Optional:     true,
+			ManifestFile: ".cache/does-not-exist.json",
+		},
+	}
+	collected := []nativeCollectedDataset{
+		{
+			Dataset:  nativeDataset{Name: "visualeffects", Kind: nativeDatasetBase, LockPath: lockPath},
+			Columns:  []string{"Label"},
+			Rows:     nil,
+			LockData: map[string]int{},
+		},
+	}
+
+	got, err := applyAutogenConsumers(p, collected, nil)
+	if err != nil {
+		t.Fatalf("expected fail-open, got error: %v", err)
+	}
+	if id, ok := got[0].LockData["visualeffects:head_accessories/hat/bandana"]; !ok || id != 10101 {
+		t.Fatalf("expected preserved lock id 10101, got %v (present=%v)", id, ok)
+	}
+}

internal/topdata/autogen_preserve_test.go

@@ -0,0 +1,109 @@
+package topdata
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+
+	"git.westgate.pw/ShadowsOverWestgate/sow-tools/internal/project"
+)
+
+// When an optional autogen consumer's released manifest cannot be fetched, the
+// build must fail open: it keeps the consumer's already-pinned lock entries
+// (so their IDs are not freed and reshuffled later) and generates no new rows.
+func TestApplyAutogenConsumersPreservesLockEntriesWhenManifestUnavailable(t *testing.T) {
+	root := testProjectRoot(t)
+
+	// 404 for every request → released manifest is unavailable (not empty).
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.NotFound(w, r)
+	}))
+	t.Cleanup(srv.Close)
+	t.Setenv("SOW_ASSETS_SERVER_URL", srv.URL)
+	t.Setenv("SOW_ASSETS_REPO", "ShadowsOverWestgate/sow-assets")
+
+	p := testProject(root)
+	p.Config.Autogen.Consumers = []project.AutogenConsumerConfig{
+		{
+			ID:       "accessory_visualeffects",
+			Producer: "accessory_visualeffects",
+			Dataset:  "visualeffects",
+			Mode:     "accessory_visualeffects",
+			Optional: true,
+			Root:     "vfxs",
+			Include:  []string{"head_accessories/**/*.mdl"},
+			Derive:   project.AutogenDeriveConfig{Kind: "model_stem", GroupFrom: "first_path_segment"},
+			Manifest: project.AutogenManifestConfig{ReleaseTag: "head-vfx-manifest-current", AssetName: "sow-accessory-vfx-manifest.json", CacheName: "sow-accessory-vfx-manifest.json"},
+		},
+	}
+
+	// On-disk lock pins an autogen-owned accessory key plus an authored key.
+	lockPath := filepath.Join(root, "visualeffects-lock.json")
+	writeFile(t, lockPath, `{"visualeffects:existing":17,"visualeffects:head_accessories/hat/bandana":10101}`+"\n")
+
+	// Simulate post-prune collected state: the accessory key has already been
+	// dropped from in-memory LockData (as pruneLockDataToActiveRows would do).
+	collected := []nativeCollectedDataset{
+		{
+			Dataset:  nativeDataset{Name: "visualeffects", Kind: nativeDatasetBase, LockPath: lockPath},
+			Columns:  []string{"Label"},
+			Rows:     []map[string]any{{"id": 17, "key": "visualeffects:existing"}},
+			LockData: map[string]int{"visualeffects:existing": 17},
+		},
+	}
+
+	got, err := applyAutogenConsumers(p, collected, nil)
+	if err != nil {
+		t.Fatalf("expected fail-open build, got error: %v", err)
+	}
+	if len(got) != 1 {
+		t.Fatalf("expected one dataset, got %d", len(got))
+	}
+
+	// The pinned accessory id must survive with its exact value (no jumble).
+	if id, ok := got[0].LockData["visualeffects:head_accessories/hat/bandana"]; !ok || id != 10101 {
+		t.Fatalf("expected preserved accessory lock id 10101, got %v (present=%v) lock=%#v", id, ok, got[0].LockData)
+	}
+	// The authored key is untouched.
+	if id, ok := got[0].LockData["visualeffects:existing"]; !ok || id != 17 {
+		t.Fatalf("expected authored key retained at 17, got %#v", got[0].LockData)
+	}
+	// No row is generated for the unavailable accessory entry.
+	for _, row := range got[0].Rows {
+		if key, _ := row["key"].(string); key == "visualeffects:head_accessories/hat/bandana" {
+			t.Fatalf("expected no generated row while manifest unavailable, got %#v", row)
+		}
+	}
+}
+
+// A key that is NOT owned by the consumer (an authored row legitimately removed)
+// must not be resurrected by the preservation path.
+func TestPreserveAutogenConsumerLockEntriesIgnoresUnownedKeys(t *testing.T) {
+	root := testProjectRoot(t)
+	lockPath := filepath.Join(root, "visualeffects-lock.json")
+	writeFile(t, lockPath, `{"visualeffects:retired_authored":3,"visualeffects:head_accessories/hat/bandana":10101}`+"\n")
+
+	consumer := project.AutogenConsumerConfig{
+		ID:      "accessory_visualeffects",
+		Dataset: "visualeffects",
+		Mode:    "accessory_visualeffects",
+	}
+	collected := []nativeCollectedDataset{
+		{
+			Dataset:  nativeDataset{Name: "visualeffects", Kind: nativeDatasetBase, LockPath: lockPath},
+			LockData: map[string]int{},
+		},
+	}
+
+	got, err := preserveAutogenConsumerLockEntries(collected, consumer)
+	if err != nil {
+		t.Fatalf("preserveAutogenConsumerLockEntries failed: %v", err)
+	}
+	if _, ok := got[0].LockData["visualeffects:head_accessories/hat/bandana"]; !ok {
+		t.Fatalf("expected owned accessory key preserved, got %#v", got[0].LockData)
+	}
+	if _, ok := got[0].LockData["visualeffects:retired_authored"]; ok {
+		t.Fatalf("expected unowned authored key NOT resurrected, got %#v", got[0].LockData)
+	}
+}

internal/topdata/damagetypes_registry.go

@@ -21,16 +21,20 @@ type damagetypesRegistry struct {
 	Types    []map[string]any
 }
 
-func collectGeneratedRegistryDatasets(dataDir string) ([]nativeCollectedDataset, error) {
+// collectGeneratedRegistryDatasets projects the registry datasets. When
-	itempropsDatasets, err := collectItempropsRegistryDatasets(dataDir)
+// persistLocks is true (the build pipeline) newly allocated ids are written
+// back to the source lockfiles; when false (validation, discovery, queries)
+// collection is read-only and never touches the source tree.
+func collectGeneratedRegistryDatasets(dataDir string, persistLocks bool) ([]nativeCollectedDataset, error) {
+	itempropsDatasets, err := collectItempropsRegistryDatasets(dataDir, persistLocks)
 	if err != nil {
 		return nil, err
 	}
-	damagetypeDatasets, err := collectDamagetypesRegistryDatasets(dataDir)
+	damagetypeDatasets, err := collectDamagetypesRegistryDatasets(dataDir, persistLocks)
 	if err != nil {
 		return nil, err
 	}
-	racialtypesDatasets, err := collectRacialtypesRegistryDatasets(dataDir)
+	racialtypesDatasets, err := collectRacialtypesRegistryDatasets(dataDir, persistLocks)
 	if err != nil {
 		return nil, err
 	}
@@ -70,7 +74,7 @@ func loadDamagetypesRegistry(dataDir string) (*damagetypesRegistry, error) {
 	}, nil
 }
 
-func collectDamagetypesRegistryDatasets(dataDir string) ([]nativeCollectedDataset, error) {
+func collectDamagetypesRegistryDatasets(dataDir string, persistLocks bool) ([]nativeCollectedDataset, error) {
 	registry, err := loadDamagetypesRegistry(dataDir)
 	if err != nil {
 		return nil, err
@@ -83,7 +87,7 @@ func collectDamagetypesRegistryDatasets(dataDir string) ([]nativeCollectedDatase
 	if err != nil {
 		return nil, err
 	}
-	if lockModified {
+	if lockModified && persistLocks {
 		if err := saveLockfile(registry.LockPath, registry.LockData); err != nil {
 			return nil, err
 		}

internal/topdata/editorconfig_format.go

@@ -203,8 +203,23 @@ func editorConfigPatternMatches(pattern, relativePath string) (bool, error) {
 }
 
 func editorConfigGlobRegexp(pattern string) (string, error) {
+	body, err := translateEditorConfigGlobSegment(pattern)
+	if err != nil {
+		return "", err
+	}
+	expression := "^" + body + "$"
+	if _, err := regexp.Compile(expression); err != nil {
+		return "", err
+	}
+	return expression, nil
+}
+
+// translateEditorConfigGlobSegment converts an editorconfig glob into a regular
+// expression body. In addition to *, **, and ?, it implements brace expansion:
+// comma lists ({a,b,c}) become alternations and numeric ranges ({n..m}) expand
+// to the integers in the range, matching the editorconfig specification.
+func translateEditorConfigGlobSegment(pattern string) (string, error) {
 	var builder strings.Builder
-	builder.WriteByte('^')
 	for index := 0; index < len(pattern); {
 		char := pattern[index]
 		switch char {
@@ -220,22 +235,132 @@ func editorConfigGlobRegexp(pattern string) (string, error) {
 				continue
 			}
 			builder.WriteString("[^/]*")
+			index++
 		case '?':
 			builder.WriteString("[^/]")
-		case '.', '+', '(', ')', '|', '^', '$', '{', '}', '[', ']', '\\':
-			builder.WriteByte('\\')
-			builder.WriteByte(char)
-		default:
-			builder.WriteByte(char)
-		}
 			index++
+		case '{':
+			end := matchingEditorConfigBrace(pattern, index)
+			if end < 0 {
+				// An unbalanced brace is matched literally.
+				builder.WriteString("\\{")
+				index++
+				continue
 			}
-	builder.WriteByte('$')
+			expansion, err := expandEditorConfigBrace(pattern[index+1 : end])
-	expression := builder.String()
+			if err != nil {
-	if _, err := regexp.Compile(expression); err != nil {
 				return "", err
 			}
-	return expression, nil
+			builder.WriteString(expansion)
+			index = end + 1
+		case '.', '+', '(', ')', '|', '^', '$', '}', '[', ']', '\\':
+			builder.WriteByte('\\')
+			builder.WriteByte(char)
+			index++
+		default:
+			builder.WriteByte(char)
+			index++
+		}
+	}
+	return builder.String(), nil
+}
+
+// matchingEditorConfigBrace returns the index of the '}' that closes the '{' at
+// open, accounting for nesting, or -1 when the braces are unbalanced.
+func matchingEditorConfigBrace(pattern string, open int) int {
+	depth := 0
+	for index := open; index < len(pattern); index++ {
+		switch pattern[index] {
+		case '{':
+			depth++
+		case '}':
+			depth--
+			if depth == 0 {
+				return index
+			}
+		}
+	}
+	return -1
+}
+
+// expandEditorConfigBrace turns the body of a brace expression into a regex
+// fragment. A comma list becomes an alternation; a lone "n..m" body becomes a
+// numeric range. A body with neither comma nor range is treated as literal
+// braces, matching the editorconfig reference implementation.
+func expandEditorConfigBrace(inner string) (string, error) {
+	options := splitTopLevelBraceCommas(inner)
+	if len(options) == 1 {
+		if rangeExpr, ok, err := editorConfigNumericRange(inner); err != nil {
+			return "", err
+		} else if ok {
+			return rangeExpr, nil
+		}
+		segment, err := translateEditorConfigGlobSegment(inner)
+		if err != nil {
+			return "", err
+		}
+		return "\\{" + segment + "\\}", nil
+	}
+	parts := make([]string, 0, len(options))
+	for _, option := range options {
+		segment, err := translateEditorConfigGlobSegment(option)
+		if err != nil {
+			return "", err
+		}
+		parts = append(parts, segment)
+	}
+	return "(?:" + strings.Join(parts, "|") + ")", nil
+}
+
+// splitTopLevelBraceCommas splits a brace body on commas that are not nested
+// inside an inner brace group.
+func splitTopLevelBraceCommas(inner string) []string {
+	parts := []string{}
+	depth := 0
+	start := 0
+	for index := 0; index < len(inner); index++ {
+		switch inner[index] {
+		case '{':
+			depth++
+		case '}':
+			depth--
+		case ',':
+			if depth == 0 {
+				parts = append(parts, inner[start:index])
+				start = index + 1
+			}
+		}
+	}
+	return append(parts, inner[start:])
+}
+
+// editorConfigNumericRange expands "n..m" into an alternation of the integers
+// in [n, m]. It returns ok=false when the body is not a numeric range.
+func editorConfigNumericRange(inner string) (string, bool, error) {
+	separator := strings.Index(inner, "..")
+	if separator < 0 {
+		return "", false, nil
+	}
+	low, err := strconv.Atoi(strings.TrimSpace(inner[:separator]))
+	if err != nil {
+		return "", false, nil
+	}
+	high, err := strconv.Atoi(strings.TrimSpace(inner[separator+2:]))
+	if err != nil {
+		return "", false, nil
+	}
+	if low > high {
+		low, high = high, low
+	}
+	const maxRangeSize = 65536
+	if high-low >= maxRangeSize {
+		return "", false, fmt.Errorf("editorconfig numeric range {%s} is too large", inner)
+	}
+	parts := make([]string, 0, high-low+1)
+	for value := low; value <= high; value++ {
+		parts = append(parts, strconv.Itoa(value))
+	}
+	return "(?:" + strings.Join(parts, "|") + ")", true, nil
 }
 
 func pathBase(path string) string {

internal/topdata/editorconfig_glob_test.go

@@ -0,0 +1,56 @@
+package topdata
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestEditorConfigPatternMatchesBraceExpansion(t *testing.T) {
+	cases := []struct {
+		pattern string
+		path    string
+		want    bool
+	}{
+		{"*.{json,jsonc}", "lock.json", true},
+		{"*.{json,jsonc}", "types.jsonc", true},
+		{"*.{json,jsonc}", "notes.md", false},
+		{"*.{js,ts,tsx}", "main.tsx", true},
+		{"{foo,bar}.txt", "bar.txt", true},
+		{"{foo,bar}.txt", "baz.txt", false},
+		{"page{1..3}.json", "page2.json", true},
+		{"page{1..3}.json", "page4.json", false},
+		// No comma and not a range: editorconfig treats braces literally.
+		{"{single}.txt", "{single}.txt", true},
+		{"{single}.txt", "single.txt", false},
+	}
+	for _, c := range cases {
+		got, err := editorConfigPatternMatches(c.pattern, c.path)
+		if err != nil {
+			t.Fatalf("pattern %q path %q: %v", c.pattern, c.path, err)
+		}
+		if got != c.want {
+			t.Errorf("editorConfigPatternMatches(%q, %q) = %v, want %v", c.pattern, c.path, got, c.want)
+		}
+	}
+}
+
+func TestSaveLockfileHonorsBraceGlobIndentSize(t *testing.T) {
+	root := t.TempDir()
+	writeFile(t, filepath.Join(root, ".editorconfig"), "root = true\n\n[*]\nindent_style = space\nindent_size = 2\n\n[*.{json,jsonc}]\nindent_size = 4\n")
+	lockPath := filepath.Join(root, "data", "damagetypes", "registry", "lock.json")
+	mkdirAll(t, filepath.Dir(lockPath))
+	writeFile(t, lockPath, "{\n  \"damagetype:acid\": 4\n}\n")
+
+	if err := saveLockfile(lockPath, map[string]int{"damagetype:acid": 4}); err != nil {
+		t.Fatalf("saveLockfile: %v", err)
+	}
+	got, err := os.ReadFile(lockPath)
+	if err != nil {
+		t.Fatalf("read lockfile: %v", err)
+	}
+	want := "{\n    \"damagetype:acid\": 4\n}\n"
+	if string(got) != want {
+		t.Fatalf("expected 4-space indent resolved from [*.{json,jsonc}]; got:\n%q", string(got))
+	}
+}

internal/topdata/itemprops_registry.go

@@ -166,7 +166,7 @@ func loadRegistryRows(path string) ([]map[string]any, error) {
 	return rows, nil
 }
 
-func collectItempropsRegistryDatasets(dataDir string) ([]nativeCollectedDataset, error) {
+func collectItempropsRegistryDatasets(dataDir string, persistLocks bool) ([]nativeCollectedDataset, error) {
 	registry, err := loadItempropsRegistry(dataDir)
 	if err != nil {
 		return nil, err
@@ -188,7 +188,7 @@ func collectItempropsRegistryDatasets(dataDir string) ([]nativeCollectedDataset,
 		return nil, err
 	}
 	lockModified = lockModified || costModified || paramModified
-	if lockModified {
+	if lockModified && persistLocks {
 		if err := saveLockfile(registry.LockPath, registry.LockData); err != nil {
 			return nil, err
 		}

internal/topdata/native.go

@@ -398,7 +398,7 @@ func buildNativeUnchecked(p *project.Project, opts NativeBuildOptions, progress
 	datasets = applyTopDataValueEncodings(datasets, p.Config.TopData.ValueEncodings)
 	datasets = applyTopDataValueDefaults(datasets, p.Config.TopData.ValueDefaults)
 	datasets = applyTopDataRowGeneration(datasets, p.Config.TopData.RowGeneration)
-	registryDatasets, err := collectGeneratedRegistryDatasets(dataDir)
+	registryDatasets, err := collectGeneratedRegistryDatasets(dataDir, true)
 	if err != nil {
 		return BuildResult{}, err
 	}
@@ -1073,7 +1073,7 @@ func discoverNativeOutputCatalog(dataDir string) (map[string]string, error) {
 	if err != nil {
 		return nil, err
 	}
-	registryDatasets, err := collectGeneratedRegistryDatasets(dataDir)
+	registryDatasets, err := collectGeneratedRegistryDatasets(dataDir, false)
 	if err != nil {
 		return nil, err
 	}

internal/topdata/racialtypes_registry.go

@@ -120,7 +120,7 @@ func loadRacialtypesRegistryRaceRows(dir string) ([]map[string]any, error) {
 	return rows, nil
 }
 
-func collectRacialtypesRegistryDatasets(dataDir string) ([]nativeCollectedDataset, error) {
+func collectRacialtypesRegistryDatasets(dataDir string, persistLocks bool) ([]nativeCollectedDataset, error) {
 	registry, err := loadRacialtypesRegistry(dataDir)
 	if err != nil {
 		return nil, err
@@ -138,7 +138,7 @@ func collectRacialtypesRegistryDatasets(dataDir string) ([]nativeCollectedDatase
 		return nil, err
 	}
 	lockModified = lockModified || raceLockModified
-	if lockModified {
+	if lockModified && persistLocks {
 		if err := saveLockfile(registry.LockPath, registry.LockData); err != nil {
 			return nil, err
 		}

internal/topdata/registry_readonly_test.go

@@ -0,0 +1,64 @@
+package topdata
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+const damagetypesRegistryTestTypes = `{
+  "rows": [
+    {"id": 0, "key": "damagetype:bludgeoning", "label": "Bludgeoning", "group_label": "Physical", "damage_type_group": 0},
+    {"id": 1, "key": "damagetype:piercing", "label": "Piercing", "group_label": "Physical", "damage_type_group": 0}
+  ]
+}
+`
+
+// validate-topdata must never modify source lockfiles. Collection in read-only
+// mode must leave the registry lock byte-identical even though the rows carry
+// explicit ids that would otherwise mark the lock "modified".
+func TestCollectGeneratedRegistryDatasetsReadOnlyDoesNotWriteLock(t *testing.T) {
+	dataDir := t.TempDir()
+	regDir := filepath.Join(dataDir, "damagetypes", "registry")
+	mkdirAll(t, regDir)
+	writeFile(t, filepath.Join(regDir, "types.json"), damagetypesRegistryTestTypes)
+
+	lockPath := filepath.Join(regDir, "lock.json")
+	original := "{\n    \"damagetype:bludgeoning\": 0,\n    \"damagetype:piercing\": 1\n}\n"
+	writeFile(t, lockPath, original)
+
+	if _, err := collectGeneratedRegistryDatasets(dataDir, false); err != nil {
+		t.Fatalf("read-only collection failed: %v", err)
+	}
+
+	got, err := os.ReadFile(lockPath)
+	if err != nil {
+		t.Fatalf("read lockfile: %v", err)
+	}
+	if string(got) != original {
+		t.Fatalf("read-only collection must not modify lockfile.\nwant: %q\ngot:  %q", original, string(got))
+	}
+}
+
+// build-topdata still persists allocated ids to source lockfiles.
+func TestCollectGeneratedRegistryDatasetsPersistWritesLock(t *testing.T) {
+	dataDir := t.TempDir()
+	regDir := filepath.Join(dataDir, "damagetypes", "registry")
+	mkdirAll(t, regDir)
+	writeFile(t, filepath.Join(regDir, "types.json"), damagetypesRegistryTestTypes)
+
+	lockPath := filepath.Join(regDir, "lock.json")
+	writeFile(t, lockPath, "{\n    \"damagetype:bludgeoning\": 0\n}\n")
+
+	if _, err := collectGeneratedRegistryDatasets(dataDir, true); err != nil {
+		t.Fatalf("persisting collection failed: %v", err)
+	}
+
+	lockData, err := loadLockfile(lockPath)
+	if err != nil {
+		t.Fatalf("load lockfile: %v", err)
+	}
+	if lockData["damagetype:piercing"] != 1 {
+		t.Fatalf("persisting collection should record allocated id; got %#v", lockData)
+	}
+}

internal/topdata/top_package.go

@@ -557,7 +557,7 @@ func expectedCompiled2DAOutputs(p *project.Project) (map[string]struct{}, error)
 	if err != nil {
 		return nil, err
 	}
-	registryDatasets, err := collectGeneratedRegistryDatasets(dataDir)
+	registryDatasets, err := collectGeneratedRegistryDatasets(dataDir, false)
 	if err != nil {
 		return nil, err
 	}

internal/topdata/topdata.go

@@ -1320,7 +1320,7 @@ func validateNativeOutputCatalog(dataDir string, report *ValidationReport) {
 		})
 		return
 	}
-	registryDatasets, err := collectGeneratedRegistryDatasets(dataDir)
+	registryDatasets, err := collectGeneratedRegistryDatasets(dataDir, false)
 	if err != nil {
 		report.Diagnostics = append(report.Diagnostics, Diagnostic{
 			Severity: SeverityError,
@@ -2307,7 +2307,7 @@ func validateNativeBuildability(p *project.Project, report *ValidationReport) {
 		})
 		return
 	}
-	registryDatasets, err := collectGeneratedRegistryDatasets(dataDir)
+	registryDatasets, err := collectGeneratedRegistryDatasets(dataDir, false)
 	if err != nil {
 		report.Diagnostics = append(report.Diagnostics, Diagnostic{
 			Severity: SeverityError,

internal/topdata/topdata_test.go

@@ -7633,7 +7633,7 @@ func TestApplyAutogenConsumersAugmentsPartsFromLocalOverride(t *testing.T) {
 	}
 }
 
-func TestApplyAutogenConsumersAugmentsHeadVisualeffectsFromLocalOverride(t *testing.T) {
+func TestApplyAutogenConsumersAugmentsAccessoryVisualeffectsFromLocalOverride(t *testing.T) {
 	root := testProjectRoot(t)
 	overrideRoot := filepath.Join(root, "autogen-assets")
 	mkdirAll(t, filepath.Join(overrideRoot, "vfxs", "head_accessories", "hat"))
@@ -7717,7 +7717,7 @@ func TestApplyAutogenConsumersAugmentsHeadVisualeffectsFromLocalOverride(t *test
 	}
 }
 
-func TestApplyAutogenConsumersUsesFolderDrivenSlashHeadVisualeffectsNames(t *testing.T) {
+func TestApplyAutogenConsumersUsesFolderDrivenSlashAccessoryVisualeffectsNames(t *testing.T) {
 	root := testProjectRoot(t)
 	overrideRoot := filepath.Join(root, "autogen-assets")
 	mkdirAll(t, filepath.Join(overrideRoot, "vfxs", "head_features", "sinfar", "ears_plt"))
@@ -7735,8 +7735,8 @@ func TestApplyAutogenConsumersUsesFolderDrivenSlashHeadVisualeffectsNames(t *tes
 			Derive:            project.AutogenDeriveConfig{Kind: "model_stem", GroupFrom: "first_path_segment"},
 			Manifest:          project.AutogenManifestConfig{ReleaseTag: "head-vfx-manifest-current", AssetName: "sow-accessory-vfx-manifest.json", CacheName: "sow-accessory-vfx-manifest.json"},
 			LocalOverrideRoot: "autogen-assets",
-			HeadVisualeffects: project.HeadVisualeffectsConfig{
+			AccessoryVisualeffects: project.AccessoryVisualeffectsConfig{
-				Groups: map[string]project.HeadVisualeffectGroupConfig{
+				Groups: map[string]project.AccessoryVisualeffectGroupConfig{
 					"head_features": {
 						ModelColumns: []string{"Imp_HeadCon_Node", "Imp_Root_H_Node"},
 					},
@@ -7790,7 +7790,7 @@ func TestApplyAutogenConsumersUsesFolderDrivenSlashHeadVisualeffectsNames(t *tes
 	}
 }
 
-func TestBuildNativeUsesConfiguredHeadVisualeffectsGroups(t *testing.T) {
+func TestBuildNativeUsesConfiguredAccessoryVisualeffectsGroups(t *testing.T) {
 	root := t.TempDir()
 	mkdirAll(t, filepath.Join(root, "src"))
 	mkdirAll(t, filepath.Join(root, "build"))
@@ -7878,7 +7878,7 @@ autogen:
 	}
 }
 
-func TestBuildGenerated2DAAssetsAppendsCachedModelsFromHeadVisualeffects(t *testing.T) {
+func TestBuildGenerated2DAAssetsAppendsCachedModelsFromAccessoryVisualeffects(t *testing.T) {
 	root := testProjectRoot(t)
 	mkdirAll(t, filepath.Join(root, "assets", "vfxs", "chest_accessories"))
 	mkdirAll(t, filepath.Join(root, "assets", "vfxs", "head_accessories"))
@@ -13139,7 +13139,7 @@ func TestBuildNativeWithReleasedPartsManifestUsesAssetsServerOverride(t *testing
 	}
 }
 
-func TestBuildNativeWithReleasedHeadVisualeffectsManifest(t *testing.T) {
+func TestBuildNativeWithReleasedAccessoryVisualeffectsManifest(t *testing.T) {
 	root := t.TempDir()
 	projRoot := filepath.Join(root, "project")
 	mkdirAll(t, filepath.Join(projRoot, "src"))
@@ -13274,7 +13274,7 @@ func TestBuildNativeWithReleasedHeadVisualeffectsManifest(t *testing.T) {
 	}
 }
 
-func TestBuildNativePrefersRemoteReleasedHeadVisualeffectsManifestOverFreshCache(t *testing.T) {
+func TestBuildNativePrefersRemoteReleasedAccessoryVisualeffectsManifestOverFreshCache(t *testing.T) {
 	root := t.TempDir()
 	projRoot := filepath.Join(root, "project")
 	mkdirAll(t, filepath.Join(projRoot, "src"))
@@ -15021,7 +15021,7 @@ func (t twoDATable) cell(rowID, column string) string {
 
 func runGitTest(t *testing.T, dir string, args ...string) {
 	t.Helper()
-	cmd := exec.Command("git", args...)
+	cmd := exec.Command("git", append([]string{"-c", "commit.gpgsign=false", "-c", "tag.gpgsign=false"}, args...)...)
 	if dir != "" {
 		cmd.Dir = dir
 	}

internal/topdata/wiki_native.go

@@ -748,7 +748,7 @@ func collectWikiRacialtypesDatasets(dataDir string, datasets []nativeDataset) ([
 	if len(out) > 0 {
 		return out, nil
 	}
-	return collectRacialtypesRegistryDatasets(dataDir)
+	return collectRacialtypesRegistryDatasets(dataDir, false)
 }
 
 func collectWikiRacialtypeStatuses(dataDir string) map[string]string {