{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/GreenLv/dsh-session-insights/blob/main/docs/schema/report-v1.schema.json",
  "title": "dsh-session-insights report schema v1",
  "type": "object",
  "additionalProperties": true,
  "required": [
    "schema",
    "schema_version",
    "analyzer_version",
    "product",
    "runtime",
    "generated_at",
    "scope",
    "coverage",
    "totals",
    "measurement_contract",
    "projects",
    "task_families",
    "session_summaries",
    "excerpts",
    "warnings"
  ],
  "properties": {
    "schema": {
      "const": "dsh-session-insights/1"
    },
    "schema_version": {
      "const": 1
    },
    "product": {
      "const": "dsh-session-insights"
    },
    "runtime": {
      "const": "dsh"
    },
    "generated_at": {
      "type": "string",
      "format": "date-time"
    },
    "scope": {
      "type": "object",
      "required": [
        "runtime",
        "privacy_mode",
        "analysis_privacy_mode",
        "analysis_depth"
      ],
      "properties": {
        "runtime": {
          "const": "dsh"
        },
        "privacy_mode": {
          "enum": [
            "metrics_only",
            "redacted_sample",
            "local_content"
          ]
        },
        "analysis_privacy_mode": {
          "enum": [
            "metrics",
            "redacted",
            "local"
          ]
        },
        "analysis_depth": {
          "enum": [
            "conversation",
            "evidence"
          ]
        },
        "locale": {
          "enum": [
            "zh-CN",
            "en",
            "ru"
          ]
        },
        "report_timezone": {
          "type": "string",
          "description": "IANA zone name or explicit UTC offset (for example Asia/Shanghai or UTC+08:00) used for every date, hour and weekday projection and every date filter in this report; raw timestamps remain UTC instants."
        }
      }
    },
    "coverage": {
      "type": "object"
    },
    "totals": {
      "type": "object",
      "required": [
        "sessions",
        "turns",
        "tool_calls",
        "tokens"
      ],
      "properties": {
        "sessions": {
          "type": "integer",
          "minimum": 0
        },
        "turns": {
          "type": "integer",
          "minimum": 0
        },
        "tool_calls": {
          "type": "integer",
          "minimum": 0
        },
        "tool_recovery": {
          "type": "object",
          "description": "Official DSH recovery results, counted separately from confirmed failures. outcome_unknown: a recorded call whose completed outcome was not durably recorded (side effects possible). not_started: no record of the call starting. Neither status proves a tool executed or did nothing.",
          "required": [
            "outcome_unknown",
            "not_started"
          ],
          "additionalProperties": false,
          "properties": {
            "outcome_unknown": {
              "type": "integer",
              "minimum": 0
            },
            "not_started": {
              "type": "integer",
              "minimum": 0
            }
          }
        },
        "tokens": {
          "type": "object",
          "required": [
            "uncached_input_tokens",
            "cached_input_tokens",
            "output_tokens",
            "total_tokens"
          ],
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          }
        },
        "jobs": {
          "type": "object",
          "description": "Per-session job counts summed; registry outcome is not user-task completion.",
          "additionalProperties": true,
          "required": [
            "registered",
            "settled",
            "completed",
            "failed",
            "killed",
            "pending"
          ],
          "properties": {
            "registered": {
              "type": "integer",
              "minimum": 0
            },
            "settled": {
              "type": "integer",
              "minimum": 0
            },
            "completed": {
              "type": "integer",
              "minimum": 0
            },
            "failed": {
              "type": "integer",
              "minimum": 0
            },
            "killed": {
              "type": "integer",
              "minimum": 0
            },
            "pending": {
              "type": "integer",
              "minimum": 0
            },
            "inherited": {
              "type": "integer",
              "minimum": 0
            },
            "inherited_pending": {
              "type": "integer",
              "minimum": 0
            },
            "producer_reported": {
              "type": "integer",
              "minimum": 0
            },
            "unreported": {
              "type": "integer",
              "minimum": 0
            },
            "teardown": {
              "type": "integer",
              "minimum": 0
            },
            "duration_negative": {
              "type": "integer",
              "minimum": 0
            },
            "detail_present": {
              "type": "integer",
              "minimum": 0
            },
            "busy_turn_ends": {
              "type": "integer",
              "minimum": 0
            },
            "unpaired_settlement": {
              "type": "integer",
              "minimum": 0
            },
            "by_kind": {
              "type": "object",
              "additionalProperties": {
                "type": "integer",
                "minimum": 0
              }
            },
            "by_cause": {
              "type": "object",
              "additionalProperties": {
                "type": "integer",
                "minimum": 0
              }
            },
            "measurement": {
              "type": "string"
            },
            "completion_scope": {
              "type": "string"
            }
          }
        },
        "working_directory_changes": {
          "type": "integer",
          "minimum": 0,
          "description": "Own working-directory changes in the window."
        },
        "working_directory_inherited_changes": {
          "type": "integer",
          "minimum": 0,
          "description": "Inherited (fork-prefix) working-directory changes."
        },
        "cross_project_sessions": {
          "type": "integer",
          "minimum": 0,
          "description": "Sessions whose recorded trajectory covers more than one project."
        },
        "cwd_invalid_changes": {
          "type": "integer",
          "minimum": 0,
          "description": "Working-directory changes with an empty/invalid cwd, counted as integrity anomalies."
        },
        "cwd_changes_same_as_previous": {
          "type": "integer",
          "minimum": 0,
          "description": "Working-directory changes equal to the current value; the host suppresses these."
        },
        "cwd_platform_forms": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          }
        },
        "delegation": {
          "type": "object",
          "additionalProperties": true,
          "properties": {
            "dispatches": {
              "type": "integer",
              "minimum": 0
            },
            "settlements": {
              "type": "integer",
              "minimum": 0
            },
            "completion_notices": {
              "type": "integer",
              "minimum": 0
            },
            "relays_received": {
              "type": "integer",
              "minimum": 0
            },
            "relays_sent": {
              "type": "integer",
              "minimum": 0
            },
            "dispatches_by_tool": {
              "type": "object",
              "additionalProperties": {
                "type": "integer",
                "minimum": 0
              }
            },
            "measurement": {
              "type": "string"
            }
          }
        },
        "team": {
          "type": "object",
          "additionalProperties": true,
          "properties": {
            "members": {
              "type": "integer",
              "minimum": 0
            },
            "tasks": {
              "type": "integer",
              "minimum": 0
            },
            "task_transitions": {
              "type": "integer",
              "minimum": 0
            },
            "mailbox_legacy": {
              "type": "integer",
              "minimum": 0
            },
            "members_by_phase": {
              "type": "object",
              "additionalProperties": {
                "type": "integer",
                "minimum": 0
              }
            },
            "tasks_by_status": {
              "type": "object",
              "additionalProperties": {
                "type": "integer",
                "minimum": 0
              }
            },
            "measurement": {
              "type": "string"
            }
          }
        },
        "plugin_records": {
          "type": "object",
          "description": "Opaque plugin record types and counts; payloads are never retained.",
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          }
        },
        "llm_retries_performed": {
          "type": "integer",
          "minimum": 0,
          "description": "llm/retry-started attempts that actually began."
        },
        "llm_retry_chains": {
          "type": "integer",
          "minimum": 0,
          "description": "Distinct retryId chains across selected sessions."
        }
      }
    },
    "projects": {
      "type": "array"
    },
    "task_families": {
      "type": "array"
    },
    "session_summaries": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "tool_execution": {
            "type": "object",
            "required": [
              "outer_calls",
              "inner_calls",
              "outer_failures",
              "inner_failures",
              "inner_incomplete"
            ],
            "additionalProperties": false,
            "properties": {
              "outer_calls": {
                "type": "integer",
                "minimum": 0
              },
              "inner_calls": {
                "type": "integer",
                "minimum": 0
              },
              "outer_failures": {
                "type": "integer",
                "minimum": 0
              },
              "inner_failures": {
                "type": "integer",
                "minimum": 0
              },
              "inner_incomplete": {
                "type": "integer",
                "minimum": 0
              }
            }
          },
          "tool_recovery": {
            "type": "object",
            "description": "Official recovery results for this session; same contract as totals.tool_recovery. Never counted as tool failures.",
            "required": [
              "outcome_unknown",
              "not_started"
            ],
            "additionalProperties": false,
            "properties": {
              "outcome_unknown": {
                "type": "integer",
                "minimum": 0
              },
              "not_started": {
                "type": "integer",
                "minimum": 0
              }
            }
          },
          "child_sessions": {
            "type": "integer",
            "minimum": 0
          },
          "jobs": {
            "type": "object",
            "description": "Background-job lifecycle (DSH 0.2.1-rc.2). A registry settlement is not user-task completion or resource release.",
            "required": [
              "registered",
              "settled",
              "completed",
              "failed",
              "killed",
              "pending",
              "inherited"
            ],
            "properties": {
              "registered": {
                "type": "integer",
                "minimum": 0
              },
              "settled": {
                "type": "integer",
                "minimum": 0
              },
              "completed": {
                "type": "integer",
                "minimum": 0
              },
              "failed": {
                "type": "integer",
                "minimum": 0
              },
              "killed": {
                "type": "integer",
                "minimum": 0
              },
              "pending": {
                "type": "integer",
                "minimum": 0
              },
              "inherited": {
                "type": "integer",
                "minimum": 0
              },
              "inherited_pending": {
                "type": "integer",
                "minimum": 0
              },
              "producer_reported": {
                "type": "integer",
                "minimum": 0
              },
              "unreported": {
                "type": "integer",
                "minimum": 0
              },
              "teardown": {
                "type": "integer",
                "minimum": 0
              },
              "duration_negative": {
                "type": "integer",
                "minimum": 0
              },
              "detail_present": {
                "type": "integer",
                "minimum": 0
              },
              "busy_turn_ends": {
                "type": "integer",
                "minimum": 0
              },
              "unpaired_settlement": {
                "type": "integer",
                "minimum": 0
              },
              "by_kind": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "by_cause": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "items": {
                "type": "array",
                "maxItems": 20,
                "items": {
                  "type": "object",
                  "properties": {
                    "job_id": {
                      "type": "string"
                    },
                    "kind": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "running",
                        "completed",
                        "failed",
                        "killed"
                      ]
                    },
                    "cause": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "enum": [
                        "producer",
                        "kill",
                        "teardown",
                        null
                      ]
                    },
                    "settled": {
                      "type": "boolean"
                    },
                    "producer_reported": {
                      "type": [
                        "boolean",
                        "null"
                      ]
                    },
                    "inherited": {
                      "type": "boolean"
                    },
                    "duration_ms": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "minimum": 0
                    },
                    "label": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "working_directory": {
            "type": "object",
            "description": "Labelled cwd trajectory. The immutable header cwd remains the origin/filter criterion; raw paths are not exposed in redacted/metrics modes.",
            "properties": {
              "changes": {
                "type": "integer",
                "minimum": 0
              },
              "inherited_changes": {
                "type": "integer",
                "minimum": 0
              },
              "trajectory": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "projects_visited": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "cross_project": {
                "type": "boolean"
              },
              "origin_label": {
                "type": "string"
              },
              "effective_at_cut": {
                "type": "string"
              },
              "own_labels": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "inherited_labels": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "platform_forms": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "changes_same_as_previous": {
                "type": "integer",
                "minimum": 0
              },
              "invalid_changes": {
                "type": "integer",
                "minimum": 0
              },
              "relative_changes": {
                "type": "integer",
                "minimum": 0
              },
              "attribution": {
                "type": "string"
              }
            }
          },
          "delegation": {
            "type": "object",
            "description": "Dispatch/settlement/relay evidence; delivery and parent turn end are not completion.",
            "properties": {
              "dispatches": {
                "type": "integer",
                "minimum": 0
              },
              "dispatches_by_tool": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "settlements": {
                "type": "integer",
                "minimum": 0
              },
              "completion_notices": {
                "type": "integer",
                "minimum": 0
              },
              "relays_received": {
                "type": "integer",
                "minimum": 0
              },
              "relays_sent": {
                "type": "integer",
                "minimum": 0
              },
              "workflow_runs_started": {
                "type": "integer",
                "minimum": 0
              },
              "workflow_runs_ended": {
                "type": "integer",
                "minimum": 0
              },
              "workflow_agents_started": {
                "type": "integer",
                "minimum": 0
              },
              "workflow_agents_ended": {
                "type": "integer",
                "minimum": 0
              },
              "measurement": {
                "type": "string"
              }
            }
          },
          "team": {
            "type": "object",
            "description": "Last-wins Team roster/task snapshots; not Lead task completion.",
            "properties": {
              "members": {
                "type": "integer",
                "minimum": 0
              },
              "members_by_phase": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "tasks": {
                "type": "integer",
                "minimum": 0
              },
              "tasks_by_status": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "task_transitions": {
                "type": "integer",
                "minimum": 0
              },
              "mailbox_legacy": {
                "type": "integer",
                "minimum": 0
              }
            }
          },
          "subagent": {
            "type": [
              "object",
              "null"
            ],
            "description": "First child-owned subagent descriptor; absent when the session is not a subagent.",
            "properties": {
              "version": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "mode": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "provider": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "agent_provider": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "agent_model": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "token_measurement": {
            "type": "object",
            "description": "Provenance of token counters. `input_tokens` and `total_tokens` are derived sums.",
            "properties": {
              "input_tokens": {
                "type": "string",
                "enum": [
                  "recorded",
                  "derived"
                ]
              },
              "uncached_input_tokens": {
                "type": "string",
                "enum": [
                  "recorded",
                  "derived"
                ]
              },
              "cached_input_tokens": {
                "type": "string",
                "enum": [
                  "recorded",
                  "derived"
                ]
              },
              "output_tokens": {
                "type": "string",
                "enum": [
                  "recorded",
                  "derived"
                ]
              },
              "reasoning_output_tokens": {
                "type": "string",
                "enum": [
                  "recorded",
                  "derived"
                ]
              },
              "cache_write_tokens": {
                "type": "string",
                "enum": [
                  "recorded",
                  "derived"
                ]
              },
              "total_tokens": {
                "type": "string",
                "enum": [
                  "recorded",
                  "derived"
                ]
              },
              "usage_samples": {
                "type": "integer",
                "minimum": 0
              },
              "usage_total_samples": {
                "type": "integer",
                "minimum": 0
              }
            }
          }
        }
      }
    },
    "excerpts": {
      "type": "array"
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "semantic_analysis": {
      "type": "object"
    },
    "semantic_evidence": {
      "type": "array"
    },
    "semantic_facets": {
      "type": "array"
    }
  }
}