@event4u/agent-config 16.5.0 → 17.1.0

package/dist/install/preserve.js

@@ -58,29 +58,96 @@ export const SIDECAR_SUFFIX = '.agent-config.new';
  * `2` is already argparse's usage-error code, so this is `3`.
  */
 export const EXIT_COMPLETED_WITH_CONFLICTS = 3;
+/**
+ * Does this target reach the migration branch at all?
+ *
+ * Cheap on purpose — it hashes nothing. The migration branch needs the digest
+ * of what the run WOULD write, and computing that means staging the package
+ * content into a temp file and tagging it. Asking this first means a normal
+ * install pays nothing: on a tree where every ledger-listed path carries a
+ * digest, this is false everywhere and no extra byte is written.
+ *
+ * The set it selects is narrow and worth stating exactly. A path is
+ * ledger-listed but digest-less only when it was deployed globally by an
+ * install that predates the ledger (inventory schema 1, which recorded paths
+ * and no digests) AND no project manifest records a digest for it either —
+ * which means that install ran from a directory carrying no project settings.
+ * That is precisely the population whose global edits this roadmap found being
+ * overwritten silently.
+ *
+ * `onDiskSha256 === null` is excluded deliberately: with bytes that cannot be
+ * read, equality is undecidable in both directions, so the pre-ledger
+ * behaviour stands rather than being changed on a case nobody reasoned about.
+ */
+export function isLedgerMigration(inputs) {
+    if (!inputs.exists || inputs.force || inputs.loggedWrite === true)
+        return false;
+    if (inputs.ledgerListed !== true)
+        return false;
+    if (inputs.onDiskSha256 === null)
+        return false;
+    return classifyOwnership(inputs.recordedSha256, inputs.onDiskSha256) === 'unknown';
+}
+/**
+ * May the transaction-log proof decide this target? Only where the verdict
+ * would otherwise be a preservation the record cannot justify: a ledger-listed
+ * file with no digest (the migration branch), or a `recorded-modified` file
+ * whose recorded digest is a staged one. Everywhere else the log is not read —
+ * the ledger alone already decides, and a genuine edit must stay preserved.
+ */
+export function logProofApplies(inputs) {
+    if (!inputs.exists || inputs.force || inputs.onDiskSha256 === null)
+        return false;
+    const ownership = classifyOwnership(inputs.recordedSha256, inputs.onDiskSha256);
+    if (ownership === 'recorded-modified')
+        return inputs.recordedIsStaged === true;
+    // `loggedWrite` is cleared because `isLedgerMigration` excludes a proven
+    // target, and this asks whether the target is a candidate BEFORE the proof.
+    return ownership === 'unknown' && isLedgerMigration({ ...inputs, loggedWrite: false });
+}
 /**
  * Decide whether the writer may replace one managed file.
  *
- * A target that does not exist is written. A forced run writes. Otherwise the
- * recorded-ownership verdict decides: `recorded-modified` preserves, and both
- * `recorded-unchanged` and `unknown` write.
- *
- * The `unknown` arm is the one worth stating out loud, because it is what
- * keeps this change from being a regression. No recorded digest means no
- * divergence to measure — a tree with no manifest, a global anchor that holds
- * none, or a bridge entry recorded without a hash. Preserving there would
- * stage a sidecar beside every pre-existing file on a first install, which is
- * not protection, it is noise. The ruling covers a file this tree can show it
- * wrote and can show has changed since; everything else keeps the behavior it
- * had, and `recordedOwnership` already documents that floor.
+ * A target that does not exist is written. A forced run writes. A target whose
+ * bytes the transaction log records this installer writing there is written
+ * where {@link logProofApplies} — there is no edit to lose. Otherwise the
+ * recorded-ownership verdict decides:
+ * `recorded-modified` preserves, and `recorded-unchanged` writes.
+ *
+ * The `unknown` arm is the one worth stating out loud. No recorded digest
+ * means no divergence to measure — a tree with no manifest, a global anchor
+ * that holds none, or a bridge entry recorded without a hash. Preserving every
+ * such file would stage a sidecar beside every pre-existing file on a first
+ * install, which is not protection, it is noise, and that is still the answer
+ * for a file this tree has no record of.
+ *
+ * THE MIGRATION BRANCH, and why `unknown` is not one thing. A path the
+ * ledger LISTS is not a file this tree has no record of: the listing is this
+ * package's own record that it deployed that path. The noise argument above
+ * was made about genuinely unrecorded files and does not reach it. For that
+ * narrow set — see {@link isLedgerMigration} — the only available proof is
+ * equality with what the run would write: equal means writing cannot destroy
+ * an edit, whatever the history; unequal proves nothing, because an edited
+ * file and an untouched older version are indistinguishable without a
+ * recorded digest. Overwriting on "proves nothing" accepts irreversible loss
+ * knowingly, so the unequal case preserves.
  */
 export function decideDeployWrite(inputs) {
     if (!inputs.exists)
         return 'write';
     if (inputs.force)
         return 'write';
+    if (inputs.loggedWrite === true && logProofApplies(inputs))
+        return 'write';
     const ownership = classifyOwnership(inputs.recordedSha256, inputs.onDiskSha256);
-    return ownership === 'recorded-modified' ? 'preserve' : 'write';
+    if (ownership === 'recorded-modified')
+        return 'preserve';
+    if (ownership === 'unknown' && isLedgerMigration(inputs)) {
+        return inputs.packagedSha256 != null && inputs.packagedSha256 === inputs.onDiskSha256
+            ? 'write'
+            : 'preserve';
+    }
+    return 'write';
 }
 /** Path of the sidecar staged beside `target`. */
 export function sidecarPathFor(target) {
@@ -99,6 +166,22 @@ export function preservedFileMessage(target, sidecar) {
         'the active installation is not current. Review and merge it, or rerun with ' +
         '--force to replace the managed file.');
 }
