# Perception Domain Schema — Layer 3 Vocabulary Entity
# KNO Schema Version: 0.1.0
#
# Layer 3 schema for declaring agent perception domains as first-class
# entities. Each instance in `content/perception-domains/*.kno` defines
# one domain that agent cards may reference in their `perception.domains[]`
# block (per agent-card-schema.kno v0.2.0+).
#
# DOMAIN: Vocabulary of signal types / data sources that agents can perceive
# PURPOSE: Make perception-domains an open, file-driven enum. Adding a new
#          domain = adding a new .kno file (no schema change required).
#
# KEY CONCEPT: This is a vocabulary schema. Each entity instance is a *term
# definition*, not an instance of behaviour. The collection of all
# perception-domain entities is the perception vocabulary; agents subscribe
# to terms in it via their cards.
#
# DESIGN DECISIONS:
#   - DD-PD-01: Open enum via filesystem. Drift-guard test asserts every
#     `perception.domains[]` slug in any agent card has a corresponding
#     `content/perception-domains/<slug>.kno` file.
#   - DD-PD-02: Categories (data-source, signal-type, structural) are
#     advisory only; not part of the routing/projection mechanism.
#   - DD-PD-03: Sources field documents *what* a domain covers (which
#     files / endpoints / streams) so new agents can decide which domains
#     match their needs without reading schema source.
#
# Created for: M22-P2 F1 (#849), per #2018 futro carry-forward A-3.

# =============================================================================
# SCHEMA DECLARATION
# =============================================================================
$schema: kno@0.0.9

# =============================================================================
# BASIC TIER
# =============================================================================
id: 01KQ3P2VZMKDPPZ7YYATFCTF7R
slug: perception-domain-schema
type: spec
version: 0.1.0

# =============================================================================
# STANDARD TIER
# =============================================================================
title: "Perception Domain Schema"
purpose: |
  Schema for declaring agent perception domains as first-class .kno
  entities. Each instance describes one signal type or data source that
  one or more agents perceive.

  **Why a vocabulary schema?**

  M22 agent cards (v0.2.0+) declare `perception.domains[]` — a list of
  domain slugs the agent monitors. Without a schema for those domains,
  the slugs are free-form strings: agents can typo, two agents can use
  different names for the same concept, and the routing layer (F3) has
  no canonical list to validate against.

  Promoting perception-domain to a first-class entity type closes that
  gap:

  | Concern | Without vocabulary schema | With vocabulary schema |
  |---|---|---|
  | Domain typo | Silent — agent declares `entity_health`; routing dispatches to nothing | Drift-guard test catches missing `content/perception-domains/entity_health.kno` |
  | Domain consolidation | Two slugs (`api-surface`, `apis`) coexist; routing splits | Two .kno files; eventually one `supersedes` the other |
  | Domain documentation | Lives in agent card comments, scattered | Lives in the domain entity itself, single source |
  | Adding a domain | Schema change required (closed enum) | Add a .kno file (open enum) |

  **What goes in a perception-domain entity?**

  Each domain entity declares:
  - `slug` — the canonical identifier referenced by agent cards
  - `name` — human-readable name
  - `category` — advisory grouping (data-source, signal-type, structural)
  - `description` — what this domain covers
  - `sources` — concrete file globs, endpoints, or streams that comprise the
    domain (helps new agents decide if the domain matches their needs)
  - `subscribed_by` — OPTIONAL list of agent slugs that subscribe (for
    documentation; the canonical reverse projection is computed at runtime)

  **Drift-guard contract:**

  The test in `services/pspace-api/src/lib/__tests__/perception-domains-drift-guard.test.ts`
  enforces three invariants:
  1. Every slug in any agent card's `perception.domains[]` resolves to a
     `content/perception-domains/<slug>.kno` file.
  2. Every perception-domain .kno file is referenced by at least one
     agent card (no orphaned vocabulary).
  3. Every perception-domain .kno file conforms to this schema.

  **Layer 3 position:** This is a peer of `role-schema.kno`,
  `capability-schema.kno`, etc. — Layer 3 reusable entity type, NOT a
  document extension.

# =============================================================================
# RICH TIER — Provenance & Taxonomy
# =============================================================================
provenance:
  origin:
    id: 01KQ3P2VZMKDPPZ7YYATFCTF7R
    timestamp: "2026-04-25T22:30:00Z"
    tool: manual
    issue: "https://github.com/PossibilityTruthy/possibility-space/issues/849"

taxonomy:
  topics:
    - agents
    - perception
    - vocabulary
    - m22
  keywords:
    - perception-domain
    - agent-card
    - signal
    - data-source
    - capability-routing

# =============================================================================
# RICH TIER — Relationships
# =============================================================================
relationships:
  related_to:
    - xri: "kno://specs/agent-card-schema"
      reason: "agent-card.perception.domains[] holds slug references to instances of this schema"
    - xri: "kno://specs/role-schema"
      reason: "Roles describe what an actor IS; perception domains describe what an actor SEES"
    - xri: "kno://specs/capability-schema"
      reason: "Perception domains are a capability dimension distinct from skill/tool capabilities"

