Skip to main content

spec_driven_docs/services/
upgrader.rs

1//! Binary-driven instance upgrade.
2//!
3//! The newer binary carries the newer payload, so an upgrade is mechanical:
4//! refuse atomically while any managed file is locally edited, reinstall
5//! from the embedded payload, prune what the new version stopped managing —
6//! inside the vendored directory only, and never through a symlink — and
7//! report the rule-ID diff the operator reconciles by hand. Copier's model;
8//! what changed between versions is the changelog's business.
9
10use camino::{Utf8Path, Utf8PathBuf};
11use serde::Serialize;
12
13use crate::adapters::fs::sha256_file;
14use crate::domain::manifest::{LegacyManifest, MANIFEST_PATH, Manifest, ManifestParseError};
15use crate::domain::ownership::Sha256;
16use crate::domain::profile::ProfileId;
17use crate::domain::version::CanonVersion;
18use crate::error::AppError;
19use crate::services::installer::{InitOptions, init, init_holding};
20
21/// What an upgrade was asked to do.
22#[derive(Debug, Clone)]
23pub struct UpgradeOptions {
24    /// The absolute target instance.
25    pub target: Utf8PathBuf,
26    /// Report what would change and change nothing.
27    pub dry_run: bool,
28    /// The choices a stage recorded, where the landing takes them.
29    pub staged: Option<crate::stage::StagedChoices>,
30    /// The conflicts the operator named for replacement, as the record
31    /// names each destination.
32    pub replace: Vec<String>,
33}
34
35/// What kind of conflict one destination is.
36#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
37#[serde(rename_all = "kebab-case")]
38pub enum ConflictKind {
39    /// A managed file whose bytes are not the recorded ones.
40    EditedManagedFile,
41    /// A managed file the record names and the target lacks.
42    MissingManagedFile,
43    /// A managed region whose bytes are not the recorded ones.
44    EditedManagedBlock,
45    /// The file a recorded managed region lives in is gone.
46    MissingIntegrationHost,
47    /// A destination the candidate lands that holds bytes no record
48    /// vouches for.
49    Unattributed,
50    /// A skill package folder the candidate lands into whose files no
51    /// record attributes. It is never replaced, so no name resolves it.
52    UnattributedSkillPackage,
53}
54
55/// One destination the upgrade cannot overwrite unasked.
56#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
57pub struct Conflict {
58    /// The destination, relative to the target.
59    pub path: String,
60    /// What kind of conflict it is.
61    pub kind: ConflictKind,
62}
63
64impl Conflict {
65    /// The line the text report prints.
66    fn line(&self) -> String {
67        let what = match self.kind {
68            ConflictKind::EditedManagedFile => "locally edited managed file",
69            ConflictKind::MissingManagedFile => "missing managed file",
70            ConflictKind::EditedManagedBlock => "locally edited managed block",
71            ConflictKind::MissingIntegrationHost => "missing integration host",
72            ConflictKind::Unattributed => "destination holds bytes no record vouches for",
73            ConflictKind::UnattributedSkillPackage => {
74                return format!(
75                    "CONFLICT {}",
76                    crate::landing::apply::refused_package_line(&self.path)
77                );
78            }
79        };
80        format!("CONFLICT {what}: {}", self.path)
81    }
82}
83
84/// One named conflict, and where its bytes were saved before the landing.
85#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
86pub struct Replaced {
87    /// The destination, relative to the target.
88    pub path: String,
89    /// Where its bytes are kept, or nothing where the target held none.
90    pub saved_to: Option<Utf8PathBuf>,
91}
92
93/// One citation of a rule ID this binary no longer defines.
94#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
95pub struct Citation {
96    /// The citing file, relative to the target.
97    pub path: Utf8PathBuf,
98    /// The one-based line the citation sits on.
99    pub line: usize,
100    /// The rule ID cited.
101    pub id: String,
102}
103
104/// What an upgrade did.
105#[derive(Debug, Default)]
106pub struct UpgradeOutcome {
107    /// Every line to print, in order.
108    pub lines: Vec<String>,
109    /// How many lines are conflicts or failures.
110    pub failures: usize,
111    /// The release the record names, where one was read.
112    pub from: Option<CanonVersion>,
113    /// Every conflict the target holds, named or not.
114    pub conflicts: Vec<Conflict>,
115    /// Every named conflict and where its bytes went.
116    pub replaced: Vec<Replaced>,
117    /// Every citation of a rule ID this binary no longer defines.
118    pub retired_citations: Vec<Citation>,
119}
120
121struct Installed {
122    version: CanonVersion,
123    profile: ProfileId,
124    docs_root: String,
125    managed: Vec<(Utf8PathBuf, Sha256)>,
126    integration: Vec<(Utf8PathBuf, Sha256)>,
127    /// Whether the record is already at this binary's schema.
128    ///
129    /// The two versions move independently, so an instance can carry this
130    /// binary's canon version and an older schema. Without this the "already
131    /// at" shortcut would return before migrating, while every other verb
132    /// refuses the record and sends the operator back here.
133    schema_current: bool,
134}
135
136/// The marker pair a host file's managed region uses.
137fn markers_for(path: &str) -> (&'static str, &'static str) {
138    use crate::domain::marker::{AGENTS_BEGIN, AGENTS_END, BEGIN, END};
139    if path == crate::domain::paths::HOOKS_CONFIG_PATH {
140        (BEGIN, END)
141    } else {
142        (AGENTS_BEGIN, AGENTS_END)
143    }
144}
145
146fn read_installed(target: &Utf8Path) -> Result<Installed, AppError> {
147    let path = target.join(MANIFEST_PATH);
148    if !path.is_file() {
149        return Err(AppError::ManifestMissing(path));
150    }
151    let text = std::fs::read_to_string(&path)?;
152    match Manifest::parse(&text) {
153        Ok(manifest) => Ok(Installed {
154            version: manifest.canon_version,
155            profile: manifest.profile,
156            docs_root: manifest.docs_root.as_str().to_string(),
157            managed: manifest
158                .managed_files
159                .into_iter()
160                .map(|entry| (entry.destination, entry.sha256))
161                .collect(),
162            integration: manifest
163                .integration_blocks
164                .into_iter()
165                .map(|block| (block.path, block.marker_hash))
166                .collect(),
167            schema_current: true,
168        }),
169        Err(ManifestParseError::Older(_)) => {
170            let legacy: LegacyManifest = serde_json::from_str(&text)
171                .map_err(|e| AppError::ManifestInvalid(e.to_string()))?;
172            Ok(Installed {
173                version: legacy.canon_version,
174                profile: legacy.profile,
175                docs_root: legacy.docs_root.as_str().to_string(),
176                managed: legacy
177                    .managed_files
178                    .into_iter()
179                    .map(|entry| (entry.destination, entry.sha256))
180                    .collect(),
181                integration: legacy
182                    .integration_blocks
183                    .into_iter()
184                    .map(|block| (block.path, block.marker_hash))
185                    .collect(),
186                schema_current: false,
187            })
188        }
189        Err(error) => Err(AppError::ManifestInvalid(error.to_string())),
190    }
191}
192
193/// Refuse an answer on a path where no plan offers a decision.
194///
195/// A target with nothing to do and one whose managed files were edited
196/// both end before a plan exists. An answer given on either is an answer
197/// to a question nobody asked, and letting it pass silently would make
198/// typing look like consent on the one path where nothing checked it.
199/// A downgrade refuses on its own terms before this can matter.
200///
201/// # Errors
202///
203/// [`AppError::Usage`] naming the decision nothing offered.
204/// Every managed file and region the target no longer holds as recorded.
205///
206/// A reinstall replaces a managed file and re-splices a managed region, so
207/// an edit to either would be lost. An edit outside the markers is the
208/// project's own and survives, which is why the region is compared by its
209/// own hash rather than the host file's.
210///
211/// # Errors
212///
213/// Any I/O error reading a destination.
214fn conflicts_at(target: &Utf8Path, installed: &Installed) -> Result<Vec<Conflict>, AppError> {
215    let mut conflicts = Vec::new();
216    let mut push = |path: &Utf8Path, kind| {
217        conflicts.push(Conflict {
218            path: path.to_string(),
219            kind,
220        });
221    };
222    for (destination, recorded) in &installed.managed {
223        let file = target.join(destination);
224        if !file.is_file() {
225            push(destination, ConflictKind::MissingManagedFile);
226            continue;
227        }
228        if sha256_file(&file)? != *recorded {
229            push(destination, ConflictKind::EditedManagedFile);
230        }
231    }
232    for (path, recorded) in &installed.integration {
233        let full = target.join(path);
234        if !full.is_file() {
235            push(path, ConflictKind::MissingIntegrationHost);
236            continue;
237        }
238        let (begin, end) = markers_for(path.as_str());
239        let host = std::fs::read_to_string(&full)?;
240        match crate::domain::marker::block_hash_with(&host, begin, end) {
241            Some(present) if present == *recorded => {}
242            _ => push(path, ConflictKind::EditedManagedBlock),
243        }
244    }
245    Ok(conflicts)
246}
247
248/// Every destination the candidate lands that the landing would refuse,
249/// beyond what the record already names.
250fn unattributed(
251    target: &Utf8Path,
252    candidate: &crate::candidate::Candidate,
253    known: &[Conflict],
254) -> Vec<Conflict> {
255    let recorded = crate::services::installer::recorded(target);
256    let packages = crate::landing::apply::refused_skill_packages(target, &recorded);
257    let mut found: Vec<Conflict> = packages
258        .iter()
259        .map(|folder| Conflict {
260            path: folder.clone(),
261            kind: ConflictKind::UnattributedSkillPackage,
262        })
263        .collect();
264    for destination in &candidate.destinations {
265        if packages
266            .iter()
267            .any(|folder| destination.path.as_str().starts_with(folder.as_str()))
268        {
269            continue;
270        }
271        let Ok(held) = std::fs::read(target.join(&destination.path)) else {
272            continue;
273        };
274        if held == destination.bytes
275            || crate::landing::apply::vouches(
276                &recorded,
277                &destination.path,
278                destination.ownership,
279                &held,
280            )
281            || known
282                .iter()
283                .any(|conflict| conflict.path == destination.path.as_str())
284        {
285            continue;
286        }
287        found.push(Conflict {
288            path: destination.path.to_string(),
289            kind: ConflictKind::Unattributed,
290        });
291    }
292    found
293}
294
295/// The options a reinstall carries.
296///
297/// No flag: the reinstall carries the recorded declarations forward, and
298/// the project's own declaration file is adopted, so the reinstall reads
299/// it rather than replacing it.
300fn reinstall_options(
301    target: &Utf8Path,
302    profile: ProfileId,
303    options: &UpgradeOptions,
304) -> InitOptions {
305    let staged = options.staged.as_ref();
306    InitOptions {
307        target: target.to_path_buf(),
308        profile,
309        apply: false,
310        dry_run: true,
311        docs_scratch: staged.map(|choices| choices.docs_scratch.clone()),
312        reserve: staged
313            .map(|choices| choices.reserve.clone())
314            .unwrap_or_default(),
315        writing_style: staged.map(|choices| choices.writing_style.clone()),
316        acquisition: staged.and_then(|choices| choices.acquisition.clone()),
317        replace: options.replace.clone(),
318    }
319}
320
321/// Report what the landing took back.
322///
323/// The removals are the landing's own, taken only where the record
324/// vouched for the bytes it removed. This only says what happened.
325fn report_removals(removed: &[String], outcome: &mut UpgradeOutcome) {
326    for raw in removed {
327        outcome
328            .lines
329            .push(format!("removed managed file no longer owned: {raw}"));
330    }
331}
332
333/// Upgrade an installed instance to this binary's version.
334///
335/// # Errors
336///
337/// [`AppError::Violations`] when conflicts block the upgrade or removals
338/// remain unfinished, [`AppError::Refused`] when the binary is older than
339/// the instance or the reinstall refuses, and manifest errors when the
340/// record cannot be read.
341pub fn upgrade(options: &UpgradeOptions) -> Result<UpgradeOutcome, AppError> {
342    if !options.target.is_absolute() {
343        return Err(AppError::Usage("target must be absolute".to_string()));
344    }
345    if !options.target.is_dir() {
346        return Err(AppError::Usage(format!(
347            "unresolved target: {}",
348            options.target
349        )));
350    }
351    let target = Utf8PathBuf::from_path_buf(std::fs::canonicalize(&options.target)?)
352        .map_err(|p| AppError::Usage(format!("target is not UTF-8: {}", p.display())))?;
353
354    // An apply holds the target for the whole run, the observation below
355    // included. Without it, a second run could read the tree another
356    // landing is halfway through and report that as drift rather than
357    // naming the holder.
358    let held = if options.dry_run {
359        None
360    } else {
361        Some(crate::landing::lock::hold(&target)?)
362    };
363
364    let installed = read_installed(&target)?;
365    // The version landed is the version running. The operator chose which
366    // binary to install, and that binary projects only itself.
367    let new = CanonVersion::current();
368    let old = installed.version;
369    let mut outcome = UpgradeOutcome::default();
370
371    if old > new {
372        return Err(AppError::Refused(format!(
373            "sdd {new} is older than the installed canon {old}; upgrade sdd"
374        )));
375    }
376
377    if let Some(staged) = options.staged.as_ref()
378        && staged.profile != installed.profile
379    {
380        return Err(AppError::Refused(format!(
381            "the stage projects the {} profile and {target} records {}; moving a profile is a migration to ask for deliberately",
382            staged.profile, installed.profile
383        )));
384    }
385    outcome.from = Some(old);
386    let reinstall = reinstall_options(&target, installed.profile, options);
387    outcome.retired_citations = retired_citations(&target, &installed);
388
389    // The conflict scan comes before the version shortcut. A managed file
390    // edited in a current instance is exactly the drift this verb serves,
391    // and a shortcut that reported success first would leave the one route
392    // to it unable to do its job.
393    let conflicts = scan(&target, &installed, &reinstall, &options.replace)?;
394    outcome.conflicts.clone_from(&conflicts);
395    let unnamed: Vec<&Conflict> = conflicts
396        .iter()
397        .filter(|conflict| !options.replace.contains(&conflict.path))
398        .collect();
399    if !unnamed.is_empty() {
400        outcome.failures += unnamed.len();
401        outcome
402            .lines
403            .extend(unnamed.iter().map(|conflict| conflict.line()));
404        report_citations(&mut outcome);
405        return Ok(outcome);
406    }
407
408    if old == new
409        && installed.schema_current
410        && options.replace.is_empty()
411        && options.staged.is_none()
412    {
413        outcome.lines.push(format!("OK already at {new}"));
414        report_citations(&mut outcome);
415        return Ok(outcome);
416    }
417
418    let save_root = save_root(&target, &options.replace, !options.dry_run)?;
419    if options.dry_run {
420        preview(
421            &target,
422            options,
423            &reinstall,
424            save_root.as_deref(),
425            &mut outcome,
426        )?;
427        report_citations(&mut outcome);
428        return Ok(outcome);
429    }
430
431    // Every named conflict's bytes are kept before the first write, so the
432    // answer "discard" and the answer "keep" lose nothing either way.
433    keep_named(
434        &target,
435        &options.replace,
436        save_root.as_deref(),
437        &mut outcome,
438    )?;
439
440    let reinstalled = init_holding(
441        held,
442        &InitOptions {
443            apply: true,
444            dry_run: false,
445            ..reinstall
446        },
447        // The upgrade already classified the target; the reinstall is its
448        // own act rather than a second landing decision.
449        crate::landing::classify::Intent::Reconcile,
450    )
451    .map_err(|error| {
452        AppError::Refused(format!(
453            "upgrade aborted during reinstall from {old} to {new}: {error}"
454        ))
455    })?;
456    // The reinstall's destination list is noise here, and its notes are
457    // not: a seed that did not land because the project already holds the
458    // destination is something the operator must hear about once.
459    let removed = reinstalled.removed.clone();
460    outcome.lines.extend(
461        reinstalled
462            .lines
463            .into_iter()
464            .filter(|line| line.starts_with("note:")),
465    );
466
467    finish(&target, &installed, &removed, old, new, &mut outcome);
468    Ok(outcome)
469}
470
471/// Every conflict the target holds, and a refusal for a name that is none.
472///
473/// The record's own conflicts come first, then every destination the
474/// candidate lands that holds bytes no record vouches for, because the
475/// landing would refuse those too.
476fn scan(
477    target: &Utf8Path,
478    installed: &Installed,
479    reinstall: &InitOptions,
480    named: &[String],
481) -> Result<Vec<Conflict>, AppError> {
482    let (conflicts, candidate) = conflicts_with_candidate(target, installed, reinstall)?;
483    // A name is an answer to a question the scan asked. One that names no
484    // conflict answers nothing, and taking it would make typing look like
485    // consent to overwrite a file nobody looked at. One the landing would
486    // refuse resolves nothing either, so it is refused here, before a copy
487    // is saved, rather than by the landing after.
488    for name in named {
489        let Some(conflict) = conflicts.iter().find(|conflict| &conflict.path == name) else {
490            return Err(AppError::Usage(format!(
491                "--replace {name} names no conflict; the conflicts are the destinations this run lists"
492            )));
493        };
494        if conflict.kind == ConflictKind::UnattributedSkillPackage {
495            return Err(AppError::Refused(format!(
496                "--replace {name} names a skill package folder, which is never replaced; move it aside, then run this again"
497            )));
498        }
499        if let Some((component, kind)) =
500            crate::landing::apply::refuses_named(target, &candidate, name)
501        {
502            return Err(AppError::Refused(format!(
503                "--replace {name} names a destination the landing cannot write: {component} {kind}; move it aside, then run this again"
504            )));
505        }
506    }
507    Ok(conflicts)
508}
509
510/// Every conflict the target holds, with the candidate that judged them.
511fn conflicts_with_candidate(
512    target: &Utf8Path,
513    installed: &Installed,
514    reinstall: &InitOptions,
515) -> Result<(Vec<Conflict>, crate::candidate::Candidate), AppError> {
516    let mut conflicts = conflicts_at(target, installed)?;
517    let candidate =
518        crate::services::installer::candidate_for(target, reinstall).map_err(|error| {
519            AppError::Refused(format!(
520                "upgrade could not render the candidate for {target}: {error}"
521            ))
522        })?;
523    let unattributed = unattributed(target, &candidate, &conflicts);
524    conflicts.extend(unattributed);
525    Ok((conflicts, candidate))
526}
527
528/// The destinations `sdd upgrade --replace` accepts after the stage that
529/// recorded `staged`, by the check that verb applies to each name.
530///
531/// Empty where no instance is recorded, because `sdd init` takes no name,
532/// and wherever the upgrade refuses before it scans: the front gate that
533/// classifies the target, an instance newer than this binary, or a stage
534/// of another profile.
535///
536/// # Errors
537///
538/// Whatever rendering the candidate refuses.
539pub(crate) fn replaceable(staged: &crate::stage::StagedChoices) -> Result<Vec<String>, AppError> {
540    let target = &staged.target;
541    if crate::commands::front::serves(crate::landing::classify::Intent::Upgrade, target).is_err() {
542        return Ok(Vec::new());
543    }
544    let Ok(installed) = read_installed(target) else {
545        return Ok(Vec::new());
546    };
547    if installed.version > CanonVersion::current() || staged.profile != installed.profile {
548        return Ok(Vec::new());
549    }
550    let options = UpgradeOptions {
551        target: target.clone(),
552        dry_run: true,
553        staged: Some(staged.clone()),
554        replace: Vec::new(),
555    };
556    let reinstall = reinstall_options(target, installed.profile, &options);
557    let (conflicts, candidate) = conflicts_with_candidate(target, &installed, &reinstall)?;
558    Ok(conflicts
559        .into_iter()
560        .filter(|conflict| {
561            conflict.kind != ConflictKind::UnattributedSkillPackage
562                && crate::landing::apply::refuses_named(target, &candidate, &conflict.path)
563                    .is_none()
564        })
565        .map(|conflict| conflict.path)
566        .collect())
567}
568
569/// What a dry run reports: the move, each named conflict and where its
570/// bytes would go, and the notes the landing would print.
571fn preview(
572    target: &Utf8Path,
573    options: &UpgradeOptions,
574    reinstall: &InitOptions,
575    save_root: Option<&Utf8Path>,
576    outcome: &mut UpgradeOutcome,
577) -> Result<(), AppError> {
578    let new = CanonVersion::current();
579    let old = outcome.from.unwrap_or(new);
580    // At the same canon version the work is the record's schema alone, or
581    // the repair of what the operator named, so saying "upgrade X to X"
582    // would describe nothing.
583    if old != new {
584        outcome
585            .lines
586            .push(format!("DRY RUN upgrade {old} to {new}"));
587    } else if options.replace.is_empty() {
588        outcome
589            .lines
590            .push(format!("DRY RUN migrate the record of {new}"));
591    } else {
592        outcome.lines.push(format!("DRY RUN repair {new}"));
593    }
594    for named in &options.replace {
595        let saved_to = target
596            .join(named)
597            .is_file()
598            .then(|| save_root.map(|root| root.join(named)))
599            .flatten();
600        outcome.lines.push(saved_to.as_ref().map_or_else(
601            || format!("DRY RUN write {named}, which the target lacks"),
602            |saved| format!("DRY RUN save {named} to {saved}, then replace it"),
603        ));
604        outcome.replaced.push(Replaced {
605            path: named.clone(),
606            saved_to,
607        });
608    }
609    // A seed the landing will not write, and a file it cannot account for,
610    // are what a dry run exists to show.
611    let preview =
612        init(reinstall, crate::landing::classify::Intent::Reconcile).map_err(|error| {
613            AppError::Refused(format!(
614                "upgrade could not be previewed from {old} to {new}: {error}"
615            ))
616        })?;
617    outcome.lines.extend(
618        preview
619            .lines
620            .into_iter()
621            .filter(|line| line.starts_with("note:")),
622    );
623    Ok(())
624}
625
626/// Print every retired citation, one line each.
627fn report_citations(outcome: &mut UpgradeOutcome) {
628    for citation in &outcome.retired_citations {
629        outcome.lines.push(format!(
630            "retired rule ID cited: {}:{} `{}`; re-point it to the rule the changelog names",
631            citation.path, citation.line, citation.id
632        ));
633    }
634}
635
636/// Where the bytes of a replaced destination are kept.
637///
638/// Under the docs scratch the instance declares, or that its variable
639/// names, in `replaced/`. Where neither names one, under this tool's state
640/// root, in a directory of this run's own. Never inside a stage, so
641/// cleaning a stage never deletes a saved copy.
642///
643/// SATISFIES staging:a-replacement-keeps-the-bytes-it-replaces
644///
645/// A run that writes claims its state-root directory exclusively, so two
646/// runs in one second never share one; a preview only names where it would.
647fn save_root(
648    target: &Utf8Path,
649    named: &[String],
650    claim: bool,
651) -> Result<Option<Utf8PathBuf>, AppError> {
652    if named.is_empty() {
653        return Ok(None);
654    }
655    let env = crate::domain::paths::UserEnv::from_process();
656    let recorded = crate::services::installer::recorded_field(target, "docs_scratch")
657        .and_then(|value| value.as_str().map(Utf8PathBuf::from))
658        .filter(|path| !path.as_str().is_empty());
659    let scratch = env.docs_scratch.clone().map(Utf8PathBuf::from).or(recorded);
660    if let Some(scratch) = scratch {
661        return Ok(Some(target.join(scratch).join("replaced")));
662    }
663    let Some(state) = env.state_root() else {
664        return Ok(None);
665    };
666    let runs = state
667        .path
668        .join("snapshots")
669        .join(crate::stage::stage_name(target));
670    let stamp = jiff::Timestamp::now()
671        .strftime("%Y%m%dT%H%M%SZ")
672        .to_string();
673    let run = if claim {
674        crate::adapters::fs::claim_run_dir(&runs, &stamp)?
675    } else {
676        runs.join(stamp)
677    };
678    Ok(Some(run.join("replaced")))
679}
680
681/// Keep every named destination's bytes, and report where each went.
682fn keep_named(
683    target: &Utf8Path,
684    named: &[String],
685    root: Option<&Utf8Path>,
686    outcome: &mut UpgradeOutcome,
687) -> Result<(), AppError> {
688    for name in named {
689        let saved_to = save(target, name, root)?;
690        if let Some(saved) = &saved_to {
691            outcome.lines.push(format!("saved {name} to {saved}"));
692        }
693        outcome.replaced.push(Replaced {
694            path: name.clone(),
695            saved_to,
696        });
697    }
698    Ok(())
699}
700
701/// Keep one destination's bytes before it is replaced.
702///
703/// A copy already there with other bytes is somebody's earlier answer, and
704/// writing over it would lose the bytes this step exists to keep.
705fn save(
706    target: &Utf8Path,
707    named: &str,
708    root: Option<&Utf8Path>,
709) -> Result<Option<Utf8PathBuf>, AppError> {
710    let held = match std::fs::read(target.join(named)) {
711        Ok(held) => held,
712        Err(source) if source.kind() == std::io::ErrorKind::NotFound => return Ok(None),
713        Err(source) => return Err(AppError::Io(source)),
714    };
715    let Some(root) = root else {
716        return Err(AppError::Refused(format!(
717            "no docs scratch and no state root resolve, so the bytes of {named} have nowhere to be kept; set XDG_STATE_HOME or declare a docs scratch"
718        )));
719    };
720    let saved = root.join(named);
721    match std::fs::read(&saved) {
722        Ok(existing) if existing == held => return Ok(Some(saved)),
723        Ok(_) => {
724            return Err(AppError::Refused(format!(
725                "{saved} already keeps other bytes of {named}; move it aside, then run this again"
726            )));
727        }
728        Err(_) => {}
729    }
730    crate::adapters::fs::write_file(&saved, &held)?;
731    Ok(Some(saved))
732}
733
734/// Every rule ID the instance's own specs define, read from the spec
735/// directory under its documentation root.
736fn instance_rule_ids(target: &Utf8Path, docs_root: &str) -> std::collections::BTreeSet<String> {
737    let mut ids = std::collections::BTreeSet::new();
738    let specs = target.join(docs_root).join("specs");
739    if let Ok(entries) = specs.read_dir_utf8() {
740        for entry in entries.filter_map(Result::ok) {
741            if let Ok(text) = std::fs::read_to_string(entry.path()) {
742                ids.extend(crate::embedded::rule_ids_in(&text));
743            }
744        }
745    }
746    ids
747}
748
749/// Every citation of a rule ID this binary no longer defines.
750///
751/// A citation is an inline-code token in a domain this binary defines
752/// rules in, naming a rule it does not define. A rule heading is a
753/// definition rather than a citation, a decision record is judged on its
754/// `Enforced by` paragraph alone, every line it wraps onto included,
755/// because its prose may describe a retirement,
756/// and a file this tool manages is about to be replaced, so none of those
757/// is listed. The changelog is history and is never re-pointed, a token
758/// this binary's own specs carry is an example it ships, and a rule the
759/// instance's own specs define is live wherever this binary once retired
760/// a rule of the same name.
761///
762/// SATISFIES staging:an-upgrade-lists-every-retired-citation-first
763fn retired_citations(target: &Utf8Path, installed: &Installed) -> Vec<Citation> {
764    let defined = crate::embedded::spec_rule_ids();
765    let domains: std::collections::BTreeSet<&str> = defined
766        .iter()
767        .filter_map(|id| id.split_once(':').map(|(domain, _)| domain))
768        .collect();
769    // A token this binary's own specs carry is an example it ships, such as
770    // a scenario showing a dead citation, never a retirement it caused.
771    let shipped: std::collections::BTreeSet<String> = crate::embedded::spec_texts()
772        .flat_map(|text| {
773            text.lines()
774                .flat_map(crate::gates::adr_cites_a_live_rule::cited_ids)
775                .map(String::from)
776                .collect::<Vec<_>>()
777        })
778        .collect();
779    // A project that keeps a spec domain of the same name, such as its own
780    // `staging`, defines its rules there, and a citation of one is live.
781    let local = instance_rule_ids(target, &installed.docs_root);
782    let managed: Vec<&Utf8PathBuf> = installed.managed.iter().map(|(path, _)| path).collect();
783    let decisions = Utf8Path::new(&installed.docs_root).join("decisions");
784    let mut found = Vec::new();
785    let walker = walkdir::WalkDir::new(target)
786        .sort_by_file_name()
787        .into_iter()
788        .filter_entry(|entry| {
789            let name = entry.file_name().to_string_lossy();
790            !(entry.depth() > 0
791                && entry.file_type().is_dir()
792                && (crate::gates::PRUNED_DIRS.contains(&name.as_ref())
793                    || name == crate::domain::paths::INSTANCE_DIR
794                    || crate::domain::paths::DOCS_SCRATCH_LEAVES.contains(&name.as_ref())))
795        });
796    for entry in walker.filter_map(Result::ok) {
797        if !entry.file_type().is_file() {
798            continue;
799        }
800        let Some(path) = entry.path().to_str() else {
801            continue;
802        };
803        let Ok(relative) = Utf8Path::new(path).strip_prefix(target) else {
804            continue;
805        };
806        if relative.extension() != Some("md")
807            || relative == "CHANGELOG.md"
808            || managed.iter().any(|held| *held == relative)
809        {
810            continue;
811        }
812        let Ok(text) = std::fs::read_to_string(entry.path()) else {
813            continue;
814        };
815        let record = relative.starts_with(&decisions);
816        let enforced: std::collections::BTreeSet<usize> = if record {
817            crate::gates::adr_cites_a_live_rule::enforced_by(&text)
818                .into_iter()
819                .map(|(number, _)| number)
820                .collect()
821        } else {
822            std::collections::BTreeSet::new()
823        };
824        for (index, line) in text.lines().enumerate() {
825            if line.starts_with("### `") || (record && !enforced.contains(&(index + 1))) {
826                continue;
827            }
828            for id in crate::gates::adr_cites_a_live_rule::cited_ids(line) {
829                let domain = id.split_once(':').map_or(id, |(domain, _)| domain);
830                if domains.contains(domain)
831                    && !defined.contains(id)
832                    && !shipped.contains(id)
833                    && !local.contains(id)
834                {
835                    found.push(Citation {
836                        path: relative.to_owned(),
837                        line: index + 1,
838                        id: id.to_string(),
839                    });
840                }
841            }
842        }
843    }
844    found
845}
846
847fn finish(
848    target: &Utf8Path,
849    installed: &Installed,
850    removed: &[String],
851    old: CanonVersion,
852    new: CanonVersion,
853    outcome: &mut UpgradeOutcome,
854) {
855    report_removals(removed, outcome);
856
857    let local_ids = instance_rule_ids(target, &installed.docs_root);
858    let upstream_only: Vec<String> = crate::embedded::spec_rule_ids()
859        .difference(&local_ids)
860        .cloned()
861        .collect();
862    if !upstream_only.is_empty() {
863        outcome
864            .lines
865            .push("upstream rule IDs not present locally:".to_string());
866        for id in upstream_only {
867            outcome.lines.push(format!("  {id}"));
868        }
869    }
870
871    if outcome.failures > 0 {
872        outcome.lines.push(format!(
873            "FAIL upgraded {old} to {new} with unfinished removals above"
874        ));
875    } else if old == new {
876        outcome
877            .lines
878            .push(format!("OK migrated the record of {new}"));
879    } else {
880        outcome.lines.push(format!("OK upgraded {old} to {new}"));
881    }
882}
883
884#[cfg(test)]
885mod tests {
886    use super::*;
887
888    /// SATISFIES staging:a-replacement-keeps-the-bytes-it-replaces
889    #[test]
890    fn two_saves_in_one_second_keep_both_copies() {
891        let dir = tempfile::tempdir().unwrap();
892        let root = Utf8Path::from_path(dir.path()).unwrap();
893        let target = root.join("target");
894        let runs = root.join("snapshots");
895        let stamp = "20261009T213000Z";
896
897        crate::adapters::fs::write_file(&target.join("AGENTS.md"), b"first").unwrap();
898        let first = crate::adapters::fs::claim_run_dir(&runs, stamp).unwrap();
899        let kept = save(&target, "AGENTS.md", Some(&first)).unwrap().unwrap();
900
901        crate::adapters::fs::write_file(&target.join("AGENTS.md"), b"second").unwrap();
902        let second = crate::adapters::fs::claim_run_dir(&runs, stamp).unwrap();
903        let again = save(&target, "AGENTS.md", Some(&second)).unwrap().unwrap();
904
905        assert_ne!(kept, again);
906        assert_eq!(std::fs::read(&kept).unwrap(), b"first");
907        assert_eq!(std::fs::read(&again).unwrap(), b"second");
908    }
909}