recover.orphans

Projde publikační temp soubory každého úložiště záznamů, rename temp soubory pod lokální polovinou vrstvy a sledovanou sekcí relací a stagingové adresáře generátoru webu v kořeni repozitáře; každému dá verdikt podle jeho stáří a pak obsahu; a pokud volání není kontrola, odstraní ty, o nichž verdikt říká, že je nic nedrží. Nic se nemaže jen proto, že to nebylo rozpoznáno: temp, který drží jedinou kopii záznamu, se hlásí jako `incomplete` a nechává se volajícímu k publikaci, obsah, který tato verze neumí klasifikovat, je `foreign` a zůstává přesně tam, kde je, kandidát, jehož stáří tato platforma neumí přečíst, je `unmeasurable` a nikdy kandidát, a žádný adresář se nikdy neodstraňuje. Práh je povinný a nemá výchozí hodnotu, protože úklid měřený proti chybějícímu prahu by shledal zastaralým každý soubor.

command
behaviorally_verified
module recover
#recover
#sessions
#maintenance
#lifecycle

Zpřístupnění

Kde je tato jedna definice dosažitelná. Absence je explicitní: povrch, který není uveden, ji nenese.

povrch	jako
MCP	nástroj majordomus_recover_orphans
HTTP	POST /api/v1/recover/orphans operationId recover.orphans
příkazová řádka	—

Schémata

Kanonický vstup a výstup z typů Rustu; schéma nástroje MCP a parametry a odpovědi OpenAPI se odvozují z nich.

vstup · RecoverOrphansInput

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());

vlastnost	typ	povinné	popis
check	boolean	ne	Klasifikuje a hlásí, nic nezapisuje. Výchozí, protože alternativa maže soubory. výchozí true
older_than_seconds	integer	ano	Jak dlouho musel zbloudilý soubor zůstat nedotčen, aby se vůbec stal kandidátem, v sekundách. Povinné a na nule odmítnuté: shellový nástroj je řeší z `session.stranded_after` pomocí `mj_pol_req`, což selhává uzavřeně, a nic zde žádný nevymýšlí.

JSON Schema

{
  "additionalProperties": false,
  "description": "The input of `recover.orphans`: how old a stray must be, and whether to act.\n\n```\nuse majordomus_cli::capability::builtin::recover::RecoverOrphansInput;\n\n// The wire form the shell tool, an MCP client or an HTTP POST sends.\nlet act: RecoverOrphansInput =\n    serde_json::from_str(r#\"{\"older_than_seconds\":43200,\"check\":false}\"#).unwrap();\nassert_eq!(act.older_than_seconds, 43_200);\nassert!(!act.check);\n\n// `check` defaults to true, and that direction is deliberate: this capability deletes\n// files, and a caller that forgets the field gets a plan rather than a sweep.\nlet forgot: RecoverOrphansInput =\n    serde_json::from_str(r#\"{\"older_than_seconds\":43200}\"#).unwrap();\nassert!(forgot.check, \"the safe value is the default one\");\n\n// The threshold has no default at all. `session.stranded_after` is a policy value, and\n// a reader that carried its own copy would be a second place the number lives.\nassert!(serde_json::from_str::<RecoverOrphansInput>(r#\"{\"check\":true}\"#).is_err());\n\n// Unknown fields are refused rather than ignored: a caller that misspells `check` is\n// told so instead of having a sweep silently run.\nassert!(serde_json::from_str::<RecoverOrphansInput>(\n    r#\"{\"older_than_seconds\":1,\"chek\":true}\"#).is_err());\n```",
  "properties": {
    "check": {
      "default": true,
      "description": "Classify and report, and write nothing. The default, because the alternative deletes\nfiles.",
      "type": "boolean"
    },
    "older_than_seconds": {
      "description": "How long a stray file must have been untouched before it is a candidate at all, in\nseconds. Required, and refused at zero: the shell tool resolves it from\n`session.stranded_after` with `mj_pol_req`, which fails closed, and nothing here\ninvents one.",
      "format": "uint64",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "older_than_seconds"
  ],
  "title": "RecoverOrphansInput",
  "type": "object"
}

output · RecoverOrphansResult

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);

vlastnost	typ	povinné	popis
check	boolean	ano	Zda šlo o kontrolu. `true` znamená, že se nic nezapsalo.
older_than_seconds	integer	ano	Práh, proti kterému toto čištění měřilo, vrácený zpět, aby odmítnutí nebo verdikt pojmenovaly hodnotu, kterou volající skutečně dostal, ne tu, o které věří, že ji poslal.
odstranitelné	integer	ano	Kolik z nich by toto volání odstranilo, nebo odstranilo.
odstraněno	integer	ano	Kolik jich skutečně odstranil. Při kontrole vždy `0`.
zbloudilé	array	ano	Každý nalezený zbloudilý soubor v pořadí podle cesty.
neměřitelné	integer	ano	Kolik kandidátů nešlo změřit, a proto zůstali beze změny.

