HTTP API: recover

Vstup recover.orphans: jak starý musí být zatoulaný soubor a zda jednat.

use majordomus_cli::capability::builtin::recover::RecoverOrphansInput;

// The wire form the shell tool, an MCP client or an HTTP POST sends.
let act: RecoverOrphansInput =
    serde_json::from_str(r#"{"older_than_seconds":43200,"check":false}"#).unwrap();
assert_eq!(act.older_than_seconds, 43_200);
assert!(!act.check);

// `check` defaults to true, and that direction is deliberate: this capability deletes
// files, and a caller that forgets the field gets a plan rather than a sweep.
let forgot: RecoverOrphansInput =
    serde_json::from_str(r#"{"older_than_seconds":43200}"#).unwrap();
assert!(forgot.check, "the safe value is the default one");

// The threshold has no default at all. `session.stranded_after` is a policy value, and
// a reader that carried its own copy would be a second place the number lives.
assert!(serde_json::from_str::<RecoverOrphansInput>(r#"{"check":true}"#).is_err());

// Unknown fields are refused rather than ignored: a caller that misspells `check` is
// told so instead of having a sweep silently run.
assert!(serde_json::from_str::<RecoverOrphansInput>(
    r#"{"older_than_seconds":1,"chek":true}"#).is_err());

Co jeden průchod našel a co s tím udělal.

Počty se odvozují z strays, a ne akumulují vedle něj, takže čtenář může zprávu zkontrolovat sama proti sobě a povrch, který vykresluje seznam, se nemůže rozejít s povrchem, který vykresluje součet.

use majordomus_cli::capability::builtin::recover::RecoverOrphansResult;

let plan: RecoverOrphansResult = serde_json::from_str(r#"{
    "older_than_seconds": 43200, "check": true, "strays": [],
    "removable": 0, "removed": 0, "unmeasurable": 0
}"#).unwrap();
// a check never removes anything, whatever it found
assert_eq!(plan.removed, 0);
assert!(plan.check);

Jeden zatoulaný soubor, jeho verdikt a důkazy, které jej vytvořily.

Nese se každé pole, které něco rozhodlo, protože pravidlo, podle kterého je tento příkaz tvarován, vyžaduje, aby hodnota, která rozhodla o verdiktu, byla viditelná dříve, než verdikt jedná: povrch, který by vytiskl „orphan“ bez stáří, epizody a souboru, který ji už drží, by žádal o důvěru, místo aby byl čten.

use majordomus_cli::capability::builtin::recover::{Stray, StrayKind, StrayVerdict};
use serde_json::json;

let s: Stray = serde_json::from_value(json!({
    "path": ".ai/repo/sessions/.tmp.a1b2c3",
    "kind": "publish_temp",
    "verdict": "orphan",
    "age_seconds": 90_000,
    "session_id": "s-0007",
    "published_at": ".ai/repo/sessions/2026-09-11--s-0007.md",
    "removable": true,
    "removed": false,
})).unwrap();
assert_eq!(s.verdict, StrayVerdict::Orphan);
assert_eq!(s.kind, StrayKind::PublishTemp);
// removable and removed are different facts: a check run reports the first and never
// the second, which is what makes `--check` readable as a plan rather than a report.
assert!(s.removable && !s.removed);

// and an unmeasurable one carries no age at all, rather than a zero that would read as
// "brand new" to anything that compared it with a threshold
let u: Stray = serde_json::from_value(json!({
    "path": ".mj-stage.xyz", "kind": "staging_dir", "verdict": "unmeasurable",
    "removable": false, "removed": false,
})).unwrap();
assert!(u.age_seconds.is_none());

Jaký druh zbloudilého souboru cesta je, rozhodnuto podle toho, kde je a jak se jmenuje, ne podle obsahu. Obsah rozhoduje o verdiktu; toto rozhoduje, jakou otázku položit.

Slovo, pod kterým se druh hlásí, je také slovo, z něhož se čte zpět, a slovo, které tato verze nezná, se odmítne, místo aby se četlo jako nejbližší druh:

use majordomus_cli::capability::builtin::recover::StrayKind;
for kind in [StrayKind::PublishTemp, StrayKind::RenameTemp, StrayKind::StagingDir] {
    let word = serde_json::to_value(kind).unwrap();
    assert_eq!(serde_json::from_value::<StrayKind>(word).unwrap(), kind);
}
assert!(serde_json::from_value::<StrayKind>(serde_json::json!("temp")).is_err());

Čím je tento zbloudilý soubor, rozhodnuto jeho přečtením.

Těch pět slov je záměrně z lib/recover.sh: kdo si přečetl výstup příkazu, se nemá učit týchž pět faktů dvakrát jen proto, že druhý povrch zvolil vlastní slovník.

Tento slovník je uzavřený. Každý verdikt se čte zpět jako sám sebe a šesté slovo neexistuje: povrch, který nějaké vymyslí, dostane chybu místo verdiktu, který nikdo nemyslel.

use majordomus_cli::capability::builtin::recover::StrayVerdict::{self, *};
let all = [Live, Orphan, Incomplete, Foreign, Unmeasurable];
let words: Vec<&str> = all.iter().map(|v| v.as_str()).collect();
assert_eq!(words, ["live", "orphan", "incomplete", "foreign", "unmeasurable"]);
for v in all {
    let word = serde_json::json!(v.as_str());
    assert_eq!(serde_json::from_value::<StrayVerdict>(word).unwrap(), v);
}
assert!(serde_json::from_value::<StrayVerdict>(serde_json::json!("stale")).is_err());