+/**
+ * Per-file report line for a target preserved on the migration branch.
+ *
+ * Distinct wording because the cause is distinct and the ordinary message
+ * would mislead. "Preserved user-modified" asserts an edit; here the run
+ * cannot tell an edit from an older version, and saying otherwise would be
+ * the kind of unproven claim the preservation path exists to avoid. What the
+ * reader needs is why it happened and that it is a one-off.
+ */
+export function migrationPreservedMessage(target, sidecar) {
+    return (`Preserved ${target} without being able to classify it: this package deployed it before ` +
+        'it began recording digests, so an edit and an older version look the same here. ' +
+        `Package content was written to ${sidecar}; the active installation is not current. ` +
+        'Review and merge it, or rerun with --force to replace the managed file. ' +
+        'Once resolved, this file is classified normally on every later install.');
+}
 /** End-of-run summary naming the conflict count and what it means. */
 export function conflictSummaryMessage(count) {
     const noun = count === 1 ? 'file' : 'files';

package/dist/install/recordedOwnership.js

@@ -37,22 +37,63 @@ import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import * as YAML from 'yaml';
+import * as global_deploy_inventory from '../scripts/_lib/global_deploy_inventory.js';
 import { manifest_path } from '../scripts/_lib/installed_tools.js';
 /** The empty answer — "nothing is recorded", used whenever no manifest resolves. */
 export const NO_RECORDED_HASHES = new Map();
+/**
+ * Classify one file from the digest we INSTALLED, the digest we would install
+ * NOW, and the digest on disk.
+ *
+ * `packagedSha256`: a string is the current package content; `null` means the
+ * package no longer ships the file (retired); `undefined` means the caller does
+ * not know — the comparison then degrades to the installed digest alone, which
+ * is exactly the old three-state answer and never yields an `-outdated` or
+ * `retired-` state. Bytes on disk equal to what we would ship are `clean`
+ * whatever was recorded: there is nothing to preserve and nothing to update.
+ */
+export function classifyFileState(installedSha256, packagedSha256, onDiskSha256) {
+    if (installedSha256 === undefined || installedSha256 === null)
+        return 'unknown';
+    if (onDiskSha256 === null)
+        return 'unknown';
+    const untouched = onDiskSha256 === installedSha256;
+    if (packagedSha256 === null)
+        return untouched ? 'retired-unmodified' : 'retired-modified';
+    if (packagedSha256 !== undefined && onDiskSha256 === packagedSha256)
+        return 'clean';
+    const shipsWhatWeWrote = packagedSha256 === undefined || packagedSha256 === installedSha256;
+    if (untouched)
+        return shipsWhatWeWrote ? 'clean' : 'outdated';
+    return shipsWhatWeWrote ? 'customized' : 'customized-and-outdated';
+}
+/** Collapse a {@link FileState} to the three-state ownership the write decision reads. */
+export function ownershipOfState(state) {
+    switch (state) {
+        case 'clean':
+        case 'outdated':
+        case 'retired-unmodified':
+            return 'recorded-unchanged';
+        case 'customized':
+        case 'customized-and-outdated':
+        case 'retired-modified':
+            return 'recorded-modified';
+        case 'unknown':
+            return 'unknown';
+    }
+}
 /**
  * Classify one target from the recorded digest and the on-disk digest.
  *
  * Pure — the caller supplies both digests. `undefined` for `recordedSha256`
  * means the path is not recorded at all; `null` means recorded without a
  * digest. Both answer `unknown`, because neither supports a comparison.
+ *
+ * The three-state view of {@link classifyFileState} with the packaged digest
+ * unknown — one classifier, so the two answers cannot drift apart.
  */
 export function classifyOwnership(recordedSha256, onDiskSha256) {
-    if (recordedSha256 === undefined || recordedSha256 === null)
-        return 'unknown';
-    if (onDiskSha256 === null)
-        return 'unknown';
-    return recordedSha256 === onDiskSha256 ? 'recorded-unchanged' : 'recorded-modified';
+    return ownershipOfState(classifyFileState(recordedSha256, undefined, onDiskSha256));
 }
 /**
  * Read `tools[].files[]` out of an installed-tools manifest into a
@@ -129,4 +170,46 @@ function expanduser(p) {
 export function recordedHashesForRoot(root, env) {
     return readRecordedHashes(manifest_path(root, env), root);
 }
+/**
+ * {@link recordedHashesForRoot} with the USER-scoped ownership ledger laid over
+ * it.
+ *
+ * The project manifest is written only from a project that carries settings,
+ * so on its own it decided a globally installed file's fate by the working
+ * directory of the install. The ledger (the `digests` of the global deploy
+ * inventory) is written on every global deploy, wherever it ran from, and it
+ * WINS where both record a path: it is rewritten by every global install, while
+ * a project's manifest is rewritten only by installs run from that project and
+ * so goes stale the moment a second project installs. A path the ledger does
+ * not record keeps the manifest's answer, so a project-scope target reads
+ * exactly as before.
+ *
+ * The one table the preview (`computeConflicts`) and the writer
+ * (`conflictTracker`) both read, so the two cannot answer differently.
+ */
+/**
+ * Every absolute path the user-scoped ledger LISTS, with or without a digest.
+ *
+ * {@link recordedHashesWithLedger} answers "what digest did we record"; this
+ * answers the strictly weaker "did we deploy here at all", which is the
+ * question an inventory written before digests existed can still answer. The
+ * write decision needs both: a listed path with no digest is not a file this
+ * tree has no record of, and treating the two alike is what let a pre-ledger
+ * global edit be overwritten silently.
+ *
+ * Here rather than in the tracker so the inventory stays read by the one
+ * module that already reads it, under the same `AGENT_CONFIG_DEPLOY_INVENTORY`
+ * override.
+ */
+export function ledgerListedPaths(env) {
+    return global_deploy_inventory.recorded_absolute_files(global_deploy_inventory.load_inventory(global_deploy_inventory.inventory_path(env)), env?.['HOME']);
+}
+export function recordedHashesWithLedger(root, env) {
+    const out = new Map(recordedHashesForRoot(root, env));
+    const ledger = global_deploy_inventory.load_inventory(global_deploy_inventory.inventory_path(env));
+    for (const [target, sha] of global_deploy_inventory.recorded_absolute_digests(ledger, env?.['HOME'])) {
+        out.set(target, sha);
+    }
+    return out;
+}
 //# sourceMappingURL=recordedOwnership.js.map

package/dist/install/rule_scope.js

@@ -30,7 +30,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { resolve_rule_pack_scope } from '../scripts/_lib/scoped_projection.js';
+import { consumerRuleWorkspaces, resolve_rule_pack_scope } from '../scripts/_lib/scoped_projection.js';
 import { rule_in_scope } from './ruleInScope.js';
 /**
  * Rules excluded from EVERY consumer install path regardless of scope —
@@ -51,9 +51,15 @@ function _list(value) {
  * `_read_projection_list` — absent / empty = legacy-all).
  */
 export function ruleScopeFromSettings(settings, packageRoot) {
+    // The WORKSPACE axis is derived from the pack vocabulary since ADR-293 step
+    // 4.6, so it no longer depends on a `projection` block existing at all — a
+    // rule is not a setting, and a settings file that happens to omit a section
+    // cannot switch one off. The pack and role axes are still read, so a
+    // missing block leaves them inactive exactly as before.
+    const derivedWorkspaces = packageRoot === undefined ? null : consumerRuleWorkspaces(packageRoot);
     const proj = settings['projection'];
     if (typeof proj !== 'object' || proj === null || Array.isArray(proj)) {
-        return LEGACY_ALL;
+        return { ...LEGACY_ALL, workspaces: derivedWorkspaces };
     }
     const p = proj;
     // `rule_packs: auto` derives the active-pack set — the SAME set the
@@ -65,7 +71,18 @@ export function ruleScopeFromSettings(settings, packageRoot) {
         ? _list(p['rule_packs'])
         : resolve_rule_pack_scope(p['rule_packs'], packageRoot, _list(_runtimeActivePacks(settings)) ?? []);
     return {
-        workspaces: _list(p['rule_workspaces']),
+        // DERIVED since ADR-293 step 4.6, not read. `projection.rule_workspaces`
+        // carried this list as a settings default — the nine consumer workspace
+        // ids, re-typed into the template and needing a re-type whenever a pack
+        // arrived with a new one. What it encoded is a RULE: maintainer-only
+        // rules never project to a consumer. `consumerRuleWorkspaces` derives
+        // exactly that from the pack vocabulary, and the derived set equals the
+        // old default (asserted in `consumer_rule_workspaces.test.ts`).
+        // Without a package root there is no vocabulary to read, so the axis is
+        // INACTIVE rather than empty — the same degradation `rule_packs` makes
+        // above, and the same reason: a package that cannot read its own pack
+        // list must ship more than it should, never less.
+        workspaces: derivedWorkspaces,
         packs,
         roles: _list(p['rule_roles']),
     };