# Manifest Schema — Container Entry Point
# KNO Schema Version: 0.5.1
#
# The manifest is the entry point for every .kno container/bundle.
# It describes what's inside the container and how to interpret it.
#
# PURPOSE: Enable pack/unpack tooling and container validation.
# Every .kno bundle (packed or unpacked) MUST have a manifest.kno.

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

# =============================================================================
# IDENTITY
# =============================================================================
id: 01KGK3V73M8MC65WBE9HC32B63
slug: manifest
type: spec
version: 0.1.0

# =============================================================================
# STANDARD TIER
# =============================================================================
title: "Manifest Schema"
purpose: |
  Define the entry point schema for .kno containers.

  **What is a manifest?** A manifest is metadata about a .kno bundle.
  It describes what files are inside, their types, their roles, and
  the history policy for the container.

  **Container Architecture:** Every .kno entity can exist in two forms:
  - **Packed**: Single `.kno` file (YAML multi-document with `---` separators)
  - **Unpacked**: Directory `.kno/` with individual files

  The manifest enables tooling to:
  - Pack: Combine directory into single file
  - Unpack: Split single file into directory
  - Validate: Check all declared contents exist and conform

  **P1 Compliance:** The manifest describes ONE container. The container
  holds ONE primary entity (plus history, attachments).

  **P2 Compliance:** The manifest makes the container self-describing.
  No external information needed to understand the bundle structure.

# =============================================================================
# RELATIONSHIPS
# =============================================================================
taxonomy:
  topics:
    - containers
    - packaging
    - bundle-format
  keywords:
    - manifest
    - container
    - pack
    - unpack
    - bundle
    - contents


# =============================================================================
# RICH TIER (provenance)
# =============================================================================
provenance:
  origin:
    id: 01KGK3V73M8MC65WBE9HC32B63
    timestamp: "2026-02-04T01:47:56Z"
    tool: manual-migration
relationships:
  depends_on:
    - xri: "kno://specs/kno-spec"
      reason: "Conforms to kno@0.0.9"

  enables:
    - xri: "kno://tools/pack-unpack-tooling"
      reason: "Pack/unpack container tools"
    - xri: "kno://capabilities/container-validation"
      reason: "Validate container structure"
    - xri: "kno://capabilities/history-embedding"
      reason: "Embed history in containers"

  implements:
    - xri: "kno://principles/P1"
      reason: "Single entity (container = one entity)"
    - xri: "kno://principles/P2"
      reason: "Self-contained (manifest makes bundle self-describing)"

quality:
  completeness: 0.8
  last_reviewed: "2026-01-06"
  review_status: draft
  reviewed_by: "claude"

