@orkestrel/scaffold 0.0.44 → 0.0.45

package/dist/src/server/index.cjs

@@ -39,7 +39,7 @@ var RESERVED_SEGMENT_PATTERN = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9]|conin\$|co
 *
 * @remarks
 * Fixed length, unlike the core byte encoding, because a digest is one value of
-* one algorithm rather than a variable run of bytes. Lowercase only, so two
+* one algorithm rather than a variable run of bytes. Lowercase only, so separate
 * spellings of one digest can never compare unequal.
 */
 var DIGEST_PATTERN = /^[0-9a-f]{64}$/;
@@ -131,7 +131,7 @@ var MANIFEST_NAME = "manifest.json";
 * the byte ceiling. The character ceiling is read first so an oversized string is
 * refused before it is split.
 *
-* The two spellings of an empty segment are answered differently. A trailing
+* The spellings of an empty segment are answered differently. A trailing
 * separator terminates a directory rather than opening a segment, and every
 * supported filesystem and every Node path API reads `project/` and `project` as
 * one location, so it is admitted. A doubled separator is a genuine empty
@@ -199,7 +199,7 @@ var isDigest = (0, _orkestrel_contract.stringOf)({ pattern: DIGEST_PATTERN });
 * composed, and for the same reason: the item count is settled before anything
 * walks the items, and a hostile `length` accessor answers `false` rather than
 * escaping as a throw. It exists beside that guard rather than reusing it
-* because the two bound different things — one bounds what a caller may hand a
+* because they bound different things — one bounds what a caller may hand a
 * public method, this one bounds what a checkout may contain.
 *
 * @example
