@event4u/agent-config 16.5.0 → 17.1.0

package/src/install/preflight.ts

@@ -21,6 +21,7 @@ import { dirname } from 'node:path';
 import type { PlanInputs } from './plan.js';
 import { buildInstallPlan } from './plan.js';
 import { computeConflicts } from './conflict.js';
+import type { ConflictEntry } from './types.js';
 import { detectToolPresence } from './detect.js';
 
 /** Stable identifiers for the four pre-flight probes. */
@@ -155,25 +156,56 @@ export function checkConflicts(inputs: PlanInputs): PreflightFinding[] {
         id: 'conflicts' as const,
         severity: 'warning' as const,
         path: c.path,
-        message:
-            c.ownership === 'recorded-modified'
-                ? `managed ${c.kind} file has been edited since we wrote it`
-                : `existing file conflicts with planned ${c.kind} content`,
+        message: conflictMessage(c),
         // A remedy here may only describe what an install actually does. Before
         // the owner ruling of 2026-09-21 the writer overwrote every deployed
         // file unconditionally, so the `recorded-modified` arm told the
         // operator to back their edit up. It now preserves that file and stages
         // the package content beside it, so the same sentence would be false in
         // the opposite direction — it would understate a protection that ships.
-        // The `unknown` arm is unchanged: nothing is recorded for that path, so
-        // the writer still writes over it.
-        remedy:
-            c.ownership === 'recorded-modified'
-                ? 'installing preserves your edit and stages package content as <path>.agent-config.new; --force replaces it instead'
-                : 'back up this file — installing writes the planned content over it',
+        // The `unknown` arm is NO LONGER one arm. A path the ownership ledger
+        // lists but holds no digest for is preserved too, so the back-up
+        // sentence would be false for it in the same direction the
+        // `recorded-modified` one was — it would tell the operator to save a
+        // file the installer is about to leave alone.
+        remedy: conflictRemedy(c),
     }));
 }
 
+/** What the operator is being told has happened to one conflicting file. */
+function conflictMessage(c: ConflictEntry): string {
+    if (c.ownership === 'recorded-modified') {
+        return `managed ${c.kind} file has been edited since we wrote it`;
+    }
+    if (c.migration) {
+        return `managed ${c.kind} file predates digest tracking — an edit and an older version look alike here`;
+    }
+    return `existing file conflicts with planned ${c.kind} content`;
+}
+
+/**
+ * What an install will actually do to it.
+ *
+ * A remedy here may only describe what an install actually does, which is why
+ * the migration arm exists rather than reusing either neighbour: the file is
+ * preserved like an edited one, but the reason is not an edit anyone proved.
+ */
+function conflictRemedy(c: ConflictEntry): string {
+    if (c.ownership === 'recorded-modified') {
+        return 'installing preserves your edit and stages package content as <path>.agent-config.new; --force replaces it instead';
+    }
+    if (c.migration) {
+        // MAY, not WILL, and the hedge is the accurate word rather than a
+        // soft one. The branch preserves only when the bytes differ from
+        // what the install would write, and that comparison needs the
+        // install-time tag, which this surface cannot apply — so a preflight
+        // that promised either outcome would be guessing at the one the
+        // writer settles.
+        return 'installing may preserve this file and stage package content as <path>.agent-config.new rather than overwriting it; the install run says which';
+    }
+    return 'back up this file — installing writes the planned content over it';
+}
+
 /** Probe 4 — host-detection sanity: report what the target tree looks like. */
 export function checkHostDetection(inputs: PlanInputs): PreflightFinding[] {
     const presence = detectToolPresence(inputs.root);

package/src/install/preserve.ts

@@ -77,6 +77,26 @@ export interface DeployWriteInputs {
      * whether the bytes on disk are ours.
      */
     readonly recordedSha256: string | null | undefined;
+    /**
+     * True when the user-scoped ownership ledger LISTS this path, whatever
+     * digest it carries — including none.
+     *
+     * Absent means false, so every caller that does not pass it keeps exactly
+     * the behaviour it had. Only the writer, which can read the ledger, sets
+     * it.
+     */
+    readonly ledgerListed?: boolean;
+    /**
+     * The SHA-256 of the bytes this run WOULD write to the target — the
+     * package file plus its install-time tag, not the raw source.
+     *
+     * Consulted only on the migration branch below, so a caller computes it
+     * only when {@link isLedgerMigration} says it is needed. `undefined` means
+     * the caller did not compute it and `null` means it could not be; on that
+     * branch both preserve, because the branch exists for the case where
+     * nothing can be proven.
+     */
+    readonly packagedSha256?: string | null;
     /**
      * The SHA-256 of the bytes on disk, computed immediately before the caller
      * mutates the file — not at plan time.
@@ -89,31 +109,110 @@ export interface DeployWriteInputs {
      * `null` when the file could not be read.
      */
     readonly onDiskSha256: string | null;
+    /**
+     * True when the install transaction log records this installer writing
+     * exactly the bytes now on disk to this path (`./loggedWrites.ts`).
+     * Absent means false. Decides only where {@link logProofApplies} says so.
+     */
+    readonly loggedWrite?: boolean;
+    /**
+     * True when the recorded digest is the one this installer STAGED beside the
+     * target as a sidecar, rather than bytes it wrote to the target itself.
+     *
+     * The ledger records a preserved target under the staged digest, so such a
+     * target reads `recorded-modified` without anyone having edited it. Only
+     * then may the log override the record: a recorded digest of bytes we DID
+     * write diverging from disk is a real edit — including a user restoring an
+     * older shipped version on purpose, which the log would also match.
+     */
+    readonly recordedIsStaged?: boolean;
     /** True when the run carries `--force`. */
     readonly force: boolean;
 }
 
+/**
+ * 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: Omit<DeployWriteInputs, 'packagedSha256'>): boolean {
+    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: Omit<DeployWriteInputs, 'packagedSha256' | 'loggedWrite'>): boolean {
+    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: DeployWriteInputs): DeployWriteDecision {
     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`. */
@@ -137,6 +236,25 @@ export function preservedFileMessage(target: string, sidecar: string): string {
     );
 }
 
