fix(build): validate project finalizer caches

docs/decisions/0006-project-finalizers-and-branch-assembly.md

@@ -46,6 +46,12 @@ reinterpret an in-flight branch job.
 - A project worker gets a private mutable finalizer workspace.  The immutable
   branch Lean cache remains read-only.  No two project workers share a mutable
   Lake/Web directory or branch result path.
+- The build SDK recognizes writable branch/project finalizer workspaces only
+  through their exact cache paths and schema-2/schema-3 markers.  Those
+  identities bind tooling, branch, optional build configuration, and optional
+  project key.  Documentation checkpoints continue to hash their dependency
+  artifacts; only a branch cache outside the `finalizer-caches` namespace may
+  replace those hashes with immutable namespace metadata.
 - Add one branch-assembly job per branch.  It requires the exact project set
   declared by the ReleaseSpec, revalidates every identity and content digest,
   and rejects missing, extra, duplicate, stale, symlinked, or special-file

sdk/build/README.md

@@ -138,6 +138,21 @@ replacement cache as a unit. The selected project artifacts and analyzer
 support binaries are still hashed from their bytes. Without a valid structural
 opt-in, the builder hashes all dependency `.olean`, `.so`, and `.a` files
 instead.
+
+Writable finalizer caches use separate layouts below
+`finalizer-caches/<tooling-sha256>/`: a branch worker owns either the legacy
+`lake/<branch-namespace>` or configured
+`cfg-<configuration-sha256>/lake/<branch-namespace>` shape, while an isolated
+project worker appends `projects/<safe-project-key>` to the configured shape.
+The builder accepts them only when their exact schema-2/schema-3
+`finalizer-cache.json` binds the branch metadata, tooling digest, seed
+namespace, and, where present, canonical build configuration and original
+project key to the path. Because these workspaces are writable, their markers
+never substitute for artifact content: all dependency `.olean`, `.so`, and
+`.a` files remain hashed. The validated marker is included in the analysis
+identity so checkpoints cannot cross branch/project, tooling, or
+build-configuration boundaries.
+
 The repository adapter `scripts/build/project_docs.sh` uses exactly
 `REASBOOK_LAKE_TARGETS` when a release/deployment supplies it, ahead of any
 ambient `PROJECT_DOC_MODULES` operator override. Automatic Lake library