@@ -367,8 +367,8 @@ var isMaterializerOptions = (0, _orkestrel_contract.recordOf)({
 * Narrow a value to the upstream reader's initial listener record.
 *
 * @remarks
-* Closed to the reader's own four events for the same reason the materializer's
-* record is closed to its five.
+* Closed to the reader's own events for the same reason the materializer's
+* record is closed to its own.
 */
 var isUpstreamHooks = (0, _orkestrel_contract.recordOf)({
 	release: _orkestrel_contract.isFunction,
@@ -384,7 +384,7 @@ var isUpstreamHooks = (0, _orkestrel_contract.recordOf)({
 * the wrong entity is refused rather than ignored. Every numeric leaf is a whole
 * number inside a ceiling: an unbounded concurrency, retry count, response
 * limit, or call budget is a way to exhaust the caller, so the ceiling is stated
-* here rather than left to the reader. The two byte ceilings are the core
+* here rather than left to the reader. The byte ceilings are the core
 * artifact and total-artifact limits, because a fetched guide is an artifact and
 * a whole call retains no more than a whole plan.
 *
@@ -424,7 +424,7 @@ var isUpstreamOptions = (0, _orkestrel_contract.recordOf)({
 * @remarks
 * The one place absence is told apart from failure. Every read here answers
 * `undefined` or an empty result for a path that is not there and reports a path
-* that is there but unreadable, so the two must never be read from the same
+* that is there but unreadable, so they must never be read from the same
 * caught value by eye. Total for any caught value, including a hostile one.
 *
 * @example
@@ -445,7 +445,7 @@ function matchesMissingPath(error) {
 * @returns `true` for `.git` and for anything beneath it.
 *
 * @remarks
-* The one home of the `.git` membership rule, read from two directions. A target
+* The one home of the `.git` membership rule, read in either direction. A target
 * holding nothing but this directory is still vacant, because a checkout of an
 * empty repository is where a fresh workspace legitimately starts. A path
 * beneath it is never removed and never vendored, because deleting a target's
@@ -472,11 +472,13 @@ function matchesGitPath(path) {
 * @remarks
 * The deletion deny-list, stated as a rule over paths rather than as a list of
 * directories. It is the inversion the contract asks for: the candidate set
-* comes from an audit's foreign findings narrowed by what git tracks, and this
-* is what that set is then measured against. Repository metadata is protected
-* because losing history is not a repair, and a target's own `src` and `app`
-* trees are protected because a workspace's source is the one thing scaffold
-* never plans and never owns, whatever an audit reports about it.
+* is re-derived from the plan and narrowed by what git tracks, and the audit
+* must agree with that derivation rather than supply the set itself.
+* Repository metadata is protected because losing history is not a repair,
+* and a target's own `src` and `app` trees are protected because a
+* workspace's source is the one thing scaffold never plans and never owns. A
+* plan the compiler emits never maps a protected root, so this guard exists
+* for the caller-authored plan a consumer can still supply.
 *
 * @example
 * ```ts
@@ -611,7 +613,7 @@ function computeDigest(content) {
 * detect a membership edit that did not update it. Order is part of the claim
 * rather than normalized away, because a staged manifest sorts its entries and
 * roots once and a reordered copy is a different file. Each entry is projected
-* to exactly the three declared fields, so a hand-added property cannot ride
+* to exactly the declared fields, so a hand-added property cannot ride
 * into the digest and cannot change it either.
 *
 * @example
@@ -700,8 +702,8 @@ function isExactCaseFile(path) {
 * @returns `true` only for a directory that is not a link.
 *
 * @remarks
-* A junction and a directory symbolic link both report as directories once
-* followed, so the inspection deliberately does not follow: a redirected
+* A junction and a directory symbolic link both report as directories after
+* they are followed, so the inspection deliberately does not follow: a redirected
 * directory is refused here rather than silently accepted as the one the caller
 * named.
 *
@@ -1125,7 +1127,7 @@ function listDirectories(root) {
 * snapshot all compare as the same digits. The file's identity and size are
 * measured before and after the read, and one extra byte is requested past the
 * declared size, so a file that grew or was replaced mid-read answers
-* `undefined` rather than half of two files.
+* `undefined` rather than half of one file and half of another.
 *
 * @example
 * ```ts
@@ -1214,7 +1216,7 @@ function readFileText(root, path, limit = _src_core.MAX_ARTIFACT_BYTES) {
 * The one door from a real directory into the vocabulary an audit compares in.
 * Absence is omission rather than an empty value, because core reads a missing
 * key as a missing destination and an empty string as a present directory; the
-* two are different verdicts. A path that is there but unreadable throws instead
+* they are different verdicts. A path that is there but unreadable throws instead
 * of being omitted, because omission would report it as missing and a repair
 * would then overwrite whatever is actually sitting there.
 *
@@ -1274,7 +1276,7 @@ function readSnapshot(target, paths) {
 * read, is not the declared shape, or does not match its own membership.
 *
 * @remarks
-* The two failures are held apart deliberately. A host with no manifest is a
+* The failures are held apart deliberately. A host with no manifest is a
 * raw checkout, and a caller reads it by mapping each path one to one. A host
 * with a manifest that does not verify is a staged host that has been edited,
 * and answering `undefined` there would degrade it to that same one-to-one
@@ -1322,8 +1324,8 @@ function readHostManifest(host) {
 * package will vendor or carries more bytes than one artifact may.
 *
 * @remarks
-* The one place the three declared fields are decided together, because they are
-* three readings of one path: {@link pathToStorage} decides where it is stored,
+* The one place the declared fields are decided together, because they are
+* readings of one path: {@link pathToStorage} decides where it is stored,
 * the destination is the path it answers for, and {@link matchesExecutablePath}
 * decides whether a target receives it executable.
 *
@@ -1372,7 +1374,7 @@ function readManifestEntry(destination, source) {
 * every destination to what the caller observed, and rolls a failed commit back.
 * This reads this package's own checkout at build time and fills its own build
 * output. Different direction, different lifetime, no consumer target involved,
-* so the two do not overlap and neither one belongs inside the other.
+* so they do not overlap and neither one belongs inside the other.
 *
 * Staging is plain rather than transactional for the same reason. A
 * `WriteTransaction` exists to hold a directory that already holds work
@@ -1546,7 +1548,7 @@ function readAnchor(path) {
 * @remarks
 * This binds location rather than history. `true` means the path still resolves
 * to the same physical directory on the same device, so the next write lands
-* where the last one did. A path now holding nothing, a file, or a symlink
+* where the last one did. A path holding nothing, a file, or a symlink
 * answers `false`; a directory swapped in by `rename` also answers `false`
 * because the replacement carries its own inode. A directory deleted and made
 * again under the same name can receive the old inode back and answers `true`,
@@ -1617,7 +1619,7 @@ function readExpectation(path) {
 * Test whether a destination still holds what was captured of it.
 *
 * @param expectation - The state captured earlier.
-* @returns `true` when re-reading the destination now produces that same state.
+* @returns `true` when re-reading the destination produces that same state.
 *
 * @remarks
 * Compared field for field against a fresh {@link readExpectation}, so an
@@ -1678,7 +1680,7 @@ function matchesPrecondition(precondition) {
 * has not touched the target at all. Commit is the only step that mutates the
 * target, and it is the only step that can need rolling back.
 *
-* Two bindings hold a destination still. A **precondition** is what the caller
+* A precondition and an expectation hold a destination still. A **precondition** is what the caller
 * observed earlier and is checked once, at construction, so a target that moved
 * between the caller's read and this transaction fails before anything is
 * created. An **expectation** is captured here, at construction, and re-checked
@@ -1702,7 +1704,7 @@ function matchesPrecondition(precondition) {
 *   elsewhere, or nothing is refused. An ancestor deleted and recreated under
 *   the same name can receive its old inode back and is indistinguishable here
 *   from one that never moved.
-* - **No crash atomicity across destinations.** A process killed between two
+* - **No crash atomicity across destinations.** A process killed between
 *   promotions leaves the target holding some new files and some old ones, and
 *   leaves the private root behind. Nothing here is a journal, and the private
 *   root's name is the only record a later run could read.
@@ -1835,7 +1837,7 @@ var WriteTransaction = class {
 	* Stage one text file.
 	*
 	* @param path - The target-relative path to write.
-	* @param content - The exact UTF-8 text the destination should hold.
+	* @param content - The exact UTF-8 text the destination must hold.
 	* @returns Nothing.
 	* @throws {@link ScaffoldError} coded `INVALID` when the path is not one this
 	* transaction opened or is already staged, `TARGET` when the destination holds
@@ -1867,7 +1869,7 @@ var WriteTransaction = class {
 	*
 	* @param path - The target-relative path to write.
 	* @param source - The resolved absolute path to copy the bytes from.
-	* @param executable - Whether the destination should carry the executable bit.
+	* @param executable - If `true`, the destination carries the executable bit; if `false`, it does not.
 	* @returns Nothing.
 	* @throws {@link ScaffoldError} coded `INVALID` when the path is not one this
 	* transaction opened or is already staged, `TARGET` when the destination holds
@@ -1917,7 +1919,7 @@ var WriteTransaction = class {
 	* created segment is captured by device and inode, so a segment swapped
 	* underneath the transaction is detected rather than written into.
 	*/
-	directory(path) {
+	establish(path) {
 		this.#assertOpen();
 		if (this.#expectation(path).shape === "file") throw new _src_core.ScaffoldError("TARGET", `The destination at ${path} holds a file.`, { path });
 		const established = (0, _orkestrel_contract.attempt)(() => this.#establish(this.#resolve(this.#target, path)));
@@ -2180,7 +2182,7 @@ var WriteTransaction = class {
 * The mutation spine: read the vendored host, re-derive the target, stage, swap.
 *
 * @remarks
-* Every verb runs the same three steps. It snapshots each caller-supplied value
+* Every verb runs the same steps. It snapshots each caller-supplied value
 * and guards the snapshot, so a property backed by an accessor never reaches a
 * decision. It re-derives what it is about to touch and compares that against
 * the observation the caller handed in, refusing the whole call when anything
@@ -2403,7 +2405,7 @@ var Materializer = class Materializer {
 	/**
 	* Rewrite the marker-bounded package table in the target's catalog agent file.
 	*
-	* @param entries - The published packages the table should list.
+	* @param entries - The published packages the table must list.
 	* @param target - The directory to write into.
 	* @returns The catalog path, written when the region's bytes moved and skipped otherwise.
 	* @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
@@ -2412,7 +2414,7 @@ var Materializer = class Materializer {
 	* `DESTROYED` after teardown.
 	*
 	* @remarks
-	* Only the text between the two markers is replaced, so every word a consumer
+	* Only the text between the markers is replaced, so every word a consumer
 	* wrote around the table survives the call. A row whose lookup produced no
 	* version prints the cause it carries instead, because dropping the row would
 	* hide a package the organization publishes behind one failed request.
@@ -2426,7 +2428,7 @@ var Materializer = class Materializer {
 	/**
 	* Rewrite the `@orkestrel/*` range set in the target's manifest.
 	*
-	* @param dependencies - The names and ranges the manifest should declare.
+	* @param dependencies - The names and ranges the manifest must declare.
 	* @param target - The directory to write into.
 	* @returns The manifest path, written when a declared range moved and skipped otherwise.
 	* @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
@@ -2448,9 +2450,10 @@ var Materializer = class Materializer {
 		return this.#rewrite(directory, "package.json", _src_core.MAX_MANIFEST_BYTES, this.#redeclare(accepted));
 	}
 	/**
-	* Delete the files the plan does not own.
+	* Re-derive and delete the tracked files the plan does not own.
 	*
-	* @param audit - The preview returned by this materializer's `audit` method; its foreign findings are the candidate set.
+	* @param plan - The compiled plan that decides which paths are foreign.
+	* @param audit - The preview returned by this materializer's `audit` method; it must agree with the candidate set this call re-derives.
 	* @param repository - The target's git state; only a tracked path is ever deleted.
 	* @param target - The directory to delete from.
 	* @returns The paths removed.
@@ -2467,9 +2470,14 @@ var Materializer = class Materializer {
 	* the audit reports, and neither is anything git does not track: git is the
 	* 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.
+	*
+	* 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.
 	*/
-	remove(audit, repository, target) {
+	remove(plan, audit, repository, target) {
 		this.#assertAlive();
+		const accepted = this.#accept(plan, _src_core.isPlan, "plan");
 		const preview = this.#accept(audit, _src_core.isAudit, "audit");
 		const state = this.#accept(repository, isRepository, "repository");
 		const directory = this.#accept(target, isFilesystemPath, "target");
@@ -2477,28 +2485,21 @@ var Materializer = class Materializer {
 			target: directory,
 			dirty: state.dirty.length
 		});
+		const derived = this.#derive(accepted, directory);
+		this.#reconfirmCandidates(derived.findings, preview.findings, directory);
 		const tracked = new Set(state.tracked);
-		const observed = /* @__PURE__ */ new Map();
 		const removals = [];
 		const skipped = [];
-		for (const finding of preview.findings) {
+		for (const finding of derived.findings) {
 			if (finding.drift !== "foreign") continue;
 			if (!tracked.has(finding.path) || matchesProtectedPath(finding.path)) {
 				skipped.push(finding.path);
 				continue;
 			}
-			observed.set(finding.path, finding.observed);
 			removals.push(finding.path);
 		}
-		const current = readSnapshot(directory, removals);
 		const preconditions = [];
-		for (const path of removals) {
-			if (current[path] !== observed.get(path)) throw this.#error("TARGET", `The path ${path} moved since its audit.`, {
-				target: directory,
-				path
-			});
-			preconditions.push(this.#bind(directory, path, false));
-		}
+		for (const path of removals) preconditions.push(this.#bind(directory, path, false));
 		return this.#purge(directory, removals, skipped, preconditions);
 	}
 	/**
@@ -2729,6 +2730,35 @@ var Materializer = class Materializer {
 			});
 		}
 	}
+	#reconfirmCandidates(derived, preview, target) {
+		const current = derived.filter((finding) => finding.drift === "foreign");
+		const supplied = preview.filter((finding) => finding.drift === "foreign");
+		const candidates = new Map(current.map((finding) => [finding.path, finding]));
+		const previewed = new Map(supplied.map((finding) => [finding.path, finding]));
+		if (candidates.size !== current.length || previewed.size !== supplied.length) throw this.#error("TARGET", "The audit repeats a deletion candidate.", { target });
+		for (const finding of supplied) {
+			const candidate = candidates.get(finding.path);
+			if (candidate === void 0) throw this.#error("TARGET", `The path ${finding.path} is not a deletion candidate for this plan.`, {
+				target,
+				path: finding.path
+			});
+			if (candidate.group !== finding.group) throw this.#error("TARGET", `The path ${finding.path} carries a group this plan does not derive.`, {
+				target,
+				path: finding.path
+			});
+			if (candidate.observed !== finding.observed) throw this.#error("TARGET", `The path ${finding.path} moved since its audit.`, {
+				target,
+				path: finding.path
+			});
+		}
+		for (const finding of current) {
+			if (previewed.has(finding.path)) continue;
+			throw this.#error("TARGET", `The path ${finding.path} is not covered by its audit.`, {
+				target,
+				path: finding.path
+			});
+		}
+	}
 	#bind(target, path, absent) {
 		const destination = resolveContainedPath(target, path);
 		if (destination === void 0) throw this.#error("INVALID", `The path ${path} is off contract or leaves its target.`, {
@@ -2783,7 +2813,7 @@ var Materializer = class Materializer {
 		const staged = (0, _orkestrel_contract.attempt)(() => {
 			for (const artifact of writes) if (artifact.origin === "host") this.#copy(transaction, artifact);
 			else transaction.write(artifact.path, artifact.content);
-			for (const path of directories) transaction.directory(path);
+			for (const path of directories) transaction.establish(path);
 		});
 		const written = this.#close(transaction, staged, target);
 		for (const path of written) this.#emitter.emit("write", path);
@@ -2961,7 +2991,7 @@ var Materializer = class Materializer {
 * This is the package's only network reader, and it never writes. Every call
 * opens one byte allowance and spends it across every read the call makes, so a
 * caller is bounded twice over: `limit` refuses one oversized answer and
-* `budget` refuses many small ones. The two are separate exhaustion routes and
+* `budget` refuses many small ones. They are separate exhaustion routes and
 * neither bound covers the other.
 *
 * A per-package failure never escapes as a throw. It is projected into the
@@ -3017,7 +3047,7 @@ var Upstream = class Upstream {
 	/**
 	* Construct a reader over one guide host and one registry.
 	*
-	* @param options - The two endpoints, the request bounds, the initial
+	* @param options - The endpoints, the request bounds, the initial
 	* listeners, and the listener-error handler.
 	* @throws {@link ScaffoldError} coded `INVALID` when `options` is present but
 	* is not an option bag this reader accepts, or when either endpoint names a
@@ -3027,7 +3057,7 @@ var Upstream = class Upstream {
 	* `isEndpoint` bounds an endpoint's length and nothing else, so the scheme and
 	* host law is settled here, where a refusal can say which endpoint was refused
 	* and why. An endpoint must be HTTPS, or HTTP to a loopback host — the one
-	* place an unencrypted request has no network between the two ends. That
+	* place an unencrypted request has no network between its ends. That
 	* refuses `file:`, `data:`, and plain HTTP to a real host, and it is what
 	* keeps a fixture reachable without weakening transport security anywhere a
 	* real request goes. An endpoint carrying credentials, a query, or a fragment
@@ -3099,7 +3129,7 @@ var Upstream = class Upstream {
 	* always answers for the file it names. `observed` is carried through from
 	* `current` whatever the lookup produced, because it is the precondition the
 	* later write is held to and a failed fetch does not change what the target
-	* currently holds.
+	* holds.
 	*
 	* @example
 	* ```ts
@@ -3459,49 +3489,6 @@ var Upstream = class Upstream {
 	}
 };
 //#endregion
-//#region src/server/factories.ts
-/**
-* Construct a {@link Materializer}.
-*
-* @param options - The vendored host root, the initial listeners, and the listener-error handler.
-* @returns The materializer, typed as the contract consumers program against.
-* @throws {@link ScaffoldError} coded `INVALID` when `options` is present but is
-* not an option bag the materializer accepts, and `TARGET` when the host carries
-* a manifest that cannot be read or does not match what it stores.
-*
-* @example
-* ```ts
-* import { createMaterializer } from '@orkestrel/scaffold/server'
-*
-* const materializer = createMaterializer({ host: './dist/host' })
-* materializer.destroy()
-* ```
-*/
-function createMaterializer(options) {
-	return new Materializer(options);
-}
-/**
-* Construct an {@link Upstream}.
-*
-* @param options - The two endpoints, the request bounds, the initial listeners,
-* and the listener-error handler.
-* @returns The reader, typed as the contract consumers program against.
-* @throws {@link ScaffoldError} coded `INVALID` when `options` is present but is
-* not an option bag the reader accepts, or when either endpoint names a scheme,
-* host, or form the reader will not request.
-*
-* @example
-* ```ts
-* import { createUpstream } from '@orkestrel/scaffold/server'
-*
-* const upstream = createUpstream({ guides: { branch: 'main' } })
-* upstream.destroy()
-* ```
-*/
-function createUpstream(options) {
-	return new Upstream(options);
-}
-//#endregion
 exports.BRANCH_PATTERN = BRANCH_PATTERN;
 exports.DIGEST_PATTERN = DIGEST_PATTERN;
 exports.DRIVE_PATTERN = DRIVE_PATTERN;
@@ -3522,8 +3509,6 @@ exports.WriteTransaction = WriteTransaction;
 exports.computeDigest = computeDigest;
 exports.computeFileDigest = computeFileDigest;
 exports.computeManifestDigest = computeManifestDigest;
-exports.createMaterializer = createMaterializer;
-exports.createUpstream = createUpstream;
 exports.isBranch = isBranch;
 exports.isCatalogEntries = isCatalogEntries;
 exports.isDependencies = isDependencies;