# Environment Schema — Layer 3 Vocabulary Entity
# KNO Schema Version: 0.1.0
#
# Layer 3 schema for declaring deployment environments as first-class
# entities. Each instance in `content/environments/*.kno` defines one
# environment that agent blueprints may reference in their
# `deployment.environments[]` block (per agent-blueprint-schema.kno
# v0.2.0+).
#
# DOMAIN: Vocabulary of deployment-target environments
# PURPOSE: Make environments an open, file-driven enum. Adding a new
#          environment = adding a new .kno file (no schema change required).
#
# KEY CONCEPT: This is a vocabulary schema (mirrors perception-domain-schema).
# Each entity instance is a *term definition*, not an instance of a running
# environment. The collection of all environment entities is the canonical
# enum that agent blueprints, runtime filters, and deploy gates resolve
# slugs against.
#
# DESIGN DECISIONS (see docs/planning/agent-environment-scoping/agent-environment-scoping-spec.md §5):
#   - DD-DEP-02: Registry pattern mirrors perception-domain. Open enum via
#     filesystem; drift-guard test asserts every `deployment.environments[]`
#     slug in any blueprint resolves to a `content/environments/<slug>.kno`.
#   - DD-DEP-03: Default-allow semantics — a blueprint with no
#     `deployment.environments[]` (or an empty array) is allowed everywhere.
#     Only an explicit, non-empty list scopes the blueprint.
#   - DD-DEP-04: `local` and `dev` are distinct registry entries even
#     though both are non-production. `local` = developer machine /
#     devcontainer; `dev` = a shared dev environment if/when one exists.
#     Both are needed because blueprints may want to target one but not
#     the other.
#
# Created for: M22 #2030 Phase 2 (per agent-environment-scoping-spec.md §6).

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

# =============================================================================
# BASIC TIER
# =============================================================================
id: 01KRH60HAQCJX9Q9XSRED75N50
slug: environment-schema
type: spec
version: 0.1.0

