# bundle.schema.yaml — THE schema (machine-checkable, JSON Schema 2020-12 in yaml)
# a bundle validates against this or it is not a bundle. markdown carries nothing.
$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "playground:bundle/v0"
type: object
required: [head, names, claims, derive, scenarios]
additionalProperties: false
properties:

  head:
    type: object
    required: [name, sha, lineage, organs]
    additionalProperties: false
    properties:
      name:    { type: string, minLength: 1 }
      sha:     { type: string, pattern: "^[0-9a-f]{16,64}$" }   # md5/sha over names+claims+derive+scenarios, stamped at click
      lineage: { type: string }                                  # parent sha, or "genesis"
      carrier: { type: string }                                  # informative only — bundles are carrier-neutral
      organs:  { type: object }                                  # counts, informative

  names:
    type: object
    required: [entities]
    additionalProperties: false
    properties:
      entities:
        type: object
        minProperties: 1
        additionalProperties:
          type: object
          required: [key, fields]
          properties:
            key:    { type: string }
            fields: { type: object, additionalProperties: true }
      relations: { type: object, additionalProperties: { type: string } }
      acts:
        type: object
        additionalProperties:
          type: object
          required: [of, outcomes]
          properties:
            of:       { type: string }
            to:       { type: string }
            outcomes: { type: array, items: { type: string }, minItems: 1 }

  claims:
    type: array
    minItems: 0
    items:
      type: object
      required: [id, origin, forall, holds]     # origin mandatory: no provenance, no parse
      additionalProperties: false
      properties:
        id:     { type: string, pattern: "^c-[0-9]+$" }
        origin: { type: string, minLength: 1 }  # world source path#anchor, or scenarios/<id> that bred it
        forall: { type: object, minProperties: 1, additionalProperties: { type: string } }
        when:   { type: string }                # guard expression over names; absent = unconditional
        holds:  { type: string, minLength: 1 }  # consequence expression; dies whole on one contrary trace
        # deliberately absent: confidence, weight, priority, severity — no precedence operator exists

  derive:
    type: array
    items:
      type: object
      required: [id, def]
      additionalProperties: false
      properties:
        id:  { type: string, pattern: "^d-[0-9]+$" }
        def: { type: string, minLength: 1 }     # pure function over names; computed, never asked of a model

  scenarios:
    type: array                                  # append-only; physics rejects any diff that edits or removes
    items:
      type: object
      required: [id, born, setup, red]
      additionalProperties: false
      properties:
        id:   { type: string, pattern: "^s-[0-9]+$" }
        born: { type: object, required: [date, red_on], properties: { date: { type: string }, red_on: { type: string } } }
        setup:
          type: object
          required: [world]
          properties:
            world: { type: object, minProperties: 1 }   # instances conforming to names.entities
            turn:  { type: string }                     # caller text, when the contact is conversational
        red: { type: string, minLength: 1 }             # the diff-class that must stay absent
        # deliberately absent: expected answer — what should happen is the claims' job (wheel ≠ pawl)