# Bundle Definition Schema — Layer 3 Entity Type
# KNO Schema Version: 0.2.0
# CHANGELOG:
#   0.2.0 (M52 P4.1, #2139): Add `visibility: public` collection default per REQ-18.
#                            Bundle definitions are public reference knowledge consumed
#                            via the four-surface contract.
#
# A Bundle Definition declares which .kno surfaces (and at what filters)
# compose a downloadable reference bundle. The bundle ARTIFACT (zip) is
# generated by a thin transformation (P10) over .kno sources; this schema
# describes the COMPOSITION rules, not the artifact itself.
#
# EXTENDS: document-schema.kno (which composes identity, history, quality)
#
# USE CASES:
# - Persona-scoped reference bundles (public, creator, admin)
# - Future: per-possibility tenant bundles, audit-time snapshots
#
# THREE-GATE TEST (kno-foundational-principles.md § 0.6):
# - Distinctness: PASS — bundles have no prose body; structural fields are
#   surfaces[] + filters{} + persona, fundamentally different from documents
# - Reusability: PASS — 3 instances at launch (public/creator/admin), with
#   room for tenant-scoped variants
# - Clarity: PASS — first-class named fields beat overloading document with
#   purpose: reference-bundle and ad-hoc metadata stuffing
#
# Note: Issue #1611 hinted at extending document-schema with
# `purpose: reference-bundle`. The Three-Gate Test favored a new schema;
# bedrock § 0.6 supersedes the issue's preferred path.

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

# =============================================================================
# IDENTITY
# =============================================================================
id: 01KS5N8FBQYBRRPB7K9R8M2A4P
slug: bundle-definition-schema
type: spec
version: 0.2.0

# =============================================================================
# VISIBILITY DECLARATION (REQ-18) — collection default
# =============================================================================
# Bundle-definition entities (content/reference-bundles/*.kno) are public
# reference knowledge by default — they declare composable downloadable
# reference bundles. Per REQ-18, individual entities MAY override with their
# own `visibility:` field (last-write-wins at the entity level). Drives the
# four-surface contract per kno-system_architecture.md § Agent Surface
# Integration and public-surface-parity.instructions.md.
visibility: public

# =============================================================================
# STANDARD TIER
# =============================================================================
title: "Bundle Definition Schema"
purpose: |
  Declare the composition rules for a downloadable reference bundle:
  which .kno surfaces to include, what lifecycle/persona filters apply,
  and which auth gate protects the artifact.

  **What is a Bundle Definition?**
  A declarative manifest. It does NOT contain the bundle's content; it
  describes how to assemble one. The bundle endpoint walks `surfaces[]`
  with `loadKnoFiles()`, applies `filters`, projects each entity to
  Markdown, and emits a zip. Adding a new entity to any source directory
  is reflected on the next request — zero TypeScript edits.

  **Persona Model:**

  | Persona  | Auth gate                                  | Typical filters             |
  |----------|--------------------------------------------|-----------------------------|
  | public   | authenticated session                      | lifecycle: published        |
  | creator  | organizer or admin on a possibility        | + creator audience          |
  | admin    | platform admin                             | + lifecycle: review         |

  **Layer 3 Position:** Bundle Definition extends document (Layer 2),
  which composes identity, history, and quality (Layer 1).

# =============================================================================
# RICH TIER — Taxonomy
# =============================================================================
provenance:
  origin:
    id: 01KS5N8FBQYBRRPB7K9R8M2A4P
    timestamp: "2026-04-20T00:00:00Z"
    tool: manual
taxonomy:
  topics:
    - bundles
    - reference
    - composition
    - generative-surfaces
  keywords:
    - bundle-definition
    - reference-bundle
    - persona
    - lifecycle
    - drift-guard

# =============================================================================
# SCHEMA SHAPE
# =============================================================================
schema:
  required:
    - id
    - slug
    - type
    - version
    - title
    - persona
    - auth_gate
    - surfaces

  fields:
    persona:
      type: string
      enum: [ public, creator, admin ]
      description: |
        Which audience the bundle targets. Determines auth gate and the
        default lifecycle/audience filters applied.

    auth_gate:
      type: object
      description: |
        How the bundle endpoint authenticates the request.
      required:
        - kind
      fields:
        kind:
          type: string
          enum: [ session, possibility-membership, platform-admin ]
        roles:
          type: array
          items: { type: string }
          description: |
            For `possibility-membership`, the acceptable roles
            (e.g., ["organizer", "admin"]). Ignored for other kinds.

    surfaces:
      type: array
      description: |
        The .kno source directories to scan. Each surface entry pairs a
        source directory with output placement and surface-specific filters.
      items:
        type: object
        required:
          - source
          - output_dir
        fields:
          source:
            type: string
            description: |
              Workspace-relative directory to scan (e.g., "specs",
              "content/apis", "content/rfcs", "content/capabilities").
          output_dir:
            type: string
            description: |
              Top-level directory inside the zip (e.g., "Specs", "APIs").
          group_by:
            type: string
            description: |
              Optional metadata field to subdivide output. Example:
              `managed_service.id` for APIs.
            optional: true
          lifecycle_filter:
            type: array
            description: |
              Override the persona's default lifecycle filter.
            items:
              type: string
              enum: [ draft, review, published, deprecated ]
            optional: true
          audience_filter:
            type: array
            description: |
              Restrict to entities whose `audience` or `persona` field
              matches one of these values.
            items: { type: string }
            optional: true

    cache_policy:
      type: string
      enum: [ private-no-store, private-short, public-build ]
      description: |
        Response Cache-Control behavior. Authenticated bundles MUST use
        `private-no-store` or `private-short`.

# =============================================================================
# RELATIONSHIPS
# =============================================================================
relationships:
  extends:
    - xri: pspace://spec:document-schema
      reason: "Composes identity, history, quality from Layer 1"
  related_to:
    - xri: pspace://spec:api-spec
      reason: "Bundles project API specs to Markdown grouped by managed_service"
    - xri: pspace://knowledge-base:provider-opacity
      reason: "Bundle output passes Provider Opacity lint"