JSON Schema

{
  "$defs": {
    "Stray": {
      "description": "One stray file, its verdict, and the evidence that produced it.\n\nEvery field that decided something is carried, because the rule this command is shaped\naround requires the value that decided a verdict to be visible before the verdict acts:\na surface that printed \"orphan\" without the age, the episode and the file that already\nholds it would be asking to be trusted rather than read.\n\n```\nuse majordomus_cli::capability::builtin::recover::{Stray, StrayKind, StrayVerdict};\nuse serde_json::json;\n\nlet s: Stray = serde_json::from_value(json!({\n    \"path\": \".ai/repo/sessions/.tmp.a1b2c3\",\n    \"kind\": \"publish_temp\",\n    \"verdict\": \"orphan\",\n    \"age_seconds\": 90_000,\n    \"session_id\": \"s-0007\",\n    \"published_at\": \".ai/repo/sessions/2026-09-11--s-0007.md\",\n    \"removable\": true,\n    \"removed\": false,\n})).unwrap();\nassert_eq!(s.verdict, StrayVerdict::Orphan);\nassert_eq!(s.kind, StrayKind::PublishTemp);\n// removable and removed are different facts: a check run reports the first and never\n// the second, which is what makes `--check` readable as a plan rather than a report.\nassert!(s.removable && !s.removed);\n\n// and an unmeasurable one carries no age at all, rather than a zero that would read as\n// \"brand new\" to anything that compared it with a threshold\nlet u: Stray = serde_json::from_value(json!({\n    \"path\": \".mj-stage.xyz\", \"kind\": \"staging_dir\", \"verdict\": \"unmeasurable\",\n    \"removable\": false, \"removed\": false,\n})).unwrap();\nassert!(u.age_seconds.is_none());\n```",
      "properties": {
        "age_seconds": {
          "description": "How old it is, in seconds. Absent when the platform could not say, which is the\n`Unmeasurable` verdict and never a zero.",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "kind": {
          "$ref": "#/$defs/StrayKind",
          "description": "Which of the three shapes this is."
        },
        "path": {
          "description": "The path, repository-relative. Never the absolute one: a finding that names a disk is\na finding nobody else can act on (`project.no-machine-paths`).",
          "type": "string"
        },
        "published_at": {
          "description": "The record that already holds that episode, when one does. Its presence is what turns\nan `Incomplete` publish temp into an `Orphan`.",
          "type": "string"
        },
        "removable": {
          "description": "Whether this call would remove it. Decided by the verdict and by\n`remove_stray`'s own pattern guard, never by the caller.",
          "type": "boolean"
        },
        "removed": {
          "description": "Whether this call did remove it. Always `false` on a check.",
          "type": "boolean"
        },
        "session_id": {
          "description": "The episode this publish temp carries, when it carries one.",
          "type": "string"
        },
        "target": {
          "description": "The file a rename temp was going to become. Its presence is what turns an\n`Incomplete` rename temp into an `Orphan`.",
          "type": "string"
        },
        "verdict": {
          "$ref": "#/$defs/StrayVerdict",
          "description": "What reading it decided."
        }
      },
      "required": [
        "path",
        "kind",
        "verdict",
        "removable",
        "removed"
      ],
      "type": "object"
    },
    "StrayKind": {
      "description": "What kind of stray a path is, decided by where it is and how it is named rather than by\nwhat is in it. The content decides the *verdict*; this decides which question to ask.\n\nThe word a kind is reported under is also the word it is read back from, and a word this\nversion does not know is refused rather than read as the nearest kind:\n\n```\nuse majordomus_cli::capability::builtin::recover::StrayKind;\nfor kind in [StrayKind::PublishTemp, StrayKind::RenameTemp, StrayKind::StagingDir] {\n    let word = serde_json::to_value(kind).unwrap();\n    assert_eq!(serde_json::from_value::<StrayKind>(word).unwrap(), kind);\n}\nassert!(serde_json::from_value::<StrayKind>(serde_json::json!(\"temp\")).is_err());\n```",
      "oneOf": [
        {
          "const": "publish_temp",
          "description": "A `.tmp.XXXXXX` in a record store: `mj_publish_record` makes them, and only a process\nthat died between the `mktemp` and the `rm` leaves one.",
          "type": "string"
        },
        {
          "const": "rename_temp",
          "description": "A `<target>.mj-tmp`: written and renamed in one `&&`, so one that exists means the\nwrite failed or the process died mid-write.",
          "type": "string"
        },
        {
          "const": "staging_dir",
          "description": "A `.mj-stage.XXXXXX` at the repository root: `scripts/generate-site-data` stages into\none. Always a directory, and therefore never removed here.",
          "type": "string"
        }
      ]
    },
    "StrayVerdict": {
      "description": "What this stray is, decided by reading it.\n\nThe five words are `lib/recover.sh`'s, deliberately: a person who has read the command's\noutput should not have to learn the same five facts twice because a second surface chose\nits own vocabulary.\n\nThat vocabulary is closed. Every verdict reads back as itself, and there is no sixth word:\na surface that invents one gets an error rather than a verdict nobody meant.\n\n```\nuse majordomus_cli::capability::builtin::recover::StrayVerdict::{self, *};\nlet all = [Live, Orphan, Incomplete, Foreign, Unmeasurable];\nlet words: Vec<&str> = all.iter().map(|v| v.as_str()).collect();\nassert_eq!(words, [\"live\", \"orphan\", \"incomplete\", \"foreign\", \"unmeasurable\"]);\nfor v in all {\n    let word = serde_json::json!(v.as_str());\n    assert_eq!(serde_json::from_value::<StrayVerdict>(word).unwrap(), v);\n}\nassert!(serde_json::from_value::<StrayVerdict>(serde_json::json!(\"stale\")).is_err());\n```",
      "oneOf": [
        {
          "const": "live",
          "description": "Younger than the threshold: a `session close` or a `scripts/derive` running right now\nowns it. Measured, reported, never touched.",
          "type": "string"
        },
        {
          "const": "orphan",
          "description": "Its work completed, or there was never anything in it. Removable — unless it is a\ndirectory, which this runtime never removes.",
          "type": "string"
        },
        {
          "const": "incomplete",
          "description": "It holds something no other file holds: a record nobody published, or a write whose\ntarget never arrived. Never removed here; the caller decides.",
          "type": "string"
        },
        {
          "const": "foreign",
          "description": "Not written by this tool at all, or written by a version that shaped it differently.\nNever touched; reported with what it is.",
          "type": "string"
        },
        {
          "const": "unmeasurable",
          "description": "Its age could not be read on this platform, so nothing here treats it as stale. The\nguard `project.destructive-sweeps-fail-closed` asks for: a predicate that cannot\nmeasure its input is false, never the most extreme value in the set.",
          "type": "string"
        }
      ]
    }
  },
  "description": "What one sweep found and what it did about it.\n\nThe counts are derived from `strays` rather than accumulated beside it, so a reader can\ncheck the report against itself and a surface that renders the list cannot disagree with\nthe surface that renders the total.\n\n```\nuse majordomus_cli::capability::builtin::recover::RecoverOrphansResult;\n\nlet plan: RecoverOrphansResult = serde_json::from_str(r#\"{\n    \"older_than_seconds\": 43200, \"check\": true, \"strays\": [],\n    \"removable\": 0, \"removed\": 0, \"unmeasurable\": 0\n}\"#).unwrap();\n// a check never removes anything, whatever it found\nassert_eq!(plan.removed, 0);\nassert!(plan.check);\n```",
  "properties": {
    "check": {
      "description": "Whether this was a check. `true` means nothing was written.",
      "type": "boolean"
    },
    "older_than_seconds": {
      "description": "The threshold this sweep measured against, echoed back so that a refusal or a verdict\nnames the value the caller actually got rather than the one it believes it sent.",
      "format": "uint64",
      "minimum": 0,
      "type": "integer"
    },
    "removable": {
      "description": "How many of them this call would remove, or did.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "removed": {
      "description": "How many it actually removed. Always `0` on a check.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "strays": {
      "description": "Every stray found, in path order.",
      "items": {
        "$ref": "#/$defs/Stray"
      },
      "type": "array"
    },
    "unmeasurable": {
      "description": "How many candidates could not be measured and were therefore left alone.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "older_than_seconds",
    "check",
    "strays",
    "removable",
    "removed",
    "unmeasurable"
  ],
  "title": "RecoverOrphansResult",
  "type": "object"
}

Politiky

benchmark: povinné — cíl na každém transportu, který expozice deklaruje; případy jsou ty ze vstupního typu
cache: vypnuto — každé volání spustí handler

Cíle benchmarku

Odvozeno z registru pro tento repozitář: jeden požadavek na transport a případy, které poskytuje typ vstupu. Celá matice je na stránce měření výkonu.

transport	state	případy	targets
direct	pokryto	2	check-twelve-hours check-one-second
mcp	pokryto	2	check-twelve-hours check-one-second
http	pokryto	2	check-twelve-hours check-one-second