@orkestrel/scaffold 0.0.55 → 0.0.56

package/dist/src/server/index.d.cts

@@ -4,6 +4,7 @@ import { Dependency } from '@orkestrel/scaffold';
 import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
+import { Group } from '@orkestrel/scaffold';
 import { Guard } from '@orkestrel/contract';
 import { HostFile } from '@orkestrel/scaffold';
 import { ManifestRegionSet } from '@orkestrel/scaffold';
@@ -130,8 +131,11 @@ export declare const DRIVE_PATTERN: RegExp;
  * went missing, names an undeclared path, or leaves a host-owned path absent
  * answers `undefined`. Deferred paths are presence-only and retain the installed
  * floor bytes that their catalog or mirror surface owns; repair never writes
- * those floor bytes. One `Host` can therefore carry live host bytes beside floor
- * bytes without mixing baselines within a surface.
+ * those floor bytes. A canon path is read the same way for a different reason:
+ * the canon is staged for reading rather than for a target, so every canon
+ * destination keeps its floor bytes here, claimed or not, and a fill that carries
+ * no row for one is complete rather than spoiled. One `Host` can therefore carry
+ * live host bytes beside floor bytes without mixing baselines within a surface.
  *
  * The emitted entries keep the release's own order and its storage and
  * executable declarations, and carry digests recomputed over the bytes the fill
@@ -143,8 +147,12 @@ export declare const DRIVE_PATTERN: RegExp;
  * ```ts
  * import { filesToHost } from '@orkestrel/scaffold/server'
  *
- * filesToHost([{ path: 'AGENTS.md', lookup: 'found', hex: '23204167656e74730a' }], floor)
- * // { manifest: { entries: [ … ], roots: [ … ], digest: '…' }, bytes: { 'AGENTS.md': '…' } }
+ * // A floor declaring the host-owned `scripts/codex.sh` path and the canon
+ * // `AGENTS.md` destination. The script's live bytes are taken; the canon
+ * // destination keeps the floor's.
+ * filesToHost([{ path: 'scripts/codex.sh', lookup: 'found', hex: '23212f62696e2f73680a' }], floor)
+ * // { manifest: { entries: [ … ], roots: [ … ], digest: '…' },
+ * //   bytes: { 'scripts/codex.sh': '23212f62696e2f73680a', 'AGENTS.md': floor.bytes['AGENTS.md'] } }
  * ```
  */
 export declare function filesToHost(files: readonly HostFile[], floor: Host): Host | undefined;
@@ -624,6 +632,39 @@ export declare function isVacant(target: string): boolean;
  */
 export declare const isWorktree: Guard<Worktree>;
 
