@clossys/launcher 0.3.1 → 0.4.0

package/src/host.ts

@@ -58,9 +58,19 @@ export function createNodeHost(cwd = process.cwd(), env: NodeJS.ProcessEnv = pro
         return null;
       }
     },
+    readBytes: (path) => {
+      try {
+        return readFileSync(path);
+      } catch {
+        return null;
+      }
+    },
     writeText: (path, contents) => {
       writeFileSync(path, contents, "utf8");
     },
+    writeBytes: (path, contents) => {
+      writeFileSync(path, contents);
+    },
     mkdirp: (path) => {
       mkdirSync(path, { recursive: true });
     },

package/src/identity.ts

@@ -0,0 +1,51 @@
+// The one rule for "is this the same GitHub repository" and "is this the
+// same GitHub account" in Launcher (#1179). Every such decision -- the
+// inventory's duplicate rule, a --repositories choice against the stored
+// inventory, the appoint --inventory merge, the hub excluding itself from
+// its own roster, matching a sibling checkout's origin, whether an id
+// belongs to the hub's account, CLOSSYS_OWNER against the origin, and the
+// drift report -- goes through the functions below and nothing else.
+//
+// GitHub compares owner and repository names without regard to letter case,
+// and a bare inventory id names a repository of the hub's own owner, as
+// Launcher's sibling resolution reads it. A folder path is never used as a
+// repository's identity: on a case-insensitive file system two spellings of
+// a path name the same folder, so a path comparison can disagree with the
+// repository it holds.
+
+/** An owner or repository name as GitHub compares it. */
+function nameKey(name: string): string {
+  return name.toLowerCase();
+}
+
+/**
+ * The identity of a repository id: a bare id is qualified with the hub's
+ * owner when that owner is known, and the result is compared as GitHub
+ * compares names. Without an owner, a bare id stays bare.
+ */
+export function inventoryKey(id: string, hubOwner?: string): string {
+  return nameKey(hubOwner !== undefined && !id.includes("/") ? `${hubOwner}/${id}` : id);
+}
+
+/** Whether two repository ids name the same repository. */
+export function sameRepository(left: string, right: string, hubOwner?: string): boolean {
+  return inventoryKey(left, hubOwner) === inventoryKey(right, hubOwner);
+}
+
+/** Whether two owner names name the same GitHub account. */
+export function sameOwner(left: string, right: string): boolean {
+  return nameKey(left) === nameKey(right);
+}
+
+/** Whether a repository id names a repository of `hubOwner`'s account (a bare id always does). */
+export function belongsToOwner(id: string, hubOwner: string): boolean {
+  const slash = id.indexOf("/");
+  return slash === -1 || sameOwner(id.slice(0, slash), hubOwner);
+}
+
+/** The first spelling of each distinct owner, in order: case variants of one account are one owner. */
+export function distinctOwners(owners: Iterable<string>): string[] {
+  const kept: string[] = [];
+  for (const owner of owners) if (!kept.some((existing) => sameOwner(existing, owner))) kept.push(owner);
+  return kept;
+}

package/src/index.ts

