# Frame Contract Schema — Layer 3 Domain Entity Type
# KNO Schema Version: 0.1.0
# Status: Draft
# Last Updated: 2026-08-04
#
# A frame contract bundles a view schema, a verb set, an addressing
# regime, and a consistency class (RFC-023 §3): it governs how a
# participant sees and mutates an act. Frame selection is content
# negotiation; a task, an email, and a chat message are the SAME act
# entity under different frames. Contracts declare intake as well as
# render: a frame without an intake mapping for a verb cannot receive
# that verb — declared, not discovered.
#
# THREE-GATE (kno-foundational-principles § 0.6):
# - Gate 1 (Distinctness): PASS — a frame contract is a projection
#   contract over acts (verb legality + view shape + addressing +
#   consistency), not a document, notice, or capability; no existing
#   schema declares verb-intake legality.
# - Gate 2 (Reusability): PASS by design — RFC-023 anticipates message,
#   task, notice-broadcast, and inbox frames; M0 ships `message`, and
#   the sweep's catalog names the successors.
# - Gate 3 (Clarity): PASS — the frame mechanism is exactly what lets
#   ONE act schema replace N per-kind schemas; the contract entity is
#   the declared boundary that keeps it so.
#
# =============================================================================
# @kno:manifest
# =============================================================================
$schema: kno@0.0.9
id: 01KZ786QS7EVDPV8TRNYEE339G
slug: frame-contract-schema
type: spec
version: 0.1.0

title: "Frame Contract Schema"
purpose: |
  Define the schema for frame contracts — the entity that carries
  everything distinguishing one "kind" of communication from another
  (RFC-023 §3): addressing regime, lifecycle contract (legal verbs and
  their state machine), and consistency class, plus the view schema a
  participant renders.

status: draft
created: "2026-08-04"
authors:
  - "Possibility Contributors"

provenance:
  origin:
    id: 01KZ786QS7EVDPV8TRNYEE339G
    timestamp: "2026-08-04T11:30:00Z"
    emerged_from:
      - kno://content/rfcs/023-communicative-acts
    tool: ai-assisted-authoring
    issue: "forge#3376"

taxonomy:
  topics:
    - communicative-acts
    - frames
    - messaging
  keywords:
    - frame
    - contract
    - verb
    - addressing
    - consistency

relationships:
  conforms_to:
    - xri: "kno://specs/kno-spec"
      reason: "RFC-001 defines kno@0.0.9 schema"
  depends_on:
    - xri: "pspace://rfc:rfc-023-communicative-acts"
      reason: "RFC-023 §3 defines the three dimensions frame contracts carry"
    - xri: "kno://specs/act-schema"
      reason: "Frames govern how participants see and mutate acts"

# Frame contracts are public reference knowledge (RFC-023 §2.2 —
# four-surface contract with the act schema).
visibility: public

quality:
  completeness: 0.6
  review_status: draft

_history:
  retention: full
  format: snapshot
  versions:
    - version: "0.1.0"
      date: "2026-08-04"
      author: "Possibility Contributors"
      summary: "Initial draft — frame-contract fields (view schema, verb set with intake/render mappings, addressing regime, consistency class) + the M0 message-frame instance inline as the canonical example"

fields:
  id:
    type: string
    format: ulid
    required: true
    description: "ULID of this frame contract (immutable, RFC-013)"

  slug:
    type: string
    required: true
    description: "Frame name referenced by act records' `frame` field (e.g. `message`)"

  type:
    type: string
    enum: [ frame-contract ]
    required: true
    description: "Top-level kind discriminator"

  version:
    type: string
    format: semver
    required: true
    description: |
      Contract version. New verbs or intake-mapping changes require a
      version bump (verb matrix rule 4: declared, not discovered).

  addressing_regime:
    type: string
    enum: [ open-world-envelope, membership-bound-container, assignee-with-overlay-writers ]
    required: true
    description: "RFC-023 §3 dimension 1 — who can be addressed and who may write"

  consistency_class:
    type: string
    enum: [ store-and-forward, live-subscribe, mutable-graph ]
    required: true
    description: "RFC-023 §3 dimension 3 — the delivery/read consistency participants can assume"

  verbs:
    type: array
    required: true
    min_items: 1
    description: |
      The lifecycle contract (dimension 2): which verbs are legal under
      this frame, each with intake and render declarations. A verb
      absent from this list cannot be received by acts in this frame.
      Verb semantics and reference rules live in the per-verb reference
      matrix (docs/architecture/messaging-verb-reference-matrix.md).
    items:
      type: object
      required_fields:
        - verb
        - intake
        - render
      example: |
        - verb: Ack
          intake: audience-member    # who may send it
          render: processed-badge    # how surfaces show it

  view_schema:
    type: object
    required: true
    description: |
      What a participant sees: the projection fields surfaces render.
      References act-schema fields; never widens the signed scope.

# =============================================================================
# CANONICAL INSTANCE — the M0 message frame (ships with the mechanism)
# =============================================================================
canonical_instance:
  slug: message
  version: "0.1.0"
  addressing_regime: open-world-envelope
  consistency_class: store-and-forward
  verbs:
    - verb: Create
      intake: authenticated-principal
      render: inbox-entry
    - verb: Deliver
      intake: service-egress
      render: delivery-receipt
    - verb: Ack
      intake: audience-member
      render: processed-badge
    - verb: Route
      intake: authorized-router
      render: hop-entry
    - verb: Resolve
      intake: chain-participant
      render: resolution-notice
  view_schema:
    fields:
      - actor
      - audience
      - body
      - context.refs
      - context.chain
      - published
      - acked