{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "PropertyJourneyState",
  "description": "Shared per-property state spine written to properties/<slug>/.property/journey.json. One file per property; never contains another property's data (SKILL.md Principle 2). The orchestrator is the sole writer of stage and contract; each advisor writes only its own section plus openRisks; missing values stay null (never invented). Every write updates `updated` and appends to `versions`.",
  "type": "object",
  "additionalProperties": false,
  "required": ["property", "stage", "updated"],
  "properties": {
    "property": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "address": { "type": ["string", "null"] },
        "slug": { "type": ["string", "null"] },
        "reportPrefix": { "type": ["string", "null"], "description": "Short subdivision/community or house name prefixed to every report/dashboard filename (SKILL.md naming rule)." },
        "purchasePrice": { "type": ["number", "null"] },
        "loanAmount": { "type": ["number", "null"], "description": "Planned loan amount from the contract/financing addendum. Read by the loan advisor." },
        "replacementCost": { "type": ["number", "null"], "description": "Dwelling replacement cost (structure only, land excluded). Read by the insurance advisor." },
        "county": { "type": ["string", "null"] }
      }
    },
    "stage": {
      "type": "string",
      "enum": ["readiness", "discovery", "investigation", "neighborhood-value", "financing", "offer-contract", "option-period", "insurance", "closing-prep", "post-closing"],
      "description": "Current journey stage. Orchestrator-owned."
    },
    "firstTimeBuyer": { "type": "boolean" },
    "contract": {
      "type": "object",
      "additionalProperties": false,
      "description": "Controlling terms from the latest fully executed contract. Orchestrator is the sole writer; advisors read but never invent these.",
      "properties": {
        "effectiveDate": { "type": ["string", "null"] },
        "optionDeadline": { "type": ["string", "null"] },
        "financingApprovalDate": { "type": ["string", "null"] },
        "closingDate": { "type": ["string", "null"] },
        "maxRate": { "type": ["number", "null"], "description": "Third Party Financing Addendum maximum interest rate. Read by the loan advisor." },
        "financingType": { "type": ["string", "null"], "description": "Allowed financing type (Conventional/FHA/VA/USDA/Jumbo). Read by the loan advisor." },
        "asIs": { "type": ["boolean", "null"] },
        "status": { "type": "string", "enum": ["verified", "unverified"] }
      }
    },
    "value": {
      "type": "object",
      "additionalProperties": false,
      "description": "Written by the neighborhood advisor.",
      "properties": {
        "ran": { "type": "boolean" },
        "estimatedValue": { "type": ["number", "null"] },
        "estimatedValueBasis": { "type": ["string", "null"], "enum": ["closed-comps", "cad-benchmark", "street-median", null], "description": "What estimatedValue represents. A CAD mass-appraisal benchmark is never a closed-sale appraisal." },
        "cushion": { "type": ["number", "null"] }
      }
    },
    "loan": {
      "type": "object",
      "additionalProperties": false,
      "description": "Written by the loan advisor.",
      "properties": {
        "ran": { "type": "boolean" },
        "bestLender": { "type": ["string", "null"] },
        "rate": { "type": ["number", "null"] },
        "monthlyPITI": { "type": ["number", "null"] },
        "escrowMonthly": { "type": ["number", "null"] },
        "cashToClose": { "type": ["number", "null"] },
        "maxRateFlag": { "type": ["boolean", "null"] }
      }
    },
    "insurance": {
      "type": "object",
      "additionalProperties": false,
      "description": "Written by the insurance advisor.",
      "properties": {
        "ran": { "type": "boolean" },
        "carrier": { "type": ["string", "null"] },
        "annualPremium": { "type": ["number", "null"] },
        "roofSettlement": { "type": ["string", "null"], "enum": ["RCV", "ACV", null] },
        "deductibles": { "type": ["string", "null"] }
      }
    },
    "inspection": {
      "type": "object",
      "additionalProperties": false,
      "description": "Written by the inspection advisor.",
      "properties": {
        "ran": { "type": "boolean" },
        "exposureBase": { "type": ["number", "null"] },
        "sellerScope": { "type": ["string", "null"] },
        "buyerCredit": { "type": ["number", "null"], "description": "Seller credit. Affects loan cash-to-close (lender-capped)." },
        "priceReduction": { "type": ["number", "null"], "description": "Negotiated price cut. Changes the loan amount, not just cash-to-close." },
        "dealBreaker": { "type": "string", "enum": ["no", "conditional", "yes", "pending", "unknown_pending_specialist"] }
      }
    },
    "openRisks": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Appendable by any advisor plus the orchestrator."
    },
    "updated": { "type": "string", "description": "ISO-8601 timestamp of the most recent write." },
    "versions": {
      "type": "array",
      "description": "Append-only audit trail so reconciliation never silently discards a prior state.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "at": { "type": "string" },
          "by": { "type": "string", "description": "orchestrator | neighborhood-advisor | comparison-advisor | loan-advisor | insurance-advisor | inspection-advisor" },
          "note": { "type": "string" }
        }
      }
    }
  }
}