+/**
+ * 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: string, sidecar: string): string {
+    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: number): string {
     const noun = count === 1 ? 'file' : 'files';

package/src/install/recordedOwnership.ts

@@ -40,6 +40,7 @@ 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, type EnvMap } from '../scripts/_lib/installed_tools.js';
 
 /**
@@ -62,20 +63,90 @@ export type RecordedHashes = ReadonlyMap<string, string | null>;
 /** The empty answer — "nothing is recorded", used whenever no manifest resolves. */
 export const NO_RECORDED_HASHES: RecordedHashes = new Map<string, string | null>();
 
+/**
+ * The state of one managed file, read from TWO recorded digests and the bytes
+ * on disk.
+ *
+ * One digest answers "did the bytes change since we wrote them". It cannot
+ * answer "did WE change what we would write", and every later decision needs
+ * both: an untouched file the package has since updated is `outdated`, not
+ * `clean`, and an edited file the package has since updated is the case where
+ * the user's work and a new version collide.
+ *
+ * - `clean`                    — on disk is what we wrote, and still what we ship.
+ * - `outdated`                 — on disk is what we wrote; we now ship something else.
+ * - `customized`               — edited since we wrote it; we still ship what we wrote.
+ * - `customized-and-outdated`  — edited, AND we now ship something else.
+ * - `retired-unmodified`       — we no longer ship it, and it is untouched.
+ * - `retired-modified`         — we no longer ship it, and it was edited.
+ * - `unknown`                  — no installed digest, or the bytes are unreadable.
+ */
+export type FileState =
+    | 'clean'
+    | 'outdated'
+    | 'customized'
+    | 'customized-and-outdated'
+    | 'retired-unmodified'
+    | 'retired-modified'
+    | 'unknown';
+
+/**
+ * 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: string | null | undefined,
+    packagedSha256: string | null | undefined,
+    onDiskSha256: string | null,
+): FileState {
+    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: FileState): RecordedOwnership {
+    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: string | null | undefined,
     onDiskSha256: string | null,
 ): RecordedOwnership {
-    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));
 }
 
 /**
@@ -147,3 +218,50 @@ function expanduser(p: string): string {
 export function recordedHashesForRoot(root: string, env?: EnvMap | null): RecordedHashes {
     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?: EnvMap | null): ReadonlySet<string> {
+    return global_deploy_inventory.recorded_absolute_files(
+        global_deploy_inventory.load_inventory(global_deploy_inventory.inventory_path(env)),
+        env?.['HOME'],
+    );
+}
+
+export function recordedHashesWithLedger(root: string, env?: EnvMap | null): RecordedHashes {
+    const out = new Map<string, string | null>(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;
+}

package/src/install/rule_scope.ts

@@ -32,7 +32,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';
 
 /**
@@ -72,9 +72,15 @@ export function ruleScopeFromSettings(
     settings: Record<string, unknown>,
     packageRoot?: string,
 ): RuleScope {
+    // 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 as Record<string, unknown>;
     // `rule_packs: auto` derives the active-pack set — the SAME set the
@@ -91,7 +97,18 @@ export function ruleScopeFromSettings(
                   _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']),
     };