+/**
+ * Lists the canon paths a target holds, filtered to a plan's groups.
+ *
+ * @param target - The target directory to inspect.
+ * @param groups - The artifact groups the plan covers; a held path whose group
+ * is outside them is not listed.
+ * @returns Every held canon path as a `/`-separated target-relative path, a
+ * directory member expanded to the files beneath it, and `[]` when the target
+ * holds none or cannot be resolved.
+ * @throws `ScaffoldError('TARGET', …)` when a held canon directory cannot be
+ * inventoried; {@link listFiles} states each refusal.
+ *
+ * @remarks
+ * A release stages the canon for reading rather than for a target, so a copy
+ * sitting in one is an artifact of a release that vendored it, and reading it
+ * here is what lets the deletion verb take it.
+ *
+ * A directory member is read by file, which is what pairs the paths a plan
+ * claims inside the canon with their artifacts and leaves only the rest foreign,
+ * with no case for a planned file. The plan's own selection gates the reading,
+ * the same rule that decides a vendored path's group, so a scoped audit reports
+ * nothing outside its groups. A member that cannot resolve inside the target is
+ * not held by it.
+ *
+ * @example
+ * ```ts
+ * import { listCanonPaths } from '@orkestrel/scaffold/server'
+ *
+ * listCanonPaths('vacant', ['orchestration']) // []
+ * ```
+ */
+export declare function listCanonPaths(target: string, groups: readonly Group[]): readonly string[];
+
 /**
  * List a directory's descendant directories as sorted root-relative paths.
  *
@@ -988,7 +1029,8 @@ export declare class Materializer implements MaterializerInterface {
       *
       * @param plan - The compiled plan to compare.
       * @param target - The directory to inspect.
-      * @returns One finding per hydrated planned path, plus foreign files beneath owned host roots.
+      * @returns One finding per hydrated planned path, plus the foreign files
+      * beneath owned host roots and inside the instruction canon.
       * @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
           * exact shape, `TARGET` when the host or target cannot be read within its
           * bounds, and `DESTROYED` after teardown.
@@ -996,8 +1038,16 @@ export declare class Materializer implements MaterializerInterface {
           * @remarks
           * Host directories expand before the target is read, so this method and
           * {@link repair} compare the same paths with the same ownership. Foreign
-          * candidates are files beneath those expanded roots only; a root file never
-          * becomes a deletion candidate merely because its group is selected.
+          * candidates are files beneath those expanded roots and files the target holds
+          * at a `CANON_PATHS` member, each in a group the plan selects; a file outside
+          * both populations never becomes a deletion candidate merely because its group
+          * is selected.
+          *
+          * The canon is staged for reading rather than for a target, so a copy of one of
+          * its paths sitting in a target is a superseded artifact and reports foreign. A
+          * path the plan claims inside the canon — the root instruction pointers and the
+          * catalog agent file — pairs with its artifact and is compared like any other
+          * planned path.
           */
       audit(plan: Plan, target: string): Audit;
       /**
@@ -1124,9 +1174,20 @@ export declare class Materializer implements MaterializerInterface {
                 * recovery mechanism, so a path it cannot restore is not one this verb takes.
                 * A tree carrying uncommitted work is refused whole for the same reason.
                 *
+                * One candidate list carries both foreign populations {@link audit} reports, so
+                * a superseded instruction copy the target holds inside the canon is deleted in
+                * the same transaction as a stray beneath an owned root. Membership decides it,
+                * never byte identity: a copy a release behind no longer matches the bytes the
+                * canon now stages, and matching bytes is exactly how such a copy would be
+                * spared. An untracked leftover is left where it sits and stays a finding, which
+                * is the seam a maintainer keeps a git-ignored file in.
+                *
                 * The whole call refuses when the preview disagrees with the re-derivation on
                 * any foreign finding, including one the deletion itself would skip, because a
                 * preview stale anywhere is stale evidence.
+                *
+                * Every directory the deletions emptied is taken after the commit, so a swept
+                * target does not keep the shape of the set it no longer holds.
                 */
             remove(plan: Plan, audit: Audit, worktree: Worktree, target: string): MaterializeResult;
             /**
@@ -1384,6 +1445,38 @@ export declare class Materializer implements MaterializerInterface {
             */
            export declare function pathToStorage(path: string): string;
 