# =============================================================================
# HISTORY
# =============================================================================
_history:
  version: 1
  created: "2026-01-06T18:00:00Z"
  created_by: "claude"
  modified: "2026-01-06T18:00:00Z"
  modified_by: "claude"

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

  description: |
    The manifest is the first file in every .kno container. When a tool
    opens a packed `.kno` file, the first YAML document (before the first
    `---` separator) MUST be the manifest. When a tool opens an unpacked
    `.kno/` directory, there MUST be a `manifest.kno` file at the root.

    ## Packed Format

    ```yaml
    # === manifest.kno ===
    id: my-entity
    type: manifest
    ...
    ---
    # === content.kno ===
    $schema: https://schemas.possibility.space/kno@0.0.9
    id: my-entity
    ...
    ---
    # === history/v1.0.0.kno ===
    ...
    ```

    ## Unpacked Format

    ```
    my-entity.kno/
    ├── manifest.kno
    ├── content.kno
    └── history/
        └── v1.0.0.kno
    ```

    ## Minimal Manifest

    The simplest valid manifest for a single-document .kno:

    ```yaml
    $schema: https://schemas.possibility.space/kno/manifest@0.1
    id: my-entity
    type: manifest
    version: 1.0.0
    entity_type: document
    contents:
      - path: content.kno
        role: content
    history:
      policy: none
    ```

  changelog:
    - version: "0.1.0"
      changes:
        - "Initial manifest schema for container architecture"
        - "Aligned with bedrock docs (embedded/external terminology)"
        - "Added hash chain support (parent_hash for verification)"
        - "Added rationale field for history policy explanation"

  schema:
    # -------------------------------------------------------------------------
    # CORE IDENTITY (what bundle is this?)
    # -------------------------------------------------------------------------
    identity:
      description: "Identity fields for the container"
      fields:
        id:
          type: string
          required: true
          description: |
            The identifier for this entity. Matches the id of the primary
            content entity inside the container.
          examples: ["my-document", "rfc-001", "user-schema"]

        type:
          type: string
          required: true
          const: "manifest"
          description: "Always 'manifest' for manifest files"

        version:
          type: string
          required: true
          pattern: "^\\d+\\.\\d+\\.\\d+$"
          description: |
            Semantic version of the entity. This is the CURRENT version
            of the primary content, not the manifest schema version.
          examples: ["1.0.0", "0.5.1", "2.3.0"]

        entity_type:
          type: string
          required: true
          description: |
            The kno_type of the primary entity in this container.
            Used for quick identification without reading content.
          examples: ["document", "spec", "rfc", "user", "diagram"]

    # -------------------------------------------------------------------------
    # CONTENTS (what's in the bundle?)
    # -------------------------------------------------------------------------
    contents:
      description: "List of files/documents in this container"
      fields:
        contents:
          type: array
          required: true
          min_items: 1
          description: |
            Array of content entries describing each file in the container.
            Order matters for packed format — files are concatenated in this order.
          items:
            type: object
            fields:
              path:
                type: string
                required: true
                description: |
                  Relative path within the container. For packed format, this
                  is a logical path. For unpacked, it's the actual file path.
                examples:
                  [
                    "content.kno",
                    "history/v1.0.0.kno",
                    "attachments/diagram.kno",
                  ]

              role:
                type: string
                required: true
                enum: ["content", "attachment", "schema"]
                description: |
                  The role this file plays in the container:
                  - **content**: The primary entity content (exactly one required)
                  - **attachment**: Supporting file (image, diagram, etc.)
                  - **schema**: Embedded schema for self-contained validation

                  Note: History snapshots are managed via the `history.embedded`
                  block, not listed individually in contents.

              type:
                type: string
                required: false
                description: "The kno_type of this file."
                examples: ["document", "diagram", "image"]

              hash:
                type: string
                required: false
                pattern: "^sha256:[a-f0-9]{64}$"
                description: |
                  Content hash for integrity verification. Recommended for
                  history snapshots and attachments.
                examples: ["sha256:abc123..."]

    # -------------------------------------------------------------------------
    # HISTORY POLICY (how is history managed?)
    # -------------------------------------------------------------------------
    history:
      description: "History retention and storage policy"
      fields:
        history:
          type: object
          required: false
          description: |
            History configuration for this entity. If omitted, defaults to
            policy: none (no embedded history).
          fields:
            policy:
              type: string
              required: true
              enum: ["full", "hybrid", "changelog", "external", "none"]
              description: |
                History retention policy:
                - **full**: All versions embedded in container
                - **hybrid**: Last N versions embedded, older externalized
                - **changelog**: Only summaries, no full snapshots
                - **external**: All history in external VCS entity
                - **none**: No history tracking

            retention:
              type: integer
              required: false
              minimum: 1
              description: |
                For 'hybrid' policy: number of versions to keep embedded.
                Defaults to 10 if not specified.
              examples: [5, 10, 20]

            rationale:
              type: string
              required: false
              description: |
                Human-readable explanation of why this history policy
                was chosen for this entity.
              examples:
                [
                  "Specification requires full audit trail",
                  "Standard entity - recent history accessible",
                ]

            embedded:
              type: array
              required: false
              description: |
                List of version snapshots embedded in this container.
                Each entry references a .kno file within the container.
                Aligns with bedrock: kno-foundational-principles.md § History Architecture
              items:
                type: object
                fields:
                  version:
                    type: string
                    required: true
                    description: "Semantic version string"
                    examples: ["3.0.0", "2.0.0", "1.0.0"]
                  snapshot:
                    type: string
                    required: true
                    description: "Path to snapshot file within container"
                    examples: ["history/v3.0.0.kno", "history/v2.0.0.kno"]
                  hash:
                    type: string
                    required: false
                    pattern: "^sha256:[a-f0-9]{64}$"
                    description: "Content hash for integrity verification"
                  parent_hash:
                    type: string
                    required: false
                    pattern: "^sha256:[a-f0-9]{64}$"
                    description: |
                      Hash of the previous version in the chain.
                      Enables hash chain verification without loading all versions.
                  date:
                    type: string
                    format: date-time
                    required: false
                    description: "When this version was created"

            external:
              type: object
              required: false
              description: |
                Reference to external VCS entity holding deep history.
                Used for 'hybrid' and 'external' policies.
                Aligns with bedrock: kno-foundational-principles.md § History Architecture
              fields:
                vcs_uri:
                  type: string
                  required: true
                  description: "XRI or URI of the external VCS entity"
                  examples: ["pspace://vcs:entity-id-history"]
                before_version:
                  type: string
                  required: false
                  description: "Oldest version NOT in embedded (first in external)"
                  examples: ["1.0.0"]
                root_hash:
                  type: string
                  required: false
                  pattern: "^sha256:[a-f0-9]{64}$"
                  description: |
                    Hash of the oldest embedded version, for chain verification
                    against external history.

    # -------------------------------------------------------------------------
    # TIMESTAMPS (when was bundle created/modified?)
    # -------------------------------------------------------------------------
    timestamps:
      description: "Container-level timestamps"
      fields:
        created:
          type: string
          format: date-time
          required: false
          description: "When this container was first created"
          examples: ["2026-01-06T18:00:00Z"]

        modified:
          type: string
          format: date-time
          required: false
          description: "When this container was last modified"
          examples: ["2026-01-06T18:00:00Z"]

        packed_at:
          type: string
          format: date-time
          required: false
          description: "When this container was last packed (if packed)"

  # ---------------------------------------------------------------------------
  # VALIDATION RULES
  # ---------------------------------------------------------------------------
  validation:
    rules:
      - id: "exactly-one-content"
        description: "Container must have exactly one content role entry"
        expression: "contents.filter(c => c.role === 'content').length === 1"

      - id: "full-hybrid-requires-embedded"
        description: "Full/hybrid policy requires embedded[] for version snapshots"
        expression: "!['full', 'hybrid'].includes(history?.policy) || history?.embedded?.length > 0"

      - id: "external-hybrid-requires-external"
        description: "External/hybrid policy requires external block"
        expression: "!['external', 'hybrid'].includes(history?.policy) || history?.external"
        severity: warning

      - id: "hybrid-requires-retention"
        description: "Hybrid policy should specify retention count"
        expression: "history?.policy !== 'hybrid' || history?.retention"
        severity: warning

      - id: "hash-chain-integrity"
        description: "Each embedded version should reference parent_hash for chain verification"
        expression: "history?.embedded?.every((v, i, arr) => i === arr.length - 1 || v.parent_hash)"
        severity: info

  # ---------------------------------------------------------------------------
  # EXAMPLES
  # ---------------------------------------------------------------------------
  examples:
    minimal:
      description: "Simplest valid manifest (no history)"
      value: |
        $schema: https://schemas.possibility.space/kno/manifest@0.1
        id: my-doc
        type: manifest
        version: 1.0.0
        entity_type: document
        contents:
          - path: content.kno
            role: content
        history:
          policy: none

    with_history:
      description: "Manifest with hybrid history (aligns with bedrock example)"
      value: |
        $schema: https://schemas.possibility.space/kno/manifest@0.1
        id: rfc-001
        type: manifest
        version: 0.5.1
        entity_type: rfc
        contents:
          - path: content.kno
            role: content
            type: rfc
        history:
          policy: hybrid
          retention: 10
          rationale: "Standard entity - recent history accessible, deep history available"
          embedded:
            - version: "0.5.0"
              snapshot: history/v0.5.0.kno
              hash: sha256:abc123...
              date: 2026-01-05T12:00:00Z
            - version: "0.4.0"
              snapshot: history/v0.4.0.kno
              hash: sha256:def456...
              parent_hash: sha256:abc123...
              date: 2026-01-01T12:00:00Z
          external:
            vcs_uri: pspace://vcs:rfc-001-history
            before_version: "0.3.0"
            root_hash: sha256:def456...

    full_history:
      description: "Manifest with full history (specifications, audit-critical)"
      value: |
        $schema: https://schemas.possibility.space/kno/manifest@0.1
        id: kno-spec
        type: manifest
        version: 0.5.1
        entity_type: spec
        contents:
          - path: content.kno
            role: content
            type: spec
        history:
          policy: full
          rationale: "Specification requires full audit trail"
          embedded:
            - version: "0.5.0"
              snapshot: history/v0.5.0.kno
              hash: sha256:111...
            - version: "0.4.0"
              snapshot: history/v0.4.0.kno
              hash: sha256:222...
              parent_hash: sha256:111...
            - version: "0.3.0"
              snapshot: history/v0.3.0.kno
              hash: sha256:333...
              parent_hash: sha256:222...

    with_attachments:
      description: "Manifest with attachments"
      value: |
        $schema: https://schemas.possibility.space/kno/manifest@0.1
        id: architecture-doc
        type: manifest
        version: 2.0.0
        entity_type: document
        contents:
          - path: content.kno
            role: content
            type: document
          - path: attachments/arch-diagram.kno
            role: attachment
            type: diagram
          - path: attachments/logo.kno
            role: attachment
            type: image
        history:
          policy: none

# =============================================================================
# CONTAINER TIER — Navigation Index
# =============================================================================
_index:
  - path: "identity"
    line: 18
    keywords: [id, type, version, manifest]
  - path: "spec/fields"
    line: 80
    keywords: [schema_version, bundle_type, entries, history]
  - path: "spec/entry"
    line: 150
    keywords: [path, role, type, required, description]
  - path: "spec/roles"
    line: 220
    keywords: [primary, attachment, auxiliary, metadata]
  - path: "spec/history_policy"
    line: 300
    keywords: [full, summary, none, external]
  - path: "examples"
    line: 400
    keywords: [minimal, full, rfc-bundle]

contains:
  - xri: "#identity"
    role: section
    title: "Schema Metadata"
    keywords: [id, type, version]
  - xri: "#spec"
    role: section
    title: "Manifest Schema"
    keywords: [entries, roles, history-policy]
  - xri: "#examples"
    role: section
    title: "Usage Examples"
    keywords: [minimal, full, rfc-bundle]