continuity.plan

{
  "additionalProperties": false,
  "description": "The input of `continuity.plan` and `continuity.resume`: which record, by id or a prefix\nof one. Absent, the one handover another device published that this checkout has not\nresumed — on this branch when there is one there.",
  "properties": {
    "record": {
      "description": "A record id, or a unique prefix of one.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "title": "RecordInput",
  "type": "object"
}

{
  "$defs": {
    "Component": {
      "description": "What a resume writes, recomputes or leaves.",
      "oneOf": [
        {
          "const": "handover",
          "description": "The handover, into this checkout's handovers.",
          "type": "string"
        },
        {
          "const": "intent",
          "description": "The task's title and scope, offered as the `start` to run.",
          "type": "string"
        },
        {
          "const": "issue",
          "description": "The issue and milestone.",
          "type": "string"
        },
        {
          "const": "decisions",
          "description": "The decisions the task recorded, into this checkout's decision log.",
          "type": "string"
        },
        {
          "const": "next_action",
          "description": "The handover's next action.",
          "type": "string"
        },
        {
          "const": "lineage",
          "description": "The record this checkout continues: the parent of its next publication.",
          "type": "string"
        },
        {
          "const": "provenance",
          "description": "Who published it, where, when, from which source state.",
          "type": "string"
        },
        {
          "const": "worktree",
          "description": "This checkout's path, recomputed rather than copied.",
          "type": "string"
        },
        {
          "const": "repository_id",
          "description": "The repository id the shell compares, recomputed.",
          "type": "string"
        },
        {
          "const": "episode",
          "description": "The episode, opened here by the provider's hooks.",
          "type": "string"
        },
        {
          "const": "working_context",
          "description": "The working context, compiled here from the restored records and this git.",
          "type": "string"
        },
        {
          "const": "source_state",
          "description": "The source state, from this checkout's git.",
          "type": "string"
        }
      ]
    },
    "Device": {
      "description": "The device a record was written on: the mesh node key's id and the label its identity\nfile carries. The label is presentation; the node id is identity.",
      "properties": {
        "label": {
          "description": "The display label of the device's identity file (`macbook-pro`), or the first eight\nhex of its node id when it has none.",
          "type": "string"
        },
        "node": {
          "description": "The node id: the first 32 hex of the SHA-256 of the device's Ed25519 public key.",
          "type": "string"
        }
      },
      "required": [
        "node",
        "label"
      ],
      "type": "object"
    },
    "PlanItem": {
      "description": "One thing a plan says about itself.",
      "properties": {
        "code": {
          "description": "A stable code: `source_incomplete`, `line_diverged`, `origin_untrusted`, …",
          "type": "string"
        },
        "message": {
          "description": "What it means here.",
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object"
    },
    "PlanStatus": {
      "description": "The verdict of a resume plan.",
      "oneOf": [
        {
          "const": "ready",
          "description": "Resume restores everything; nothing needs attention.",
          "type": "string"
        },
        {
          "const": "ready_with_warnings",
          "description": "Resume restores everything; the warnings say what is not what it was at the origin.",
          "type": "string"
        },
        {
          "const": "requires_source_update",
          "description": "The local source does not hold what the record was written against: update git\nfirst, as the actions say.",
          "type": "string"
        },
        {
          "const": "conflict",
          "description": "The same work was continued twice, or the source histories diverged: a person\nchooses.",
          "type": "string"
        },
        {
          "const": "choose_record",
          "description": "More than one record could be meant: name one with `--record`.",
          "type": "string"
        },
        {
          "const": "nothing_to_resume",
          "description": "Nothing to resume.",
          "type": "string"
        },
        {
          "const": "refused",
          "description": "The record is not one this checkout may resume from (an untrusted signer).",
          "type": "string"
        }
      ]
    },
    "RecordView": {
      "description": "One record as every surface shows it.",
      "properties": {
        "age_minutes": {
          "description": "Minutes since then, by this machine's clock; absent when either clock's reading is\nunusable.",
          "format": "int64",
          "type": [
            "integer",
            "null"
          ]
        },
        "branch": {
          "description": "The branch it was written on.",
          "type": [
            "string",
            "null"
          ]
        },
        "changed_total": {
          "description": "How many paths differed from HEAD at the origin.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "device": {
          "$ref": "#/$defs/Device",
          "description": "The device that published it."
        },
        "head": {
          "description": "The commit it was written at.",
          "type": [
            "string",
            "null"
          ]
        },
        "id": {
          "description": "The record id.",
          "type": "string"
        },
        "issue": {
          "description": "The issue.",
          "type": [
            "string",
            "null"
          ]
        },
        "line": {
          "description": "Its line.",
          "type": "string"
        },
        "objective": {
          "description": "The handover's `# Objective`, first line.",
          "type": "string"
        },
        "parent": {
          "description": "The record it continues.",
          "type": [
            "string",
            "null"
          ]
        },
        "published_at": {
          "description": "When it was published, by the publisher's clock.",
          "type": "string"
        },
        "session": {
          "description": "The episode it was published from.",
          "type": [
            "string",
            "null"
          ]
        },
        "task": {
          "description": "The task's title: the intent.",
          "type": [
            "string",
            "null"
          ]
        },
        "this_device": {
          "description": "Whether that device is this one.",
          "type": "boolean"
        },
        "trust": {
          "$ref": "#/$defs/Trust",
          "description": "Whether its signer is trusted here."
        },
        "working_tree": {
          "$ref": "#/$defs/WorkingTree",
          "description": "Clean or dirty at the origin."
        }
      },
      "required": [
        "id",
        "line",
        "device",
        "this_device",
        "trust",
        "working_tree",
        "changed_total",
        "published_at"
      ],
      "type": "object"
    },
    "Relation": {
      "description": "What one record is to another.",
      "oneOf": [
        {
          "const": "equal",
          "description": "The same record.",
          "type": "string"
        },
        {
          "const": "newer",
          "description": "The second descends from the first: the second is newer.",
          "type": "string"
        },
        {
          "const": "older",
          "description": "The first descends from the second: the second is older.",
          "type": "string"
        },
        {
          "const": "diverged",
          "description": "Same line, neither descends from the other: the work was continued twice.",
          "type": "string"
        },
        {
          "const": "independent",
          "description": "Different lines: separate work.",
          "type": "string"
        }
      ]
    },
    "SourceCheck": {
      "description": "The source half of a plan.",
      "properties": {
        "expected_branch": {
          "description": "The branch the record was written on.",
          "type": [
            "string",
            "null"
          ]
        },
        "expected_head": {
          "description": "The commit it was written at.",
          "type": [
            "string",
            "null"
          ]
        },
        "local_branch": {
          "description": "This checkout's branch.",
          "type": [
            "string",
            "null"
          ]
        },
        "local_dirty": {
          "description": "Whether this checkout's tree is dirty.",
          "type": "boolean"
        },
        "local_head": {
          "description": "This checkout's commit.",
          "type": [
            "string",
            "null"
          ]
        },
        "origin_changed": {
          "description": "The paths that were uncommitted at the origin, as listed.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "origin_changed_total": {
          "description": "How many were uncommitted.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "origin_dirty": {
          "description": "Whether the origin's tree was dirty.",
          "type": "boolean"
        },
        "relation": {
          "$ref": "#/$defs/SourceRelation",
          "description": "How they stand."
        },
        "same_uncommitted_work": {
          "description": "Whether this checkout holds the very uncommitted work the origin held (their\nfingerprints agree); absent when either side is clean.",
          "type": [
            "boolean",
            "null"
          ]
        }
      },
      "required": [
        "relation",
        "origin_dirty",
        "origin_changed_total",
        "local_dirty"
      ],
      "type": "object"
    },
    "SourceRelation": {
      "description": "How the local source stands towards the record's.",
      "oneOf": [
        {
          "const": "exact",
          "description": "Same branch, same commit.",
          "type": "string"
        },
        {
          "const": "local_ahead",
          "description": "Same branch; the local branch has commits the record did not see.",
          "type": "string"
        },
        {
          "const": "local_behind",
          "description": "Same branch; the record's commit is ahead of the local one.",
          "type": "string"
        },
        {
          "const": "diverged",
          "description": "Same branch; neither commit contains the other.",
          "type": "string"
        },
        {
          "const": "head_missing",
          "description": "The record's commit is not in this clone.",
          "type": "string"
        },
        {
          "const": "branch_differs",
          "description": "This checkout is on another branch.",
          "type": "string"
        },
        {
          "const": "unknown",
          "description": "The record carries no commit, or git could not answer.",
          "type": "string"
        }
      ]
    },
    "TaskRef": {
      "description": "The task the handover was written under, as the task record named it.",
      "properties": {
        "id": {
          "description": "The task id, `t-<stamp>-<hex>`.",
          "type": "string"
        },
        "outcome": {
          "description": "The outcome the task record held when the handover was published.",
          "type": [
            "string",
            "null"
          ]
        },
        "profile": {
          "description": "The profile it ran under.",
          "type": [
            "string",
            "null"
          ]
        },
        "scope": {
          "description": "The repository paths it may touch.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "title": {
          "description": "What the task is, in its author's words: the intent.",
          "type": "string"
        }
      },
      "required": [
        "id",
        "title"
      ],
      "type": "object"
    },
    "Trust": {
      "description": "Whether the device that signed a record is one this repository trusts.",
      "oneOf": [
        {
          "const": "this_device",
          "description": "This device signed it.",
          "type": "string"
        },
        {
          "const": "trusted",
          "description": "The mesh declaration's trust list admits the key.",
          "type": "string"
        },
        {
          "const": "untrusted",
          "description": "The mesh declaration exists and does not admit the key: never resumed from.",
          "type": "string"
        },
        {
          "const": "undeclared",
          "description": "The repository declares no mesh, so no list exists to check the key against. The\nsignature still binds the record to its key; the plan warns.",
          "type": "string"
        }
      ]
    },
    "WorkingTree": {
      "description": "Whether the working tree had changes git does not hold in a commit.",
      "oneOf": [
        {
          "const": "clean",
          "description": "Nothing outside HEAD.",
          "type": "string"
        },
        {
          "const": "dirty",
          "description": "Modified, staged or untracked files that HEAD does not hold.",
          "type": "string"
        }
      ]
    }
  },
  "description": "The answer of `continuity plan`, and the plan `continuity resume` acts on.",
  "properties": {
    "actions": {
      "description": "The commands that resolve the blockers or follow the resume. Recommended, never run:\nnothing a record says is executed.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "blockers": {
      "description": "What stops a resume.",
      "items": {
        "$ref": "#/$defs/PlanItem"
      },
      "type": "array"
    },
    "candidates": {
      "description": "When the record is not decided: the records that could be meant.",
      "items": {
        "$ref": "#/$defs/RecordView"
      },
      "type": "array"
    },
    "current_state": {
      "description": "The handover's `# Current State`.",
      "type": "string"
    },
    "decisions": {
      "description": "The headings of the decisions a resume carries.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "lineage": {
      "anyOf": [
        {
          "$ref": "#/$defs/Relation"
        },
        {
          "type": "null"
        }
      ],
      "description": "What the record is to the record this checkout stands on, when it stands on one."
    },
    "milestone": {
      "description": "The milestone.",
      "type": [
        "string",
        "null"
      ]
    },
    "next_action": {
      "description": "The handover's `# Next Action`.",
      "type": "string"
    },
    "objective": {
      "description": "The handover's `# Objective`.",
      "type": "string"
    },
    "recomputes": {
      "description": "What this checkout computes for itself instead of copying.",
      "items": {
        "$ref": "#/$defs/Component"
      },
      "type": "array"
    },
    "record": {
      "anyOf": [
        {
          "$ref": "#/$defs/RecordView"
        },
        {
          "type": "null"
        }
      ],
      "description": "The record it is about."
    },
    "restores": {
      "description": "What a resume writes into this checkout.",
      "items": {
        "$ref": "#/$defs/Component"
      },
      "type": "array"
    },
    "source": {
      "anyOf": [
        {
          "$ref": "#/$defs/SourceCheck"
        },
        {
          "type": "null"
        }
      ],
      "description": "The source check."
    },
    "status": {
      "$ref": "#/$defs/PlanStatus",
      "description": "The verdict."
    },
    "task": {
      "anyOf": [
        {
          "$ref": "#/$defs/TaskRef"
        },
        {
          "type": "null"
        }
      ],
      "description": "The task, as published: the intent."
    },
    "warnings": {
      "description": "What a resume proceeds past and a person should know.",
      "items": {
        "$ref": "#/$defs/PlanItem"
      },
      "type": "array"
    }
  },
  "required": [
    "status",
    "blockers",
    "warnings",
    "actions",
    "restores",
    "recomputes"
  ],
  "title": "ResumePlan",
  "type": "object"
}