+           /**
+            * Removes every directory one set of deletions emptied.
+            *
+            * @param target - The directory the deleted paths are relative to.
+            * @param removed - The `/`-separated target-relative paths the deletion took.
+            * @returns Every removed directory as a target-relative path, in the order they
+            * were taken, and `[]` when the target is absent or nothing it holds was
+            * emptied.
+            *
+            * @remarks
+            * A deletion that takes the last file out of a directory leaves the directory
+            * standing, and git records no directory, so a swept target keeps the shape of a
+            * set it no longer holds while every reading of it reports clean. Only an
+            * ancestor of a path this deletion took is a candidate, so nothing the deletion
+            * did not reach is inspected, and the target itself is never a candidate.
+            *
+            * Candidates are taken deepest first, which is what lets a whole chain go: the
+            * directory holding nothing but the emptied directory is empty in turn by the
+            * time it is read. Each one is resolved through the containment law and left
+            * standing when it escapes the target, is not a physical directory, still holds
+            * an entry, or refuses removal, and a directory left standing is absent from the
+            * answer.
+            *
+            * @example
+            * ```ts
+            * import { pruneEmptiedDirectories } from '@orkestrel/scaffold/server'
+            *
+            * pruneEmptiedDirectories('vacant', ['notes/entry.md']) // []
+            * ```
+            */
+           export declare function pruneEmptiedDirectories(target: string, removed: readonly string[]): readonly string[];
+
            /**
             * Capture one directory's physical identity.
             *
@@ -1779,9 +1872,15 @@ export declare class Materializer implements MaterializerInterface {
             * once. A directory is the same case — declaring an absent directory as an empty
             * root would create an empty directory in every generated workspace.
             *
-            * The vendoring deny-list applies to what the walk discovers beneath a vendored
+            * The walk covers `HOST_PATHS` and `CANON_PATHS` together, because a release
+            * ships both: a target receives the first set, and reads the second one out of
+            * the installed package. Everything downstream — the missing-path refusal, the
+            * storage collision guard, the sort, the digests, and the root inventory — reads
+            * the union, so a canon path is staged under exactly the law a vendored one is.
+            *
+            * The vendoring deny-list applies to what the walk discovers beneath a staged
             * directory, where a maintainer's local credential can legitimately sit, and
-            * such a path is skipped. A path `HOST_PATHS` names itself is curated data
+            * such a path is skipped. A path either list names itself is curated data
             * rather than discovery, so it is staged or the stage is refused.
             *
             * @example

package/dist/src/server/index.d.ts

@@ -4,6 +4,7 @@ import { Dependency } from '@orkestrel/scaffold';
 import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
+import { Group } from '@orkestrel/scaffold';
 import { Guard } from '@orkestrel/contract';
 import { HostFile } from '@orkestrel/scaffold';
 import { ManifestRegionSet } from '@orkestrel/scaffold';
@@ -130,8 +131,11 @@ export declare const DRIVE_PATTERN: RegExp;
  * went missing, names an undeclared path, or leaves a host-owned path absent
  * answers `undefined`. Deferred paths are presence-only and retain the installed
  * floor bytes that their catalog or mirror surface owns; repair never writes
- * those floor bytes. One `Host` can therefore carry live host bytes beside floor
- * bytes without mixing baselines within a surface.
+ * those floor bytes. A canon path is read the same way for a different reason:
+ * the canon is staged for reading rather than for a target, so every canon
+ * destination keeps its floor bytes here, claimed or not, and a fill that carries
+ * no row for one is complete rather than spoiled. One `Host` can therefore carry
+ * live host bytes beside floor bytes without mixing baselines within a surface.
  *
  * The emitted entries keep the release's own order and its storage and
  * executable declarations, and carry digests recomputed over the bytes the fill
@@ -143,8 +147,12 @@ export declare const DRIVE_PATTERN: RegExp;
  * ```ts
  * import { filesToHost } from '@orkestrel/scaffold/server'
  *
- * filesToHost([{ path: 'AGENTS.md', lookup: 'found', hex: '23204167656e74730a' }], floor)
- * // { manifest: { entries: [ … ], roots: [ … ], digest: '…' }, bytes: { 'AGENTS.md': '…' } }
+ * // A floor declaring the host-owned `scripts/codex.sh` path and the canon
+ * // `AGENTS.md` destination. The script's live bytes are taken; the canon
+ * // destination keeps the floor's.
+ * filesToHost([{ path: 'scripts/codex.sh', lookup: 'found', hex: '23212f62696e2f73680a' }], floor)
+ * // { manifest: { entries: [ … ], roots: [ … ], digest: '…' },
+ * //   bytes: { 'scripts/codex.sh': '23212f62696e2f73680a', 'AGENTS.md': floor.bytes['AGENTS.md'] } }
  * ```
  */
 export declare function filesToHost(files: readonly HostFile[], floor: Host): Host | undefined;
@@ -624,6 +632,39 @@ export declare function isVacant(target: string): boolean;
  */
 export declare const isWorktree: Guard<Worktree>;
 