# =============================================================================
# STANDARD TIER
# =============================================================================
title: "Environment Schema"
purpose: |
  Schema for declaring deployment environments as first-class .kno
  entities. Each instance describes one deployment target that agent
  blueprints may scope themselves to via `deployment.environments[]`.

  **Why a vocabulary schema?**

  Agent blueprints (v0.2.0+, landing in #2030 Phase 3) declare
  `deployment.environments[]` — a list of environment slugs the
  blueprint is permitted to run in. Without a schema for those
  environments, the slugs are free-form strings: blueprints can
  typo, two blueprints can use different names for the same target
  (`prod` vs `production`), and the runtime filter and deploy gate
  have no canonical list to validate against.

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

  | Concern | Without vocabulary schema | With vocabulary schema |
  |---|---|---|
  | Environment typo | Silent — blueprint declares `prod`; runtime filter excludes it from `production` | Drift-guard test catches missing `content/environments/prod.kno` |
  | Naming inconsistency | `prod` and `production` both appear; gate accepts both | One canonical slug per environment; the other fails resolution |
  | Environment documentation | Lives in instructions or scattered comments | Lives in the environment entity itself, single source |
  | Adding a new tier (e.g. `preview`) | Schema change required (closed enum) | Add a .kno file (open enum) |

  **What goes in an environment entity?**

  Each environment entity declares:
  - `slug` — the canonical identifier referenced by blueprints, runtime
    helpers, and deploy gates (matches `PSPACE_ENV` value at runtime)
  - `name` — human-readable name
  - `tier` — advisory grouping (development | hosted-non-production | production)
  - `description` — what this environment is, who uses it, and what the
    posture is (data tier, public exposure, etc.)
  - `pspace_env_value` — the exact string this environment expects
    `PSPACE_ENV` to be set to. Usually equal to `slug`, but recorded
    explicitly so the resolution contract is unambiguous.

  **Drift-guard contract:**

  The test in
  `services/pspace-api/src/lib/__tests__/environments-drift-guard.test.ts`
  enforces three invariants:
  1. Every slug referenced by any agent blueprint's
     `deployment.environments[]` resolves to a
     `content/environments/<slug>.kno` file.
  2. Every environment .kno file conforms to this schema (required
     fields present, slug matches filename).
  3. The set of `pspace_env_value` values is a subset of what the deploy
     scripts actually accept (see `scripts/start-pspace.sh` etc.) — i.e.
     no environment in the registry corresponds to a value the platform
     can't actually be deployed at.

  Vocabulary coverage (every environment file is referenced) is
  intentionally NOT enforced: the registry is the source of truth, and
  it is normal for an environment to exist before any blueprint scopes
  to it. Blueprints with no `deployment.environments[]` (default-allow,
  DD-DEP-03) implicitly cover every registry entry.

  **Layer 3 position:** Peer of `perception-domain-schema.kno`,
  `role-schema.kno`, etc. — Layer 3 reusable vocabulary entity type.

# =============================================================================
# RICH TIER — Provenance & Taxonomy
# =============================================================================
provenance:
  origin:
    id: 01KRH60HAQCJX9Q9XSRED75N50
    timestamp: "2026-05-13T00:00:00Z"
    tool: manual
    issue: "https://github.com/PossibilityTruthy/possibility-space/issues/2030"

taxonomy:
  topics:
    - agents
    - deployment
    - environments
    - vocabulary
    - m22
  keywords:
    - environment
    - deployment-target
    - agent-blueprint
    - pspace-env
    - capability-routing

# =============================================================================
# RICH TIER — Relationships
# =============================================================================
relationships:
  related_to:
    - xri: "kno://specs/agent-blueprint-schema"
      reason: "agent-blueprint.deployment.environments[] holds slug references to instances of this schema"
    - xri: "kno://specs/perception-domain-schema"
      reason: "Sibling Layer 3 vocabulary schema using the same open-enum-via-filesystem pattern"

quality:
  completeness: 0.9
  last_reviewed: "2026-05-13"
  review_status: draft

# =============================================================================
# HISTORY
# =============================================================================
_history:
  version: 1
  created: "2026-05-13T00:00:00Z"
  created_by: "claude"
  modified: "2026-05-13T00:00:00Z"
  modified_by: "claude"

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

  changelog:
    - version: "0.1.0"
      date: "2026-05-13"
      changes:
        - "Initial creation for M22 #2030 Phase 2 (per agent-environment-scoping-spec.md §6)"
        - "Open-enum vocabulary pattern mirrors perception-domain-schema"
        - "Drift-guard contract documented (3 invariants; vocabulary coverage NOT required, per DD-DEP-03 default-allow)"

  schema:
    type: object
    required:
      - id
      - slug
      - name
      - tier
      - description
      - pspace_env_value
    properties:
      $schema:
        type: string
        const: "environment@0.1.0"
        description: "Schema declaration"

      id:
        type: string
        description: "Unique identifier (ULID) for this environment"
        examples:
          - "01KRH60HAVXHBC6S5RFJ9WK2PZ"

      slug:
        type: string
        description: |
          Canonical kebab-case identifier. The value referenced by agent
          blueprints' `deployment.environments[]` array. MUST equal the
          filename (without `.kno` extension) so the drift-guard can
          resolve references via path lookup.
        examples:
          - "local"
          - "dev"
          - "staging"
          - "production"

      type:
        type: string
        const: "environment"

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

      name:
        type: string
        description: "Human-readable name"
        examples:
          - "Local Development"
          - "Production"

      tier:
        type: string
        enum:
          - development
          - hosted-non-production
          - production
        description: |
          Advisory grouping (does NOT affect routing or projection):
          - development: developer machine, devcontainer, ephemeral local stacks
          - hosted-non-production: shared dev/staging/preview environments
          - production: customer-facing environments

      description:
        type: string
        description: "What this environment is, who uses it, and the posture (data tier, public exposure, etc.). Plain English; CommonMark may be used."

      pspace_env_value:
        type: string
        description: |
          The exact string this environment expects `PSPACE_ENV` to be set
          to. Usually equal to `slug`, but recorded explicitly so the
          resolution contract is unambiguous and the drift-guard can verify
          alignment with deploy-script-accepted values.
        examples:
          - "local"
          - "dev"
          - "staging"
          - "production"

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

# =============================================================================
# END OF SPEC
# =============================================================================