@@ -14,6 +14,7 @@ export {
   readInventoryRepositories,
   readLiveLauncherVersion,
   reportHubHealth,
+  validateInventoryDocument,
   CLOSSYS_DIR_REL,
   CLOSSYS_README_REL,
   DEFAULT_REPOSITORY_NAME,
@@ -24,17 +25,70 @@ export {
   WORKSPACE_INVENTORY_REL,
   WORKSPACE_MARKER_REL,
 } from "./core.js";
-export type { CloneMissingOutcome } from "./core.js";
+export type { CloneMissingOutcome, InventoryValidation, PlanWorkspaceOptions } from "./core.js";
+export type { InventoryReadOptions } from "./inventory-contract.js";
 export { runDoctorChecks, renderDoctorReport } from "./doctor.js";
-export { applyEngagementBrief, isPlanApproved, validateAdvisorPlan, validateEngagementBrief } from "./apply-plan.js";
-export type { AdvisorPlan, ApplyBriefResult, BlockerKind, EngagementBrief, EngagementBriefRole, PlanBlocker, PlanDecision, ValidationResult } from "./apply-plan.js";
+export { applyEngagementBrief, approvedSubject, isPlanApproved, validateAdvisorPlan, validateEngagementBrief } from "./apply-plan.js";
+export type {
+  AdvisorPlan, ApplyBriefResult, BlockerKind, EngagementBrief, EngagementBriefRole, EngagementContext, EngagementContextField, EngagementContextFieldId, GoalDirection, PlanBlocker,
+  PlanDecision, PlanKit, PlanPackageAct, PlanStaffing, ValidationResult,
+} from "./apply-plan.js";
+export { PLAN_DIGEST_EXCLUDED_FIELDS, canonicalDigest, canonicalJson, planDigest } from "./plan-digest.js";
+export { CHANGE_SET_DIGEST_EXCLUDED_FIELDS, DERIVED_FILE_DIGEST_FIELDS, bundleDigest, changeSetDigest, changeSetDigestSubject } from "./change-set-digest.js";
+export type { BundleDigestEntry } from "./change-set-digest.js";
+export { AGENTS_GUIDE_PATH, AGENTS_GUIDE_TEXT, CLOSSYS_SKILL_PATTERNS, verifyAgentsGuide } from "./agents-guide.js";
+export { validateApplyBundle, validateRepositoryChangeSet } from "./change-set-contract.js";
+export type {
+  ApplyBundle, ApplyBundleRepository, ApplyCheck, ApplyCheckId, ApprovalBinding, ChangeSetDeferral, ChangeSetItem, ChangeSetPhase, ChangeSetRefusal, CheckVerdict, ContentDigest,
+  DependencyPlacement, DerivedFileChange, DiscoveryRoot, ExemptionSurfaceKind, FileChange, KeyChange, LedgerInvariant, LockfileName, PackageInvariant, PackageManagerKind,
+  PinnedPackage, RefusalReason, ReleaseAgeSurfaceKind, RepositoryChangeSet, RepositoryProfileObservation, RepositoryVisibility, RootEntryDeclaration, WholeFileChange,
+  WriteRecordSource,
+} from "./change-set-contract.js";
+export { ledgerSuccession, readInstalledLedger, renderInstalledLedger, serializeInstalledLedger, validateInstalledLedger } from "./ledger-contract.js";
+export { reconcileWholeFile, trustInstalledLedger } from "./ledger-trust.js";
+export type { LedgerTrust, LedgerTrustRule, PlanPackageActs, TrustInstalledLedgerOptions, WholeFileOutcome, WholeFileState } from "./ledger-trust.js";
+export { BUNDLE_STORE_REL, CHANGE_SET_STORE_REL, readStoredApplyBundle, readStoredChangeSet, storeApplyBundle, storeChangeSet } from "./apply-store.js";
+export { isRootEntryName, wouldViolateRootEntries } from "./root-entries.js";
+export type { RootEntriesVerdict } from "./root-entries.js";
+export { editReleaseAgeExemption, verifyReleaseAgeExemption } from "./release-age-edit.js";
+export type { ReleaseAgeEdit, ReleaseAgeEditInput, ReleaseAgeEditRefusalReason, ReleaseAgeVerdict, ReleaseAgeVerifyInput } from "./release-age-edit.js";
+export type { InstalledLedger, LedgerPackageIdentity, LedgerSuccession, LedgerViolation } from "./ledger-contract.js";
+export { PUBLIC_PROBLEM_PLACEHOLDER, planApplyBundle, projectEngagementBrief, serializeEngagementBrief } from "./plan-bundle.js";
+export type { PlanApplyBundleInputs, PlanApplyBundleResult, RepositoryObservation, SkippedRepositoryObservation } from "./plan-bundle.js";
+export { observeRepository } from "./observe-repository.js";
+export type { ObserveRepositoryInput, RepositoryObservationPorts } from "./observe-repository.js";
 export type { DoctorCheckHost, DoctorReport, DoctorStepId, DoctorStepResult } from "./doctor.js";
 export { checkCloudSessionBootstrap } from "./product-repository.js";
 export type { CloudBootstrapCheck, CloudBootstrapReport } from "./product-repository.js";
+// Setup templates: pure renderers for the files a setup change writes.
+export {
+  renderSetupTemplate,
+  renderStarterRequest,
+  renderAdoptionDecisionWorkflow,
+  renderProductCiWorkflow,
+  STARTER_PIN_RANGE,
+} from "./setup-templates.js";
+export type {
+  SetupPackageManager,
+  StarterPinInput,
+  StarterRequestInput,
+  TemplateFile,
+  TemplateRefusal,
+  TemplateResult,
+} from "./setup-templates.js";
+export {
+  renderSnapshotCollector,
+  renderAdoptionEvidenceWorkflow,
+  renderPathScopeScript,
+  renderPathScopeWorkflow,
+  OWNED_PATH_PATTERNS,
+} from "./setup-template-scripts.js";
 export { reportInventoryDrift } from "./inventory-adoption.js";
 export type { ExternalInventoryDeclaration, InventoryDriftReport } from "./inventory-adoption.js";
 export { detectLinkedHosts, parseHostRecord, serializeHostRecord, HOSTS_REL } from "./hosts.js";
 export type { DiscoveredHost, HostRecord } from "./hosts.js";
+export { readChangeSetMarker, renderPullRequest } from "./pull-request-body.js";
+export type { PullRequestRefusal, PullRequestRefusalReason, PullRequestText, RenderPullRequestInput } from "./pull-request-body.js";
 export { parsePreferences, readHostModelProfile, resolveModelForTier } from "./model-profile.js";
 export type {
   BudgetPreference,
@@ -47,10 +101,14 @@ export type {
 } from "./model-profile.js";
 export type {
   ApplyWorkspaceOptions,
+  ChosenInventory,
   CommandResult,
   CwdObservation,
   DependencyBucket,
+  EngineInstallFinding,
+  EnginePinChange,
   HubDocument,
+  HubEnginePin,
   HubHealthReport,
   HubMigrationState,
   InventoryObservation,
@@ -69,3 +127,14 @@ export type {
   WorkspaceRefusal,
   WorkspaceState,
 } from "./types.js";
+export {
+  PROVENANCE_CHECK_BIN,
+  PROVENANCE_CHECK_MAX_BUFFER,
+  PROVENANCE_CHECK_TIMEOUT_MS,
+  checkSetProvenance,
+  registrySnapshotDigest,
+} from "./provenance-gate.js";
+export type { ProvenanceGateInput, ProvenanceGatePorts } from "./provenance-gate.js";
+
+export { decideSetBinding, planPackagesFor, readHubAuthority } from "./admission.js";
+export type { AdmissionDecision, AdmissionRefusal, HubAuthority, ReadinessRunner } from "./admission.js";

package/src/inventory-adoption.ts

@@ -4,6 +4,9 @@
 // it. Launcher writes only what that inventory lacks (a later apply step,
 // not this module) and reports drift instead of silently merging.
 
+import { readContractDocument } from "./generated/contract-schema.generated.js";
+import { sameRepository } from "./identity.js";
+import { validateInventoryDocument } from "./inventory-contract.js";
 import type { WorkspaceHost } from "./types.js";
 
 export interface ExternalInventoryDeclaration {
@@ -11,33 +14,69 @@ export interface ExternalInventoryDeclaration {
   readonly shape: "foundry" | "custom";
 }
 
+/**
+ * A count plus each disagreeing or agreeing id's position, never the ids
+ * themselves: `externalInventory` at `declaration.path` and Launcher's own
+ * stored inventory are both document content a hub declares or writes, and
+ * this whole report reaches `formatHubHealth`'s JSON-dumped `health:` line
+ * on every resume of a hub that declares `externalInventory`, so an id kept
+ * here would still reach that message (#1179). A position names the array
+ * it indexes into: `externalInventory[<i>]` for `declaration.path`'s
+ * `repositories[<i>].id`, `repositories[<j>]` for the hub's own stored
+ * inventory's `repositories[<j>].id`.
+ */
+export interface InventoryDriftPositions {
+  readonly count: number;
+  readonly positions: readonly string[];
+}
+
 export interface InventoryDriftReport {
   readonly status: "no-external-source" | "reconciled" | "indeterminate";
-  readonly externalOnly: readonly string[];
-  readonly launcherOnly: readonly string[];
-  readonly agreeing: readonly string[];
+  readonly externalOnly: InventoryDriftPositions;
+  readonly launcherOnly: InventoryDriftPositions;
+  readonly agreeing: InventoryDriftPositions;
   readonly note?: string;
 }
 
+const NO_DRIFT: InventoryDriftPositions = { count: 0, positions: [] };
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-/** Reads a foundry-shaped inventory document's repository ids. Malformed or missing is null, never []. */
-function readForeignIds(host: WorkspaceHost, path: string): readonly string[] | null {
-  const raw = host.readText(path);
+/** One `externalInventory` entry with a usable id, paired with its own index in that document's `repositories` array. */
+interface ForeignId {
+  readonly id: string;
+  readonly index: number;
+}
+
+/**
+ * Reads a foundry-shaped inventory document's repository ids. Malformed or
+ * missing is null, never []. The file is read as bytes by the shared strict
+ * reader, so bytes that are not valid UTF-8, a repeated key, or a byte order
+ * mark make it unreadable rather than silently repaired (#1179). Its shape
+ * is read leniently on purpose: an external source is not Launcher's own
+ * document -- a non-object entry, or one with a missing, blank or non-string
+ * `id`, is skipped rather than refusing the whole document. Skipped entries
+ * still occupy a slot in `repositories`, so each kept id is paired with its
+ * own original array index, never a count of ids kept so far: the file's
+ * fourth entry (index 3) must be reported as `externalInventory[3]` even
+ * when it is the second entry actually kept (#1179).
+ */
+function readForeignIds(host: WorkspaceHost, path: string): readonly ForeignId[] | null {
+  const raw = host.readBytes(path);
   if (raw === null) return null;
   let parsed: unknown;
   try {
-    parsed = JSON.parse(raw);
+    parsed = readContractDocument(raw);
   } catch {
     return null;
   }
   if (!isRecord(parsed) || parsed.schemaVersion !== 1 || !Array.isArray(parsed.repositories)) return null;
-  const ids: string[] = [];
-  for (const entry of parsed.repositories) {
-    if (isRecord(entry) && typeof entry.id === "string" && entry.id.trim() !== "") ids.push(entry.id);
-  }
+  const ids: ForeignId[] = [];
+  parsed.repositories.forEach((entry, index) => {
+    if (isRecord(entry) && typeof entry.id === "string" && entry.id.trim() !== "") ids.push({ id: entry.id, index });
+  });
   return ids;
 }
 
@@ -45,41 +84,80 @@ function readForeignIds(host: WorkspaceHost, path: string): readonly string[] |
  * Compares the declared external inventory against the launcher-written
  * inventory at `directory/launcherInventoryRelPath`. Read-only -- callers
  * decide whether and how to write the reconciled set, as an explicit,
- * approved apply step (same #1045 pattern as clone-on-approval).
+ * approved apply step (same #1045 pattern as clone-on-approval). Ids are
+ * compared with `sameRepository()` (identity.ts): case-insensitively, and,
+ * when `hubOwner` is given, with a bare id read as that owner's repository.
+ * The hub's own inventory is read by `validateInventoryDocument()`; when it
+ * is present but invalid the report is indeterminate.
  */
 export function reportInventoryDrift(
   host: WorkspaceHost,
   directory: string,
   declaration: ExternalInventoryDeclaration | undefined,
   launcherInventoryRelPath: string,
+  hubOwner?: string,
 ): InventoryDriftReport {
   if (declaration === undefined) {
-    return { status: "no-external-source", externalOnly: [], launcherOnly: [], agreeing: [] };
+    return { status: "no-external-source", externalOnly: NO_DRIFT, launcherOnly: NO_DRIFT, agreeing: NO_DRIFT };
   }
   if (declaration.shape === "custom") {
     return {
       status: "indeterminate",
-      externalOnly: [],
-      launcherOnly: [],
-      agreeing: [],
-      note: `externalInventory at ${declaration.path} declares shape "custom"; launcher has no mapping for a non-foundry inventory shape yet and will not guess one. Reconcile by hand or file the mapping gap.`,
+      externalOnly: NO_DRIFT,
+      launcherOnly: NO_DRIFT,
+      agreeing: NO_DRIFT,
+      note: `the declared \`externalInventory\` declares a shape launcher has no mapping for yet; launcher will not guess one. Reconcile by hand or file the mapping gap.`,
     };
   }
-  const externalIds = readForeignIds(host, declaration.path);
-  if (externalIds === null) {
+  const externalEntries = readForeignIds(host, declaration.path);
+  if (externalEntries === null) {
     return {
       status: "indeterminate",
-      externalOnly: [],
-      launcherOnly: [],
-      agreeing: [],
-      note: `externalInventory at ${declaration.path} could not be read as a populated schemaVersion:1 inventory document.`,
+      externalOnly: NO_DRIFT,
+      launcherOnly: NO_DRIFT,
+      agreeing: NO_DRIFT,
+      note: `the declared \`externalInventory\` could not be read as a populated schemaVersion:1 inventory document.`,
     };
   }
-  const launcherIds = readForeignIds(host, `${directory}/${launcherInventoryRelPath}`) ?? [];
-  const externalSet = new Set(externalIds);
-  const launcherSet = new Set(launcherIds);
-  const externalOnly = externalIds.filter((id) => !launcherSet.has(id));
-  const launcherOnly = launcherIds.filter((id) => !externalSet.has(id));
-  const agreeing = externalIds.filter((id) => launcherSet.has(id));
+  // Launcher's own inventory is read by its own strict reader. A missing one
+  // lists nothing; one that is present but cannot be read makes the
+  // comparison indeterminate, never a comparison against an empty list.
+  const launcherPath = `${directory}/${launcherInventoryRelPath}`;
+  const launcherBytes = host.readBytes(launcherPath);
+  let launcherIds: readonly string[] = [];
+  if (launcherBytes !== null) {
+    const launcher = validateInventoryDocument(launcherBytes, hubOwner === undefined ? {} : { hubOwner });
+    if (!launcher.valid) {
+      return {
+        status: "indeterminate",
+        externalOnly: NO_DRIFT,
+        launcherOnly: NO_DRIFT,
+        agreeing: NO_DRIFT,
+        note: `the hub's own inventory ${launcher.reason}, so it cannot be compared with the declared \`externalInventory\`.`,
+      };
+    }
+    launcherIds = launcher.ids;
+  }
+  // One repository identity, as everywhere in Launcher (identity.ts): a bare id is the hub owner's, and case is ignored.
+  const agrees = (id: string, others: readonly string[]) => others.some((other) => sameRepository(id, other, hubOwner));
+  const externalIds = externalEntries.map((entry) => entry.id);
+  // Every position below is the id's own index in the array a caller can already read
+  // (externalEntries.index is `externalInventory`'s document's own `repositories` index --
+  // readForeignIds() pairs it with the id precisely because that array is filtered, so a
+  // count of ids kept so far would not match the file (#1179); launcherIds is never
+  // filtered, so its own array index already is that position) -- never the id, per
+  // InventoryDriftPositions' own doc comment.
+  const externalOnly = externalEntries.reduce<{ count: number; positions: string[] }>(
+    (acc, entry) => (agrees(entry.id, launcherIds) ? acc : { count: acc.count + 1, positions: [...acc.positions, `externalInventory[${entry.index}]`] }),
+    { count: 0, positions: [] },
+  );
+  const launcherOnly = launcherIds.reduce<{ count: number; positions: string[] }>(
+    (acc, id, index) => (agrees(id, externalIds) ? acc : { count: acc.count + 1, positions: [...acc.positions, `repositories[${index}]`] }),
+    { count: 0, positions: [] },
+  );
+  const agreeing = externalEntries.reduce<{ count: number; positions: string[] }>(
+    (acc, entry) => (agrees(entry.id, launcherIds) ? { count: acc.count + 1, positions: [...acc.positions, `externalInventory[${entry.index}]`] } : acc),
+    { count: 0, positions: [] },
+  );
   return { status: "reconciled", externalOnly, launcherOnly, agreeing };
 }

package/src/inventory-choice.ts

@@ -0,0 +1,172 @@
+// Writing the hub inventory from the repositories a founder chose on
+// Advisor's repository-choice card (issue #1179), so a founder never
+// hand-writes JSON. `launcher --repositories` is the command; this module
+// decides what that command may write, and never writes anything itself.
+//
+// The chosen ids and the document built from them are validated against
+// docs/contracts/repository-inventory.json (in the public repository;
+// that exact path does not ship in this package, but this package's
+// build packs and ships its own copy of the contract) through the shared
+// contract checker (./inventory-contract.ts) -- the same check every later read of
+// the stored inventory applies, so what this writes, Launcher reads back.
+//
+// An inventory already on disk that names a different set of repositories
+// is never merged into or overwritten silently: the choice is refused, with
+// the difference in counts and positions, unless the caller passes an
+// explicit replace approval (`--replace-inventory`).
+//
+// Every message this module builds -- the refusal and the success line
+// alike -- names a repository only by its position, never by its id: a
+// stored inventory file, and the `--repositories` argument, are both
+// document-shaped input an agent may relay verbatim, and a repository id is
+// exactly the kind of short string a hostile entry could shape as
+// prompt-injection text (see ./inventory-contract.ts's own header). The
+// caller looks the reported position up in its own copy of the inventory
+// file or its own `--repositories` argument to learn which repository it
+// names.
+
+import { inventoryKey } from "./identity.js";
+import { readInventoryDocument, renderInventoryDocument, validateInventoryDocument, validateInventoryValue, type InventoryEntry } from "./inventory-contract.js";
+import type { ChosenInventory } from "./types.js";
+
+export type ChosenInventoryResolution =
+  | { readonly kind: "resolved"; readonly chosen: ChosenInventory }
+  | { readonly kind: "refuse"; readonly message: string };
+
+/** The command a refusal names for an explicit replace approval. */
+export const REPLACE_INVENTORY_FLAG = "--replace-inventory";
+
+function repositories(count: number): string {
+  return `${count} ${count === 1 ? "repository" : "repositories"}`;
+}
+
+/** Added ids are named by their position in the `--repositories` argument, never by the id itself. */
+function listAddedPositions(positions: readonly number[]): string {
+  return positions.length === 0 ? "" : ` (${positions.map((index) => `--repositories[${index}]`).join(", ")})`;
+}
+
+/**
+ * Removed ids are named by their position in an inventory's `repositories`
+ * array, never by the id itself. `label` distinguishes which file that
+ * position indexes into: `"stored inventory"` for the refusal, where the
+ * file on disk is still the one the positions were computed against, and
+ * `"replaced inventory"` for the success line after `--replace-inventory`
+ * writes -- by the time that line prints, the file on disk is already the
+ * new one, so reusing "stored inventory" there would point a reader at the
+ * wrong document (#1179).
+ */
+function listRemovedPositions(positions: readonly number[], label: "stored inventory" | "replaced inventory"): string {
+  return positions.length === 0 ? "" : ` (${positions.map((index) => `repositories[${index}] in the ${label}`).join(", ")})`;
+}
+
+/**
+ * Decides what `launcher --repositories` writes into a hub whose stored
+ * inventory is `onDisk` -- the file's exact bytes, or `null` when there is
+ * none.
+ *
+ * Every comparison uses `inventoryKey(id, hubOwner)`: a bare id names a
+ * repository of the hub's own owner, and letter case is ignored.
+ *
+ * - The chosen ids must form a valid inventory on their own: at least one
+ *   id, each one satisfying the contract's repository id rule, and no two
+ *   naming the same repository. A refusal names positions only.
+ * - The stored inventory is read by the same strict reader, with the same
+ *   owner: one that fails its contract, including one listing a repository
+ *   twice (for example `app` and `<hubOwner>/app`), is replaced only with
+ *   `replace`, and then with the chosen ids alone. It is never merged.
+ * - No inventory, or an empty one: the chosen repositories are written.
+ * - An inventory naming exactly the same repositories: nothing is written.
+ * - An inventory naming a different set: refused, reporting how many
+ *   repositories each side has and the positions that would be added and
+ *   removed (never the ids themselves), unless `replace` is true. A
+ *   replacement keeps each kept repository's existing entry as it was (its
+ *   `packages` included).
+ *
+ * The document to write is checked again by the same reader every later
+ * read uses, before it is returned.
+ */
+export function resolveChosenInventory(
+  onDisk: Uint8Array | string | null,
+  chosenIds: readonly string[],
+  hubOwner: string,
+  replace: boolean,
+): ChosenInventoryResolution {
+  if (chosenIds.length === 0) {
+    return { kind: "refuse", message: "--repositories must name at least one repository" };
+  }
+  const chosenCheck = validateInventoryValue({ schemaVersion: 1, repositories: chosenIds.map((id) => ({ id })) }, { hubOwner });
+  if (!chosenCheck.valid) return { kind: "refuse", message: `--repositories is not a valid inventory: ${chosenCheck.reason}` };
+
+  let entries: InventoryEntry[];
+  let added: readonly string[] = chosenIds;
+  let removed: readonly string[] = [];
+  let addedPositions: readonly number[] = chosenIds.map((_, index) => index);
+  let removedPositions: readonly number[] = [];
+  let replaced: Extract<ChosenInventory, { kind: "write" }>["replaced"] = "nothing";
+  let previousCount = 0;
+  if (onDisk === null) {
+    entries = chosenIds.map((id) => ({ id }));
+  } else {
+    const stored = readInventoryDocument(onDisk, { hubOwner });
+    if (!stored.valid) {
+      if (!replace) {
+        return {
+          kind: "refuse",
+          message: `the hub inventory ${stored.reason}; to replace it with the ${repositories(chosenIds.length)} chosen, run again with ${REPLACE_INVENTORY_FLAG}`,
+        };
+      }
+      entries = chosenIds.map((id) => ({ id }));
+      replaced = "invalid";
+    } else {
+      previousCount = stored.ids.length;
+      // Keys are unique on both sides: the reader and the chosen-id check above both refuse two ids with one key.
+      const storedByKey = new Map(stored.entries.map((entry) => [inventoryKey(entry.id, hubOwner), entry] as const));
+      const chosenKeys = new Set(chosenIds.map((id) => inventoryKey(id, hubOwner)));
+      added = chosenIds.filter((id) => !storedByKey.has(inventoryKey(id, hubOwner)));
+      removed = stored.ids.filter((id) => !chosenKeys.has(inventoryKey(id, hubOwner)));
+      // Positions, not ids: `added` indexes into the --repositories argument the caller passed; `removed` indexes into the stored inventory's own `repositories` array.
+      addedPositions = added.map((id) => chosenIds.indexOf(id));
+      removedPositions = removed.map((id) => stored.ids.indexOf(id));
+      if (stored.ids.length > 0 && added.length === 0 && removed.length === 0) {
+        return { kind: "resolved", chosen: { kind: "unchanged", count: stored.ids.length } };
+      }
+      if (stored.ids.length > 0) {
+        if (!replace) {
+          return {
+            kind: "refuse",
+            message:
+              `the hub inventory already lists ${repositories(stored.ids.length)} and the choice has ${chosenIds.length}: ` +
+              `${added.length} to add${listAddedPositions(addedPositions)}, ${removed.length} to remove${listRemovedPositions(removedPositions, "stored inventory")}. ` +
+              `Launcher never merges or overwrites an inventory silently; to replace it with the choice, run again with ${REPLACE_INVENTORY_FLAG}`,
+          };
+        }
+        replaced = "differing";
+      }
+      entries = chosenIds.map((id) => storedByKey.get(inventoryKey(id, hubOwner)) ?? { id });
+    }
+  }
+
+  const document = renderInventoryDocument(entries);
+  const written = validateInventoryDocument(document, { hubOwner });
+  if (!written.valid) return { kind: "refuse", message: `the inventory to write ${written.reason}` };
+  return {
+    kind: "resolved",
+    chosen: { kind: "write", document, count: written.ids.length, previousCount, added, removed, addedPositions, removedPositions, replaced },
+  };
+}
+
+/** One line for the apply message saying what happened to the inventory. */
+export function describeChosenInventory(chosen: ChosenInventory): string {
+  if (chosen.kind === "unchanged") {
+    return `inventory: unchanged -- it already lists the ${repositories(chosen.count)} you chose`;
+  }
+  const count = repositories(chosen.count);
+  if (chosen.replaced === "invalid") return `inventory: replaced one that failed its contract with the ${count} you chose`;
+  if (chosen.replaced === "differing") {
+    return (
+      `inventory: replaced ${chosen.previousCount} with the ${count} you chose -- ` +
+      `${chosen.added.length} added${listAddedPositions(chosen.addedPositions)}, ${chosen.removed.length} removed${listRemovedPositions(chosen.removedPositions, "replaced inventory")}`
+    );
+  }
+  return `inventory: wrote the ${count} you chose`;
+}