+/**
+ * Lists the canon paths a target holds, filtered to a plan's groups.
+ *
+ * @param target - The target directory to inspect.
+ * @param groups - The artifact groups the plan covers; a held path whose group
+ * is outside them is not listed.
+ * @returns Every held canon path as a `/`-separated target-relative path, a
+ * directory member expanded to the files beneath it, and `[]` when the target
+ * holds none or cannot be resolved.
+ * @throws `ScaffoldError('TARGET', …)` when a held canon directory cannot be
+ * inventoried; {@link listFiles} states each refusal.
+ *
+ * @remarks
+ * A release stages the canon for reading rather than for a target, so a copy
+ * sitting in one is an artifact of a release that vendored it, and reading it
+ * here is what lets the deletion verb take it.
+ *
+ * A directory member is read by file, which is what pairs the paths a plan
+ * claims inside the canon with their artifacts and leaves only the rest foreign,
+ * with no case for a planned file. The plan's own selection gates the reading,
+ * the same rule that decides a vendored path's group, so a scoped audit reports
+ * nothing outside its groups. A member that cannot resolve inside the target is
+ * not held by it.
+ *
+ * @example
+ * ```ts
+ * import { listCanonPaths } from '@orkestrel/scaffold/server'
+ *
+ * listCanonPaths('vacant', ['orchestration']) // []
+ * ```
+ */
+export declare function listCanonPaths(target: string, groups: readonly Group[]): readonly string[];
+
 /**
  * List a directory's descendant directories as sorted root-relative paths.
  *
@@ -988,7 +1029,8 @@ export declare class Materializer implements MaterializerInterface {
       *
       * @param plan - The compiled plan to compare.
       * @param target - The directory to inspect.
-      * @returns One finding per hydrated planned path, plus foreign files beneath owned host roots.
+      * @returns One finding per hydrated planned path, plus the foreign files
+      * beneath owned host roots and inside the instruction canon.
       * @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
           * exact shape, `TARGET` when the host or target cannot be read within its
           * bounds, and `DESTROYED` after teardown.
@@ -996,8 +1038,16 @@ export declare class Materializer implements MaterializerInterface {
           * @remarks
           * Host directories expand before the target is read, so this method and
           * {@link repair} compare the same paths with the same ownership. Foreign
-          * candidates are files beneath those expanded roots only; a root file never
-          * becomes a deletion candidate merely because its group is selected.
+          * candidates are files beneath those expanded roots and files the target holds
+          * at a `CANON_PATHS` member, each in a group the plan selects; a file outside
+          * both populations never becomes a deletion candidate merely because its group
+          * is selected.
+          *
+          * The canon is staged for reading rather than for a target, so a copy of one of
+          * its paths sitting in a target is a superseded artifact and reports foreign. A
+          * path the plan claims inside the canon — the root instruction pointers and the
+          * catalog agent file — pairs with its artifact and is compared like any other
+          * planned path.
           */
       audit(plan: Plan, target: string): Audit;
       /**
@@ -1124,9 +1174,20 @@ export declare class Materializer implements MaterializerInterface {
                 * recovery mechanism, so a path it cannot restore is not one this verb takes.
                 * A tree carrying uncommitted work is refused whole for the same reason.
                 *
+                * One candidate list carries both foreign populations {@link audit} reports, so
+                * a superseded instruction copy the target holds inside the canon is deleted in
+                * the same transaction as a stray beneath an owned root. Membership decides it,
+                * never byte identity: a copy a release behind no longer matches the bytes the
+                * canon now stages, and matching bytes is exactly how such a copy would be
+                * spared. An untracked leftover is left where it sits and stays a finding, which
+                * is the seam a maintainer keeps a git-ignored file in.
+                *
                 * The whole call refuses when the preview disagrees with the re-derivation on
                 * any foreign finding, including one the deletion itself would skip, because a
                 * preview stale anywhere is stale evidence.
+                *
+                * Every directory the deletions emptied is taken after the commit, so a swept
+                * target does not keep the shape of the set it no longer holds.
                 */
             remove(plan: Plan, audit: Audit, worktree: Worktree, target: string): MaterializeResult;
             /**
@@ -1384,6 +1445,38 @@ export declare class Materializer implements MaterializerInterface {
             */
            export declare function pathToStorage(path: string): string;
 
