continuity.status

{
  "type": "object",
  "additionalProperties": false,
  "description": "No input.",
  "title": "Empty"
}

{
  "type": "object",
  "properties": {
    "repository": {
      "type": "string",
      "description": "This repository's identity (32 hex), the same on every clone."
    },
    "device": {
      "$ref": "#/$defs/Device",
      "description": "This device."
    },
    "branch": {
      "type": "string",
      "description": "The branch this checkout is on, or `DETACHED`."
    },
    "head": {
      "type": [
        "string",
        "null"
      ],
      "description": "The commit it is on."
    },
    "working_tree": {
      "$ref": "#/$defs/WorkingTree",
      "description": "Clean or dirty."
    },
    "position": {
      "anyOf": [
        {
          "$ref": "#/$defs/Position"
        },
        {
          "type": "null"
        }
      ],
      "description": "The record this checkout continues on its branch."
    },
    "store": {
      "$ref": "#/$defs/StoreView",
      "description": "The stores."
    },
    "last_sync": {
      "anyOf": [
        {
          "$ref": "#/$defs/SyncNote"
        },
        {
          "type": "null"
        }
      ],
      "description": "The last sync, as this checkout recorded it."
    },
    "lines": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/LineView"
      },
      "description": "Every line, by id."
    },
    "resumable": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/RecordView"
      },
      "description": "What other devices published that this checkout could resume, newest first."
    },
    "diagnostics": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Diagnostic"
      },
      "description": "Refused files, broken lineage, diverged lines."
    },
    "next": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The command to run next, when there is an obvious one."
    }
  },
  "required": [
    "repository",
    "device",
    "branch",
    "working_tree",
    "store",
    "lines",
    "resumable",
    "diagnostics"
  ],
  "description": "The answer of `continuity status`.",
  "title": "Status",
  "$defs": {
    "Device": {
      "type": "object",
      "properties": {
        "node": {
          "type": "string",
          "description": "The node id: the first 32 hex of the SHA-256 of the device's Ed25519 public key."
        },
        "label": {
          "type": "string",
          "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."
        }
      },
      "required": [
        "node",
        "label"
      ],
      "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."
    },
    "WorkingTree": {
      "oneOf": [
        {
          "type": "string",
          "const": "clean",
          "description": "Nothing outside HEAD."
        },
        {
          "type": "string",
          "const": "dirty",
          "description": "Modified, staged or untracked files that HEAD does not hold."
        }
      ],
      "description": "Whether the working tree had changes git does not hold in a commit."
    },
    "Position": {
      "type": "object",
      "properties": {
        "line": {
          "type": "string",
          "description": "The line."
        },
        "record": {
          "type": "string",
          "description": "The record: the parent of this checkout's next publication on the branch."
        },
        "via": {
          "$ref": "#/$defs/Via",
          "description": "Published here or resumed here."
        },
        "at": {
          "type": "string",
          "description": "When, by this machine's clock."
        }
      },
      "required": [
        "line",
        "record",
        "via",
        "at"
      ],
      "description": "The record this checkout continues on one branch."
    },
    "Via": {
      "oneOf": [
        {
          "type": "string",
          "const": "published",
          "description": "This checkout published it."
        },
        {
          "type": "string",
          "const": "resumed",
          "description": "This checkout resumed from it."
        }
      ],
      "description": "How this checkout came to stand on a record."
    },
    "StoreView": {
      "type": "object",
      "properties": {
        "reference": {
          "type": "string",
          "description": "The local ref."
        },
        "tip": {
          "type": [
            "string",
            "null"
          ],
          "description": "Its commit."
        },
        "remote": {
          "type": [
            "string",
            "null"
          ],
          "description": "The remote `sync` uses."
        },
        "remote_tip": {
          "type": [
            "string",
            "null"
          ],
          "description": "The commit last fetched from or pushed to it."
        },
        "sync": {
          "$ref": "#/$defs/SyncState",
          "description": "How they stand."
        },
        "records": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Records admitted."
        },
        "refused": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Files refused."
        }
      },
      "required": [
        "reference",
        "sync",
        "records",
        "refused"
      ],
      "description": "The two stores, as refs."
    },
    "SyncState": {
      "oneOf": [
        {
          "type": "string",
          "const": "no_remote",
          "description": "No remote is configured: the store is local, and that is a valid answer."
        },
        {
          "type": "string",
          "const": "never_synced",
          "description": "Never synced with the remote."
        },
        {
          "type": "string",
          "const": "in_sync",
          "description": "Both hold the same records."
        },
        {
          "type": "string",
          "const": "pending",
          "description": "This store holds records the remote has not received: a sync publishes them."
        },
        {
          "type": "string",
          "const": "behind",
          "description": "The last fetch brought records not merged yet."
        },
        {
          "type": "string",
          "const": "diverged",
          "description": "Both of the above."
        },
        {
          "type": "string",
          "const": "empty",
          "description": "The store is empty and nothing was ever fetched."
        }
      ],
      "description": "How the local store stands towards the remote's, from the refs alone — no network."
    },
    "SyncNote": {
      "type": "object",
      "properties": {
        "remote": {
          "type": "string",
          "description": "The remote."
        },
        "at": {
          "type": "string",
          "description": "When, by this machine's clock."
        },
        "outcome": {
          "type": "string",
          "description": "`ok`, or `unreachable` when the remote could not be asked."
        },
        "detail": {
          "type": [
            "string",
            "null"
          ],
          "description": "What git said when it was not `ok`."
        }
      },
      "required": [
        "remote",
        "at",
        "outcome"
      ],
      "description": "What the last sync did, so that a later status can report it without the network."
    },
    "LineView": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The line id."
        },
        "state": {
          "$ref": "#/$defs/LineState",
          "description": "Linear or diverged."
        },
        "records": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "How many records it holds."
        },
        "heads": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/RecordView"
          },
          "description": "Its heads."
        }
      },
      "required": [
        "id",
        "state",
        "records",
        "heads"
      ],
      "description": "A line of work as `status` shows it."
    },
    "LineState": {
      "oneOf": [
        {
          "type": "string",
          "const": "linear",
          "description": "One head: the line continues from it."
        },
        {
          "type": "string",
          "const": "diverged",
          "description": "More than one head: the same work was continued in more than one place."
        }
      ],
      "description": "Whether a line has one current record or several."
    },
    "RecordView": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The record id."
        },
        "line": {
          "type": "string",
          "description": "Its line."
        },
        "parent": {
          "type": [
            "string",
            "null"
          ],
          "description": "The record it continues."
        },
        "device": {
          "$ref": "#/$defs/Device",
          "description": "The device that published it."
        },
        "this_device": {
          "type": "boolean",
          "description": "Whether that device is this one."
        },
        "trust": {
          "$ref": "#/$defs/Trust",
          "description": "Whether its signer is trusted here."
        },
        "session": {
          "type": [
            "string",
            "null"
          ],
          "description": "The episode it was published from."
        },
        "branch": {
          "type": [
            "string",
            "null"
          ],
          "description": "The branch it was written on."
        },
        "head": {
          "type": [
            "string",
            "null"
          ],
          "description": "The commit it was written at."
        },
        "working_tree": {
          "$ref": "#/$defs/WorkingTree",
          "description": "Clean or dirty at the origin."
        },
        "changed_total": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "How many paths differed from HEAD at the origin."
        },
        "published_at": {
          "type": "string",
          "description": "When it was published, by the publisher's clock."
        },
        "age_minutes": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "description": "Minutes since then, by this machine's clock; absent when either clock's reading is\nunusable."
        },
        "task": {
          "type": [
            "string",
            "null"
          ],
          "description": "The task's title: the intent."
        },
        "issue": {
          "type": [
            "string",
            "null"
          ],
          "description": "The issue."
        },
        "objective": {
          "type": "string",
          "description": "The handover's `# Objective`, first line."
        }
      },
      "required": [
        "id",
        "line",
        "device",
        "this_device",
        "trust",
        "working_tree",
        "changed_total",
        "published_at"
      ],
      "description": "One record as every surface shows it."
    },
    "Trust": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "description": "Whether the device that signed a record is one this repository trusts."
    },
    "Diagnostic": {
      "type": "object",
      "properties": {
        "severity": {
          "$ref": "#/$defs/Severity",
          "description": "How bad."
        },
        "code": {
          "type": "string",
          "description": "A stable machine-readable code, e.g. `unknown_key`, `duplicate_identity`."
        },
        "path": {
          "type": [
            "string",
            "null"
          ],
          "description": "Repository-relative path of the file concerned, when there is one."
        },
        "message": {
          "type": "string",
          "description": "What is wrong, for a person; the code is for a program."
        }
      },
      "required": [
        "severity",
        "code",
        "message"
      ],
      "description": "One finding about the declarative state, named by a stable code, tied to a path where\nthere is one, and carrying the command that reproduces it where there is one."
    },
    "Severity": {
      "oneOf": [
        {
          "type": "string",
          "const": "info",
          "description": "Worth knowing; changes nothing."
        },
        {
          "type": "string",
          "const": "warning",
          "description": "Something to look at; the object is still served."
        },
        {
          "type": "string",
          "const": "error",
          "description": "The file is excluded and the index is degraded."
        }
      ],
      "description": "How bad a diagnostic is. `Error` excludes the file it concerns from the index and puts\nthe index into the degraded state; `Warning` and `Info` do neither."
    }
  }
}