quality:
  completeness: 0.9
  last_reviewed: "2026-04-25"
  review_status: draft

# =============================================================================
# HISTORY
# =============================================================================
_history:
  version: 1
  created: "2026-04-25T22:30:00Z"
  created_by: "claude"
  modified: "2026-04-25T22:30:00Z"
  modified_by: "claude"

# =============================================================================
# SPECIFICATION
# =============================================================================
spec:
  status: Draft

  changelog:
    - version: "0.1.0"
      date: "2026-04-25"
      changes:
        - "Initial creation for M22-P2 F1 (#849)"
        - "Open-enum vocabulary pattern: new domains added as .kno files"
        - "Drift-guard contract documented (3 invariants)"

  schema:
    type: object
    required:
      - id
      - slug
      - name
      - category
      - description
    properties:
      $schema:
        type: string
        const: "perception-domain@0.1.0"
        description: "Schema declaration"

      id:
        type: string
        description: "Unique identifier (ULID) for this perception domain"
        examples:
          - "01KQ3P2VZMKDPPZ7YYATFCTF7R"

      slug:
        type: string
        description: |
          Canonical kebab-case identifier. The value referenced by agent
          cards' `perception.domains[]` array. MUST equal the filename
          (without `.kno` extension) so the drift-guard can resolve
          references via path lookup.
        examples:
          - "schemas"
          - "api-surface"
          - "drift-surfaces"
          - "entity-health"

      type:
        type: string
        const: "perception-domain"

      version:
        type: string
        description: "Semver of the domain definition (rare to change, but supported)"
        examples:
          - "0.1.0"

      name:
        type: string
        description: "Human-readable name"
        examples:
          - "Schemas"
          - "Drift Surfaces"

      category:
        type: string
        enum:
          - data-source
          - signal-type
          - structural
        description: |
          Advisory grouping (does NOT affect routing or projection):
          - data-source: a concrete data feed (filesystem, database, API)
          - signal-type: a derived event class (errors, latencies, deltas)
          - structural: a graph or relationship view (ontology, dependencies)

      description:
        type: string
        description: "What this domain covers. Plain English; CommonMark may be used."

      sources:
        type: array
        description: |
          Concrete sources comprising this domain. File globs, endpoint
          patterns, stream names. Helps new agents decide if the domain
          matches their needs.
        items:
          type: object
          required:
            - kind
            - reference
          properties:
            kind:
              type: string
              enum:
                - filesystem
                - http
                - stream
                - database
                - kno-collection
            reference:
              type: string
              description: "Path glob, URL, stream ID, table name, etc."
              examples:
                - "specs/*.kno"
                - "/.well-known/integration"
                - "activities-stream"
                - "content/agents/*.kno"

      subscribed_by:
        type: array
        description: |
          Optional documentation of which agents subscribe to this domain.
          NOT the canonical reverse projection — the runtime
          `getAgentsForDomain(slug)` function is the canonical answer
          (computed by scanning all agent cards). This array is
          informational and may go stale; treat as a hint, not source
          of truth.
        items:
          type: string
          description: "Agent slug (matches an entity in content/agents/)"
          examples:
            - "drift-detective"
            - "entity-lifecycle-guardian"

      supersedes:
        type: string
        description: |
          Optional XRI reference to a perception-domain entity this one
          replaces. Used for vocabulary consolidation: when two domains
          should merge, mark the redundant one with `supersedes` pointing
          at the canonical one. Drift-guard MAY warn on references to
          superseded domains.

# =============================================================================
# EXAMPLES
# =============================================================================
examples:
  - title: "Schemas perception domain"
    description: "All .kno schema files in specs/"
    content: |
      $schema: perception-domain@0.1.0
      id: 01KQ3P2WXXXXXXXXXXXXXXXXXX
      slug: schemas
      type: perception-domain
      version: "0.1.0"
      name: "Schemas"
      category: data-source
      description: |
        All Layer 1-3 schema definitions in specs/. Agents perceiving
        this domain notice schema additions, version bumps, and field
        changes.
      sources:
        - kind: filesystem
          reference: "specs/*.kno"
      subscribed_by:
        - integration-schema-analyzer
        - schema-compliance-agent

  - title: "Drift surfaces perception domain"
    description: "SSOT/projection pairs that must stay aligned"
    content: |
      $schema: perception-domain@0.1.0
      id: 01KQ3P2WYYYYYYYYYYYYYYYYY
      slug: drift-surfaces
      type: perception-domain
      version: "0.1.0"
      name: "Drift Surfaces"
      category: structural
      description: |
        SSOT/projection pairs across the platform that must stay aligned.
        Each surface is a (canonical-source, derived-projection,
        guard-or-monitor) triple. Drift Detective (A13, #2013) perceives
        this domain.
      sources:
        - kind: filesystem
          reference: "**/*-drift-guard.test.ts"
        - kind: filesystem
          reference: "content/drift-surfaces/*.kno"
      subscribed_by:
        - drift-detective