+           /**
+            * Removes every directory one set of deletions emptied.
+            *
+            * @param target - The directory the deleted paths are relative to.
+            * @param removed - The `/`-separated target-relative paths the deletion took.
+            * @returns Every removed directory as a target-relative path, in the order they
+            * were taken, and `[]` when the target is absent or nothing it holds was
+            * emptied.
+            *
+            * @remarks
+            * A deletion that takes the last file out of a directory leaves the directory
+            * standing, and git records no directory, so a swept target keeps the shape of a
+            * set it no longer holds while every reading of it reports clean. Only an
+            * ancestor of a path this deletion took is a candidate, so nothing the deletion
+            * did not reach is inspected, and the target itself is never a candidate.
+            *
+            * Candidates are taken deepest first, which is what lets a whole chain go: the
+            * directory holding nothing but the emptied directory is empty in turn by the
+            * time it is read. Each one is resolved through the containment law and left
+            * standing when it escapes the target, is not a physical directory, still holds
+            * an entry, or refuses removal, and a directory left standing is absent from the
+            * answer.
+            *
+            * @example
+            * ```ts
+            * import { pruneEmptiedDirectories } from '@orkestrel/scaffold/server'
+            *
+            * pruneEmptiedDirectories('vacant', ['notes/entry.md']) // []
+            * ```
+            */
+           export declare function pruneEmptiedDirectories(target: string, removed: readonly string[]): readonly string[];
+
            /**
             * Capture one directory's physical identity.
             *
@@ -1779,9 +1872,15 @@ export declare class Materializer implements MaterializerInterface {
             * once. A directory is the same case — declaring an absent directory as an empty
             * root would create an empty directory in every generated workspace.
             *
-            * The vendoring deny-list applies to what the walk discovers beneath a vendored
+            * The walk covers `HOST_PATHS` and `CANON_PATHS` together, because a release
+            * ships both: a target receives the first set, and reads the second one out of
+            * the installed package. Everything downstream — the missing-path refusal, the
+            * storage collision guard, the sort, the digests, and the root inventory — reads
+            * the union, so a canon path is staged under exactly the law a vendored one is.
+            *
+            * The vendoring deny-list applies to what the walk discovers beneath a staged
             * directory, where a maintainer's local credential can legitimately sit, and
-            * such a path is skipped. A path `HOST_PATHS` names itself is curated data
+            * such a path is skipped. A path either list names itself is curated data
             * rather than discovery, so it is staged or the stage is refused.
             *
             * @example

package/dist/src/server/index.js

@@ -1,5 +1,5 @@
-import { andOf, arrayOf, attempt, boundsOf, holds, isArray, isBoolean, isError, isFunction, isInteger, isRecord, isString, parseJSON, parseJSONAs, parseStringField, recordOf, stringOf, unionOf } from "@orkestrel/contract";
-import { CATALOG_AGENT_PATH, CONTROL_CHARACTER_PATTERN, EXECUTABLE_PATHS, HOST_INVENTORY_PATH, HOST_PATHS, MAX_ARTIFACT_BYTES, MAX_COLLECTION_ITEMS, MAX_DEPENDENCY_NAME_LENGTH, MAX_MANIFEST_BYTES, MAX_PATH_LENGTH, MAX_RANGE_LENGTH, MAX_REGISTRY_BYTES, MAX_TOTAL_ARTIFACT_BYTES, MAX_TOTAL_REGISTRY_BYTES, ScaffoldError, WORKSPACE_OWNED_PATHS, bytesToHex, catalogToLayers, cloneValue, compareVersions, computeBytes, contentToHex, extractRangeMajor, extractVersion, inferGroup, isAudit, isCatalogEntry, isCollection, isDeferredPath, isDependency, isDependencyName, isHex, isManifestScript, isMirror, isPath, isPlan, isSnapshot, matchesDriftReachability, matchesRange, nameToGuide, planToFindings, replaceManifestRanges, replaceManifestScripts } from "../core/index.js";
+import { andOf, arrayOf, attempt, boundsOf, compareValues, holds, isArray, isBoolean, isError, isFunction, isInteger, isRecord, isString, parseJSON, parseJSONAs, parseStringField, recordOf, stringOf, unionOf } from "@orkestrel/contract";
+import { CANON_PATHS, CATALOG_AGENT_PATH, CONTROL_CHARACTER_PATTERN, EXECUTABLE_PATHS, HOST_INVENTORY_PATH, HOST_PATHS, MAX_ARTIFACT_BYTES, MAX_COLLECTION_ITEMS, MAX_DEPENDENCY_NAME_LENGTH, MAX_MANIFEST_BYTES, MAX_PATH_LENGTH, MAX_RANGE_LENGTH, MAX_REGISTRY_BYTES, MAX_TOTAL_ARTIFACT_BYTES, MAX_TOTAL_REGISTRY_BYTES, ScaffoldError, WORKSPACE_OWNED_PATHS, bytesToHex, catalogToLayers, cloneValue, compareVersions, computeBytes, contentToHex, extractRangeMajor, extractVersion, inferGroup, isAudit, isCanonPath, isCatalogEntry, isCollection, isDeferredPath, isDependency, isDependencyName, isHex, isManifestScript, isMirror, isPath, isPlan, isSnapshot, matchesDriftReachability, matchesRange, nameToGuide, planToFindings, replaceManifestRanges, replaceManifestScripts } from "../core/index.js";
 import { createHash, randomUUID } from "node:crypto";
 import { chmodSync, closeSync, constants, copyFileSync, fstatSync, linkSync, lstatSync, mkdirSync, mkdtempSync, openSync, opendirSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -1210,6 +1210,97 @@ function listDirectories(root) {
 	return directories.sort();
 }
 /**
+* Lists the canon paths a target holds, filtered to a plan's groups.
+*
+* @param target - The target directory to inspect.
+* @param groups - The artifact groups the plan covers; a held path whose group
+* is outside them is not listed.
+* @returns Every held canon path as a `/`-separated target-relative path, a
+* directory member expanded to the files beneath it, and `[]` when the target
+* holds none or cannot be resolved.
+* @throws `ScaffoldError('TARGET', …)` when a held canon directory cannot be
+* inventoried; {@link listFiles} states each refusal.
+*
+* @remarks
+* A release stages the canon for reading rather than for a target, so a copy
+* sitting in one is an artifact of a release that vendored it, and reading it
+* here is what lets the deletion verb take it.
+*
+* A directory member is read by file, which is what pairs the paths a plan
+* claims inside the canon with their artifacts and leaves only the rest foreign,
+* with no case for a planned file. The plan's own selection gates the reading,
+* the same rule that decides a vendored path's group, so a scoped audit reports
+* nothing outside its groups. A member that cannot resolve inside the target is
+* not held by it.
+*
+* @example
+* ```ts
+* import { listCanonPaths } from '@orkestrel/scaffold/server'
+*
+* listCanonPaths('vacant', ['orchestration']) // []
+* ```
+*/
+function listCanonPaths(target, groups) {
+	const held = [];
+	for (const member of CANON_PATHS) {
+		const full = resolveContainedPath(target, member);
+		if (full === void 0) continue;
+		if (isPhysicalFile(full)) held.push(member);
+		else if (isPhysicalDirectory(full)) for (const name of listFiles(full)) held.push(`${member}/${name}`);
+	}
+	return held.filter((path) => groups.includes(inferGroup(path)));
+}
+/**
+* Removes every directory one set of deletions emptied.
+*
+* @param target - The directory the deleted paths are relative to.
+* @param removed - The `/`-separated target-relative paths the deletion took.
+* @returns Every removed directory as a target-relative path, in the order they
+* were taken, and `[]` when the target is absent or nothing it holds was
+* emptied.
+*
+* @remarks
+* A deletion that takes the last file out of a directory leaves the directory
+* standing, and git records no directory, so a swept target keeps the shape of a
+* set it no longer holds while every reading of it reports clean. Only an
+* ancestor of a path this deletion took is a candidate, so nothing the deletion
+* did not reach is inspected, and the target itself is never a candidate.
+*
+* Candidates are taken deepest first, which is what lets a whole chain go: the
+* directory holding nothing but the emptied directory is empty in turn by the
+* time it is read. Each one is resolved through the containment law and left
+* standing when it escapes the target, is not a physical directory, still holds
+* an entry, or refuses removal, and a directory left standing is absent from the
+* answer.
+*
+* @example
+* ```ts
+* import { pruneEmptiedDirectories } from '@orkestrel/scaffold/server'
+*
+* pruneEmptiedDirectories('vacant', ['notes/entry.md']) // []
+* ```
+*/
+function pruneEmptiedDirectories(target, removed) {
+	const candidates = /* @__PURE__ */ new Set();
+	for (const path of removed) {
+		let parent = dirname(path);
+		while (parent !== "." && parent !== dirname(parent) && !candidates.has(parent)) {
+			candidates.add(parent);
+			parent = dirname(parent);
+		}
+	}
+	const ordered = [...candidates].sort((left, right) => compareValues(right.split("/").length, left.split("/").length) || compareValues(left, right));
+	const pruned = [];
+	for (const candidate of ordered) {
+		const directory = resolveContainedPath(target, candidate);
+		if (directory === void 0 || !isPhysicalDirectory(directory)) continue;
+		const entries = attempt(() => readdirSync(directory));
+		if (!entries.success || entries.value.length > 0) continue;
+		if (attempt(() => rmdirSync(directory)).success) pruned.push(candidate);
+	}
+	return pruned;
+}
+/**
 * Read one contained file as its exact bytes in lowercase hexadecimal.
 *
 * @param root - The containing host directory.
@@ -1518,8 +1609,11 @@ function readManifestEntry(destination, source) {
 * went missing, names an undeclared path, or leaves a host-owned path absent
 * answers `undefined`. Deferred paths are presence-only and retain the installed
 * floor bytes that their catalog or mirror surface owns; repair never writes
-* those floor bytes. One `Host` can therefore carry live host bytes beside floor
-* bytes without mixing baselines within a surface.
+* those floor bytes. A canon path is read the same way for a different reason:
+* the canon is staged for reading rather than for a target, so every canon
+* destination keeps its floor bytes here, claimed or not, and a fill that carries
+* no row for one is complete rather than spoiled. One `Host` can therefore carry
+* live host bytes beside floor bytes without mixing baselines within a surface.
 *
 * The emitted entries keep the release's own order and its storage and
 * executable declarations, and carry digests recomputed over the bytes the fill
@@ -1531,8 +1625,12 @@ function readManifestEntry(destination, source) {
 * ```ts
 * import { filesToHost } from '@orkestrel/scaffold/server'
 *
-* filesToHost([{ path: 'AGENTS.md', lookup: 'found', hex: '23204167656e74730a' }], floor)
-* // { manifest: { entries: [ … ], roots: [ … ], digest: '…' }, bytes: { 'AGENTS.md': '…' } }
+* // A floor declaring the host-owned `scripts/codex.sh` path and the canon
+* // `AGENTS.md` destination. The script's live bytes are taken; the canon
+* // destination keeps the floor's.
+* filesToHost([{ path: 'scripts/codex.sh', lookup: 'found', hex: '23212f62696e2f73680a' }], floor)
+* // { manifest: { entries: [ … ], roots: [ … ], digest: '…' },
+* //   bytes: { 'scripts/codex.sh': '23212f62696e2f73680a', 'AGENTS.md': floor.bytes['AGENTS.md'] } }
 * ```
 */
 function filesToHost(files, floor) {
@@ -1540,12 +1638,12 @@ function filesToHost(files, floor) {
 	const held = /* @__PURE__ */ new Map();
 	for (const file of files) {
 		if (file.lookup !== "found" || !declared.has(file.path)) return void 0;
-		if (!isDeferredPath(file.path)) held.set(file.path, file.hex);
+		if (!isDeferredPath(file.path) && !isCanonPath(file.path)) held.set(file.path, file.hex);
 	}
 	const entries = [];
 	const bytes = {};
 	for (const entry of floor.manifest.entries) {
-		const hex = isDeferredPath(entry.destination) ? floor.bytes[entry.destination] : held.get(entry.destination);
+		const hex = isDeferredPath(entry.destination) || isCanonPath(entry.destination) ? floor.bytes[entry.destination] : held.get(entry.destination);
 		if (hex === void 0) return void 0;
 		entries.push({
 			storage: entry.storage,
@@ -1676,9 +1774,15 @@ function stageBytes(host, root, destinations) {
 * once. A directory is the same case — declaring an absent directory as an empty
 * root would create an empty directory in every generated workspace.
 *
-* The vendoring deny-list applies to what the walk discovers beneath a vendored
+* The walk covers `HOST_PATHS` and `CANON_PATHS` together, because a release
+* ships both: a target receives the first set, and reads the second one out of
+* the installed package. Everything downstream — the missing-path refusal, the
+* storage collision guard, the sort, the digests, and the root inventory — reads
+* the union, so a canon path is staged under exactly the law a vendored one is.
+*
+* The vendoring deny-list applies to what the walk discovers beneath a staged
 * directory, where a maintainer's local credential can legitimately sit, and
-* such a path is skipped. A path `HOST_PATHS` names itself is curated data
+* such a path is skipped. A path either list names itself is curated data
 * rather than discovery, so it is staged or the stage is refused.
 *
 * @example
@@ -1697,7 +1801,7 @@ function stageHost(checkout, host) {
 	const vendored = [];
 	const roots = [];
 	const missing = [];
-	for (const path of HOST_PATHS) {
+	for (const path of [...HOST_PATHS, ...CANON_PATHS]) {
 		const full = resolveContainedPath(source, path);
 		if (full === void 0) throw new ScaffoldError("INVALID", `Vendored path leaves its checkout at ${path}`, {
 			checkout: source,
@@ -2651,7 +2755,8 @@ var Materializer = class Materializer {
 	*
 	* @param plan - The compiled plan to compare.
 	* @param target - The directory to inspect.
-	* @returns One finding per hydrated planned path, plus foreign files beneath owned host roots.
+	* @returns One finding per hydrated planned path, plus the foreign files
+	* beneath owned host roots and inside the instruction canon.
 	* @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
 	* exact shape, `TARGET` when the host or target cannot be read within its
 	* bounds, and `DESTROYED` after teardown.
@@ -2659,8 +2764,16 @@ var Materializer = class Materializer {
 	* @remarks
 	* Host directories expand before the target is read, so this method and
 	* {@link repair} compare the same paths with the same ownership. Foreign
-	* candidates are files beneath those expanded roots only; a root file never
-	* becomes a deletion candidate merely because its group is selected.
+	* candidates are files beneath those expanded roots and files the target holds
+	* at a `CANON_PATHS` member, each in a group the plan selects; a file outside
+	* both populations never becomes a deletion candidate merely because its group
+	* is selected.
+	*
+	* The canon is staged for reading rather than for a target, so a copy of one of
+	* its paths sitting in a target is a superseded artifact and reports foreign. A
+	* path the plan claims inside the canon — the root instruction pointers and the
+	* catalog agent file — pairs with its artifact and is compared like any other
+	* planned path.
 	*/
 	audit(plan, target) {
 		this.#assertAlive();
@@ -2859,9 +2972,20 @@ var Materializer = class Materializer {
 	* recovery mechanism, so a path it cannot restore is not one this verb takes.
 	* A tree carrying uncommitted work is refused whole for the same reason.
 	*
+	* One candidate list carries both foreign populations {@link audit} reports, so
+	* a superseded instruction copy the target holds inside the canon is deleted in
+	* the same transaction as a stray beneath an owned root. Membership decides it,
+	* never byte identity: a copy a release behind no longer matches the bytes the
+	* canon now stages, and matching bytes is exactly how such a copy would be
+	* spared. An untracked leftover is left where it sits and stays a finding, which
+	* is the seam a maintainer keeps a git-ignored file in.
+	*
 	* The whole call refuses when the preview disagrees with the re-derivation on
 	* any foreign finding, including one the deletion itself would skip, because a
 	* preview stale anywhere is stale evidence.
+	*
+	* Every directory the deletions emptied is taken after the commit, so a swept
+	* target does not keep the shape of the set it no longer holds.
 	*/
 	remove(plan, audit, worktree, target) {
 		this.#assertAlive();
@@ -2979,6 +3103,7 @@ var Materializer = class Materializer {
 			});
 			for (const name of listFiles(directory)) paths.add(`${root}/${name}`);
 		}
+		for (const path of listCanonPaths(target, plan.groups)) paths.add(path);
 		return {
 			findings: planToFindings(hydrated, readSnapshot(target, [...paths])),
 			questions: []
@@ -3284,6 +3409,7 @@ var Materializer = class Materializer {
 		});
 		const removed = this.#close(transaction, staged, target);
 		for (const path of removed) this.#emitter.emit("remove", path);
+		pruneEmptiedDirectories(target, removed);
 		return this.#finish({
 			target,
 			written: [],
@@ -4136,6 +4262,6 @@ var Upstream = class Upstream {
 	}
 };
 //#endregion
-export { BRANCH_PATTERN, DIGEST_PATTERN, DRIVE_PATTERN, INVALID_SEGMENT_CHARACTER_PATTERN, MANIFEST_NAME, MAX_BRANCH_LENGTH, MAX_ENDPOINT_LENGTH, MAX_INVENTORY_PATHS, MAX_PATH_DEPTH, MAX_PATH_SEGMENT_BYTES, MAX_UPSTREAM_CONCURRENCY, MAX_UPSTREAM_RETRIES, MAX_UPSTREAM_TIMEOUT, Materializer, RESERVED_SEGMENT_PATTERN, Upstream, WriteTransaction, computeDigest, computeFileDigest, computeManifestDigest, filesToHost, hexToDigest, isBranch, isCatalogEntries, isDependencies, isDependencyNames, isDigest, isEndpoint, isExactCaseFile, isFilesystemPath, isHost, isHostManifest, isInventory, isManifestEntry, isManifestRegionSet, isMaterializerHooks, isMaterializerOptions, isMirrors, isPaths, isPhysicalDirectory, isPhysicalFile, isTimeout, isUpstreamHooks, isUpstreamOptions, isVacant, isWorktree, listDirectories, listFiles, matchesAnchor, matchesExecutablePath, matchesExpectation, matchesGitPath, matchesMissingPath, matchesPrecondition, matchesProtectedPath, matchesSensitivePath, pathToStorage, readAnchor, readExpectation, readFileHex, readFileText, readHostFloor, readHostManifest, readManifestEntry, readSnapshot, resolveContainedPath, resolveRealPath, stageBytes, stageHost, stageInventory };
+export { BRANCH_PATTERN, DIGEST_PATTERN, DRIVE_PATTERN, INVALID_SEGMENT_CHARACTER_PATTERN, MANIFEST_NAME, MAX_BRANCH_LENGTH, MAX_ENDPOINT_LENGTH, MAX_INVENTORY_PATHS, MAX_PATH_DEPTH, MAX_PATH_SEGMENT_BYTES, MAX_UPSTREAM_CONCURRENCY, MAX_UPSTREAM_RETRIES, MAX_UPSTREAM_TIMEOUT, Materializer, RESERVED_SEGMENT_PATTERN, Upstream, WriteTransaction, computeDigest, computeFileDigest, computeManifestDigest, filesToHost, hexToDigest, isBranch, isCatalogEntries, isDependencies, isDependencyNames, isDigest, isEndpoint, isExactCaseFile, isFilesystemPath, isHost, isHostManifest, isInventory, isManifestEntry, isManifestRegionSet, isMaterializerHooks, isMaterializerOptions, isMirrors, isPaths, isPhysicalDirectory, isPhysicalFile, isTimeout, isUpstreamHooks, isUpstreamOptions, isVacant, isWorktree, listCanonPaths, listDirectories, listFiles, matchesAnchor, matchesExecutablePath, matchesExpectation, matchesGitPath, matchesMissingPath, matchesPrecondition, matchesProtectedPath, matchesSensitivePath, pathToStorage, pruneEmptiedDirectories, readAnchor, readExpectation, readFileHex, readFileText, readHostFloor, readHostManifest, readManifestEntry, readSnapshot, resolveContainedPath, resolveRealPath, stageBytes, stageHost, stageInventory };
 
 //# sourceMappingURL=index.js.map