@orkestrel/scaffold 0.0.118 → 0.0.119

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -348,7 +348,8 @@ export declare interface HostInventory {
348
348
  * @remarks
349
349
  * `roots` is the sorted directory inventory, which is what distinguishes a
350
350
  * declared empty directory. `surface` records only names claimed by distinct
351
- * guides, sorted by name with each owner list sorted. `digest` is the SHA-256
351
+ * guides or admitted to a keeper by `SURFACE_TRANSFERS`, sorted by name with each
352
+ * owner list sorted. `digest` is the SHA-256
352
353
  * of the exact entries, roots, and surface, so an edit without its digest is
353
354
  * detected. A self-consistent replacement manifest defines its own smaller
354
355
  * membership; authenticating omitted membership is outside a checksum's
@@ -2330,8 +2331,9 @@ export declare class Materializer implements MaterializerInterface {
2330
2331
  * host root is not vacant, the checkout does not carry every vendored path, two
2331
2332
  * vendored files claim one storage name, a vendored file is not a plain file
2332
2333
  * within the artifact ceiling, published guides are unreadable, a staged
2333
- * collision's owner set is not a subset of its published owner set, the inventory is absent without
2334
- * `establish: true`, or the staged manifest does not read back.
2334
+ * collision's owner set is not a subset of its published owner set, a
2335
+ * `SURFACE_TRANSFERS` entry is spent because its keeper alone claims the name, the
2336
+ * inventory is absent without `establish: true`, or the staged manifest does not read back.
2335
2337
  * @throws `ScaffoldError('WRITE', …)` when a staged file or the manifest cannot
2336
2338
  * be written.
2337
2339
  *
@@ -2367,7 +2369,10 @@ export declare class Materializer implements MaterializerInterface {
2367
2369
  * the canon and reference files for reading. Every catalog package must have a
2368
2370
  * guide in the discovered membership before the host is written.
2369
2371
  * Copied guides must carry no collision whose name and exact owner set the
2370
- * committed inventory lacks. An absent inventory requires `establish: true`;
2372
+ * committed inventory lacks. A `SURFACE_TRANSFERS` entry that another guide claims
2373
+ * admits its keeper beside the recorded owners, or beside the one owner of a name
2374
+ * the inventory lacks, and the staged surface records that keeper whether or not
2375
+ * its guide is mirrored. An absent inventory requires `establish: true`;
2371
2376
  * an inventory without a valid recorded Surface is refused.
2372
2377
  * Everything downstream — the missing-path refusal, the
2373
2378
  * storage collision guard, the sort, the digests, and the root inventory — reads
@@ -348,7 +348,8 @@ export declare interface HostInventory {
348
348
  * @remarks
349
349
  * `roots` is the sorted directory inventory, which is what distinguishes a
350
350
  * declared empty directory. `surface` records only names claimed by distinct
351
- * guides, sorted by name with each owner list sorted. `digest` is the SHA-256
351
+ * guides or admitted to a keeper by `SURFACE_TRANSFERS`, sorted by name with each
352
+ * owner list sorted. `digest` is the SHA-256
352
353
  * of the exact entries, roots, and surface, so an edit without its digest is
353
354
  * detected. A self-consistent replacement manifest defines its own smaller
354
355
  * membership; authenticating omitted membership is outside a checksum's
@@ -2330,8 +2331,9 @@ export declare class Materializer implements MaterializerInterface {
2330
2331
  * host root is not vacant, the checkout does not carry every vendored path, two
2331
2332
  * vendored files claim one storage name, a vendored file is not a plain file
2332
2333
  * within the artifact ceiling, published guides are unreadable, a staged
2333
- * collision's owner set is not a subset of its published owner set, the inventory is absent without
2334
- * `establish: true`, or the staged manifest does not read back.
2334
+ * collision's owner set is not a subset of its published owner set, a
2335
+ * `SURFACE_TRANSFERS` entry is spent because its keeper alone claims the name, the
2336
+ * inventory is absent without `establish: true`, or the staged manifest does not read back.
2335
2337
  * @throws `ScaffoldError('WRITE', …)` when a staged file or the manifest cannot
2336
2338
  * be written.
2337
2339
  *
@@ -2367,7 +2369,10 @@ export declare class Materializer implements MaterializerInterface {
2367
2369
  * the canon and reference files for reading. Every catalog package must have a
2368
2370
  * guide in the discovered membership before the host is written.
2369
2371
  * Copied guides must carry no collision whose name and exact owner set the
2370
- * committed inventory lacks. An absent inventory requires `establish: true`;
2372
+ * committed inventory lacks. A `SURFACE_TRANSFERS` entry that another guide claims
2373
+ * admits its keeper beside the recorded owners, or beside the one owner of a name
2374
+ * the inventory lacks, and the staged surface records that keeper whether or not
2375
+ * its guide is mirrored. An absent inventory requires `establish: true`;
2371
2376
  * an inventory without a valid recorded Surface is refused.
2372
2377
  * Everything downstream — the missing-path refusal, the
2373
2378
  * storage collision guard, the sort, the digests, and the root inventory — reads
@@ -1,6 +1,6 @@
1
1
  import { createRequire } from "node:module";
2
2
  import { andOf, arrayOf, attempt, boundsOf, compareValues, compileGuard, holds, isArray, isBoolean, isDefined, isError, isFunction, isInteger, isNonNegativeInteger, isNumber, isObject, isRecord, isString, parseJSON, parseJSONAs, parseStringField, recordOf, recordShape, stringOf, stringShape, unionOf, whereOf } from "@orkestrel/contract";
3
- import { CANON_PATHS, CATALOG_AGENT_PATH, CATALOG_END_MARKER, CATALOG_START_MARKER, CONTROL_CHARACTER_PATTERN, DEPENDENCY_NAME_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, REFERENCE_PATHS, ScaffoldError, bytesToHex, catalogToLayers, cloneValue, collectSurfaceCollisions, collectSurfaceConflicts, compareSurfaceCollisions, compareVersions, computeBytes, computeTotal, contentToHex, extractRangeMajor, extractVersion, inferGroup, insertManifestDependencies, isAudit, isCatalogEntry, isCollection, isDependency, isDependencyName, isFloorPath, isHex, isManifestScript, isMirror, isPath, isPlan, isRetainedPath, isSnapshot, iterateAnswers, manifestToName, matchesDriftReachability, matchesRange, nameToGuide, planToFindings, renderSkillPointer, replaceManifestOverrides, replaceManifestRanges, replaceManifestScripts } from "../core/index.js";
3
+ import { CANON_PATHS, CATALOG_AGENT_PATH, CATALOG_END_MARKER, CATALOG_START_MARKER, CONTROL_CHARACTER_PATTERN, DEPENDENCY_NAME_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, REFERENCE_PATHS, SURFACE_TRANSFERS, ScaffoldError, bytesToHex, catalogToLayers, cloneValue, collectSurfaceCollisions, collectSurfaceConflicts, compareSurfaceCollisions, compareVersions, computeBytes, computeTotal, contentToHex, extractRangeMajor, extractVersion, inferGroup, insertManifestDependencies, isAudit, isCatalogEntry, isCollection, isDependency, isDependencyName, isFloorPath, isHex, isManifestScript, isMirror, isPath, isPlan, isRetainedPath, isSnapshot, iterateAnswers, manifestToName, matchesDriftReachability, matchesRange, nameToGuide, planToFindings, renderSkillPointer, replaceManifestOverrides, replaceManifestRanges, replaceManifestScripts } from "../core/index.js";
4
4
  import { createHash, randomUUID } from "node:crypto";
5
5
  import { chmodSync, closeSync, constants, copyFileSync, fstatSync, linkSync, lstatSync, mkdirSync, mkdtempSync, openSync, opendirSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
6
6
  import { tmpdir } from "node:os";
@@ -1491,8 +1491,9 @@ function stageBytes(host, root, destinations) {
1491
1491
  * host root is not vacant, the checkout does not carry every vendored path, two
1492
1492
  * vendored files claim one storage name, a vendored file is not a plain file
1493
1493
  * within the artifact ceiling, published guides are unreadable, a staged
1494
- * collision's owner set is not a subset of its published owner set, the inventory is absent without
1495
- * `establish: true`, or the staged manifest does not read back.
1494
+ * collision's owner set is not a subset of its published owner set, a
1495
+ * `SURFACE_TRANSFERS` entry is spent because its keeper alone claims the name, the
1496
+ * inventory is absent without `establish: true`, or the staged manifest does not read back.
1496
1497
  * @throws `ScaffoldError('WRITE', …)` when a staged file or the manifest cannot
1497
1498
  * be written.
1498
1499
  *
@@ -1528,7 +1529,10 @@ function stageBytes(host, root, destinations) {
1528
1529
  * the canon and reference files for reading. Every catalog package must have a
1529
1530
  * guide in the discovered membership before the host is written.
1530
1531
  * Copied guides must carry no collision whose name and exact owner set the
1531
- * committed inventory lacks. An absent inventory requires `establish: true`;
1532
+ * committed inventory lacks. A `SURFACE_TRANSFERS` entry that another guide claims
1533
+ * admits its keeper beside the recorded owners, or beside the one owner of a name
1534
+ * the inventory lacks, and the staged surface records that keeper whether or not
1535
+ * its guide is mirrored. An absent inventory requires `establish: true`;
1532
1536
  * an inventory without a valid recorded Surface is refused.
1533
1537
  * Everything downstream — the missing-path refusal, the
1534
1538
  * storage collision guard, the sort, the digests, and the root inventory — reads
@@ -1669,29 +1673,48 @@ function stageHost(checkout, host, options) {
1669
1673
  digest
1670
1674
  };
1671
1675
  });
1672
- const collisions = readSurfaceCollisions(join(root, "guides"));
1673
- const growth = published === void 0 ? [] : compareSurfaceCollisions([...collisions].map(([name, owners]) => ({
1676
+ const claims = readSurfaceClaims(join(root, "guides"));
1677
+ const claimants = Map.groupBy(claims.flatMap(({ owner, names }) => names.map((name) => ({
1674
1678
  name,
1675
- owners
1676
- })), [...published].map(([name, owners]) => ({
1679
+ owner
1680
+ }))), ({ name }) => name);
1681
+ const transfers = SURFACE_TRANSFERS.map((transfer) => {
1682
+ const owners = new Set(claimants.get(transfer.name)?.map(({ owner }) => owner));
1683
+ return {
1684
+ ...transfer,
1685
+ claimed: owners.has(transfer.keeper),
1686
+ givers: [...owners].filter((owner) => owner !== transfer.keeper).sort()
1687
+ };
1688
+ });
1689
+ const spent = transfers.filter(({ claimed, givers }) => claimed && givers.length === 0).map(({ name, keeper, item }) => `${name} to ${keeper} under item ${item}`);
1690
+ if (spent.length > 0) throw new ScaffoldError("TARGET", `Surface transfers are spent, so remove them from SURFACE_TRANSFERS: ${spent.join("; ")}`, {
1691
+ checkout: source,
1692
+ host: root,
1693
+ transfers: spent
1694
+ });
1695
+ const active = transfers.filter(({ givers }) => givers.length > 0);
1696
+ const collisions = collectSurfaceCollisions([...claims, ...active.map(({ name, keeper }) => ({
1697
+ owner: keeper,
1698
+ names: [name]
1699
+ }))]);
1700
+ const growth = published === void 0 ? [] : compareSurfaceCollisions(collisions, [...new Map([...published, ...active.map(({ name, keeper, givers }) => [name, [...published.get(name) ?? (givers.length === 1 ? givers : []), keeper]])])].map(([name, owners]) => ({
1677
1701
  name,
1678
1702
  owners
1679
- }))).filter(({ standing }) => standing === "error").map(({ name, owners }) => `${name} staged (${owners.join(", ")}), recorded (${published.get(name)?.join(", ") ?? "absent"})`);
1703
+ }))).filter(({ standing }) => standing === "error").map(({ name, owners }) => {
1704
+ const keeper = active.find((transfer) => transfer.name === name)?.keeper;
1705
+ return `${name} staged (${owners.join(", ")}), recorded (${published.get(name)?.join(", ") ?? "absent"})${keeper === void 0 ? "" : `, transferred to ${keeper}`}`;
1706
+ });
1680
1707
  if (growth.length > 0) throw new ScaffoldError("TARGET", `Staged Surface collisions differ from the inventory: ${growth.join("; ")}`, {
1681
1708
  checkout: source,
1682
1709
  host: root,
1683
1710
  baseline,
1684
1711
  collisions: growth
1685
1712
  });
1686
- const surface = [...collisions].map(([name, owners]) => ({
1687
- name,
1688
- owners
1689
- }));
1690
1713
  const manifest = {
1691
1714
  entries,
1692
1715
  roots,
1693
- surface,
1694
- digest: computeManifestDigest(entries, roots, surface)
1716
+ surface: collisions,
1717
+ digest: computeManifestDigest(entries, roots, collisions)
1695
1718
  };
1696
1719
  const metadata = resolveContainedPath(root, MANIFEST_NAME);
1697
1720
  if (metadata === void 0) throw new ScaffoldError("INVALID", `Host manifest leaves its root at ${root}`, { host: root });