# KNO Specification — The Kernel
# This file is the canonical reference for the .kno format.
# It is self-describing: a .kno file that defines what .kno files are.
#
# Version: 0.0.9
# Status: Canonical Reference
# Last Updated: 2026-02-03
#
# KERNEL IMMUTABILITY:
# This file should change extremely rarely. It is the atomic kernel of the
# .kno system. Prefer edge inference over declarative enums. Push classification
# logic to domain schemas (one degree away from kernel) rather than hardcoding
# exhaustive values here.
#
# Changelog:
#   0.0.10 — Added bidirectional `applies_to` / `affected_by` predicate pair
#           for the `notice` entity (M52 Phase 3.1.6 / #2052)
#           - `applies_to`: Scope — source entity applies to / scopes target
#             (e.g., a notice applies_to `pspace://api-endpoint/oauth-authorize`)
#           - `affected_by`: Inverse of applies_to — target entity is scoped
#             by the source notice. Required by P7 (Cooperative); CI lint
#             enforces backlink consistency.
#           - Rationale: Per P10 (Derivable Structure) the SCOPE of an entity
#             (platform-wide vs. endpoint-scoped vs. possibility-scoped) is
#             emergent from its applies_to targets, not declared via a subtype
#             field. Mirrors the `documents` ↔ `documented_by` precedent.
#   0.0.9 — Identity separation (RFC-013)
#           - `id` field: Now ULID-only (no type prefix), immutable birth identity
#           - Added `slug` field (STANDARD tier): Human-readable name, mutable
#           - Added `provenance` field (RICH tier): Birth identity, content hash, assertions
#           - XRIs use ULID-only format: pspace://type:ULID (not pspace://type:type_ULID)
#           - Named XRIs supported: pspace://type:slug for human-friendly references
#           - Rationale: Enables arbitrary renaming without breaking references;
#             separates identity (immutable) from naming (mutable); enables
#             content-addressed verification and distributed trust (REQ-16, REQ-17)
#   0.0.8 — Formalized relationship target format (P7 compliance)
#           - Targets MUST be objects with `xri` field (not simple strings)
#           - Targets SHOULD include `reason` field for semantic context
#           - Objects enable future extensibility (confidence, verified_by, etc.)
#           - Rationale: Per P7 "relationships carry semantic meaning" — structured
#             targets allow capturing WHY relationships exist, not just THAT they exist
#   0.0.7 — Added relationship predicates for complete provenance tracking
#           - `inferred_from`: For schema-less conversions (structure created, not transformed)
#             * Supports schema_affinity to document WHY inference was attempted
#             * For text: source=embedded with location pointing to content field
#             * For binary: source=external with CID for content-addressed reference
#           - `instance_of`: Semantic alias for conforms_to (schema/spec instantiation)
#           - `format`: What format specification the content uses
#           - `documents`: What this entity documents or explains
#           - `documented_by`: Inverse of documents — what entities document this one
#   0.0.6 — Removed `facets` field entirely from STANDARD tier
#           - facets.domain: Redundant; derivable from $schema type + XRI namespace
#           - facets.category: Redundant; derivable from $schema inheritance graph
#           - Rationale: "Structure expressed, meaning inferred" — facets are
#             qualitative classifications that duplicate information already
#             expressed via $schema and XRI. See bedrock § Edge Inference.
#   0.0.5 — Removed all enum types; converted to strings with inference guidance
#           - type: Now string; classification inferred from $schema conformance
#           - review_status: Now string; values emerge from usage patterns
#           - resolution.status: Now string; values emerge from usage patterns
#           - Rationale: Enums require kernel modification for new values;
#             edge inference delegates classification to domain schemas
#   0.0.4 — Removed `audience` and `facets.complexity` fields (DC-1, DC-2)
#           - audience: Superfluous; per DC-1 all .kno files serve all audiences
#           - complexity: Subjective; violates DC-2 minimalism constraint
#   0.0.3 — Removed deprecated fields (kno_type, kno_version, facets.layer)
#   0.0.2 — Added STANDARD tier fields
#   0.0.1 — Initial specification

# =============================================================================
# @kno:manifest
# =============================================================================
$schema: kno@0.0.9
id: 01KGK3V73P6019WTXBX4CJ12G7
slug: kno-spec
type: schema
version: 0.0.10

title: "Knowledge Notation Object Specification"
purpose: |
  The definitive specification for .kno files — structured knowledge documents 
  that serve agents, humans, and systems equally well.

description: |
  KNO (Knowledge Notation Object) is a file format for structured knowledge.

  A .kno file is written in KAML (Knowledge-Adapted Markup Language) — 
  a markup language built on YAML with microsyntax for semantic addressing,
  hierarchical containment, and agent-optimized retrieval.

  Key characteristics:
  - **Single file format** — ONE format for ALL entity types
  - **Container structure** — Nested entities via `_contains`
  - **Progressive tiers** — BASIC → STANDARD → RICH → FEDERATED
  - **Triple-audience** — Readable by humans, parseable by code, navigable by agents

# NOTE: `facets` field removed per v0.0.6 — domain/category are qualitative
# classifications that should be inferred from $schema and XRI namespace,
# not declared redundantly. See kno-foundational-principles.md § Edge Inference.

# =============================================================================
# @kno:taxonomy
# =============================================================================
taxonomy:
  topics:
    - knowledge-management
    - schema-design
    - file-format
    - markup-language
    - federated-identity
  keywords:
    - kno
    - kaml
    - yaml
    - schema
    - container
    - xri
    - federation

# =============================================================================
# @kno:relationships
# =============================================================================

# =============================================================================
# RICH TIER (provenance)
# =============================================================================
provenance:
  origin:
    id: 01KGK3V73P6019WTXBX4CJ12G7
    timestamp: "2026-02-04T01:47:56Z"
    tool: manual-migration
relationships:
  enables:
    - xri: "kno://specs/identity-schema"
      reason: "Identity tier built on this spec"
    - xri: "kno://specs/history-schema"
      reason: "History tier built on this spec"
    - xri: "kno://specs/quality-schema"
      reason: "Quality tier built on this spec"
  related_to:
    - xri: "kno://specs/document-schema"
      reason: "Documents are a foundational entity type defined by kno-spec tiers"
    - xri: "kno://specs/spec-schema"
      reason: "Specs are self-describing .kno files per P8 (Self-Generating)"
    - xri: "kno://specs/rfc-schema"
      reason: "RFCs propose changes to kno-spec and related schemas"
  conforms_to:
    - xri: "kno://bedrock/foundational-principles"
      reason: "Implements P1-P10 and DC-1,2,3"
    - xri: "kno://bedrock/format-requirements"
      reason: "Satisfies REQ-01 through REQ-17"

# =============================================================================
# @kno:quality
# =============================================================================
quality:
  completeness: 0.85
  last_reviewed: "2026-01-07"
  review_status: canonical
  reviewed_by: "pspace-core-team"

_history:
  version: 7
  created: "2025-12-01T12:00:00Z"
  created_by: "pspace-core-team"
  modified: "2026-01-16T12:00:00Z"
  modified_by: "claude"

# =============================================================================
# @kno:index
# Navigation index for agent-optimized retrieval
# =============================================================================
_index:
  - path: "metadata"
    line: 125
    keywords: [ name, extension, pronunciation, mime ]
  - path: "principles"
    line: 200
    keywords: [ P1, P2, P3, P4, P5, P6, P7, P8, P9, P10, principle ]
  - path: "kaml"
    line: 320
    keywords: [ kaml, markup, yaml, microsyntax ]
  - path: "schema"
    line: 420
    keywords: [ tier, basic, standard, rich, federated ]
  - path: "schema/tiers"
    line: 450
    keywords: [ tier, progressive, enrichment ]
  - path: "schema/tiers/basic"
    line: 460
    keywords: [ id, type, version, required ]
  - path: "schema/tiers/standard"
    line: 520
    keywords: [ title, purpose, taxonomy ]
  - path: "schema/tiers/rich"
    line: 600
    keywords: [ taxonomy, relationships, sections, quality ]
  - path: "schema/tiers/federated"
    line: 750
    keywords: [ identity, services, resolution, xrds, xri ]
  - path: "container"
    line: 850
    keywords: [ container, _contains, nesting, manifest ]
  - path: "history"
    line: 950
    keywords: [ history, temporal, P9, snapshots, xri ]
  - path: "tooling"
    line: 1050
    keywords: [ cli, validate, resolve, flatten ]
  - path: "examples"
    line: 1100
    keywords: [ example, minimal, full ]

# =============================================================================
# @kno:contains
# What this container holds (discovery manifest)
# =============================================================================
contains:
  - xri: "#metadata"
    role: section
    title: "Format Metadata"
    keywords: [ name, extension, mime ]
  - xri: "#principles"
    role: section
    title: "The 10 Principles"
    keywords: [ P1-P10, foundation, bedrock ]
  - xri: "#kaml"
    role: section
    title: "KAML Specification"
    keywords: [ kaml, markup, microsyntax ]
  - xri: "#schema"
    role: section
    title: "Schema Definition"
    keywords: [ tier, fields, validation ]
  - xri: "#container"
    role: section
    title: "Container Structure"
    keywords: [ container, nesting, _contains ]
  - xri: "#history"
    role: section
    title: "History Architecture"
    keywords: [ temporal, P9, snapshots ]
  - xri: "#tooling"
    role: section
    title: "Tooling Specification"
    keywords: [ cli, commands ]
  - xri: "#examples"
    role: section
    title: "Examples"
    keywords: [ minimal, full, reference ]
  - xri: "#history-snapshots"
    role: history
    title: "Version History"
    keywords: [ changelog, versions, P9 ]

# =============================================================================
# NESTED CONTENT
# =============================================================================
_contains:
  # ===========================================================================
  # @kno:metadata
  # ===========================================================================
  metadata:
    $schema: kno-section@0.0.1
    id: metadata
    title: "Format Metadata"

    content:
      name: "Knowledge Notation Object"
      abbreviation: "KNO"
      pronunciation: "know"
      file_extension: ".kno"
      mime_type: "application/vnd.kno+yaml"
      tagline: "Structured knowledge you can trust"

      description: |
        KNO is a format-agnostic schema for structured knowledge documents.
        It unifies documentation, specifications, entities, and institutional
        knowledge into a single progressive schema with federated identity.

      design_principles:
        - name: "Format Singularity"
          description: "ONE file format for ALL entity types"
        - name: "Progressive Enrichment"
          description: "BASIC → STANDARD → RICH → FEDERATED tiers"
        - name: "Triple-Audience"
          description: "Humans, agents, and systems served equally"
        - name: "Container Architecture"
          description: "Every .kno is a bundle that can hold nested entities"
        - name: "Self-Generating"
          description: ".kno files describe .kno files (schemas are .kno)"

  # ===========================================================================
  # @kno:principles
  # ===========================================================================
  principles:
    $schema: kno-section@0.0.1
    id: principles
    title: "The 10 Foundational Principles"

    content:
      source: "kno://bedrock/foundational-principles"
      description: |
        These principles govern how .kno entities are created, structured,
        and interact. They are the foundation — everything else follows.

      entity_level:
        - id: "P1"
          name: "Single Entity Output"
          summary: "A converter produces ONE .kno file, not two."
          implication: "No format/domain layer separation."

        - id: "P2"
          name: "Self-Contained"
          summary: "The entity is usable without reading the original source."
          implication: "Portable, cacheable, offline-usable."

        - id: "P3"
          name: "Best Representation"
          summary: "The .kno entity is MORE useful than the source file."
          implication: "More queryable, relatable, discoverable, actionable."

        - id: "P4"
          name: "Source Embedded"
          summary: "Raw source preserved inline for provenance."
          implication: "No external references that break over time."

        - id: "P5"
          name: "Schema-Driven Quality"
          summary: "The target schema defines what 'best' means."
          implication: "Quality is objective, not subjective."

      system_level:
        - id: "P6"
          name: "Morphological / Emergent"
          summary: "Collections reveal more than individual entities."
          implication: "Patterns, gaps, insights emerge from the graph."

        - id: "P7"
          name: "Cooperative / Codependent"
          summary: "Entities carry context through relationships."
          implication: "Links carry semantic meaning (depends_on, enables, etc.)."

        - id: "P8"
          name: "Self-Generating"
          summary: ".kno files generate .kno files."
          implication: "Schemas are .kno; the system improves itself."

        - id: "P9"
          name: "Temporal / Historical"
          summary: "Entities contain their own history."
          implication: "Version history embedded; evolution matters."

        - id: "P10"
          name: "Derivable Structure"
          summary: "Graphs, ontologies, taxonomies emerge from entities."
          implication: "One source of truth, many derived views."

      design_constraints:
        - id: "DC-1"
          name: "Triple-Audience Consumption"
          summary: "Consumable by programmatic, agentic, AND human audiences."

        - id: "DC-2"
          name: "Minimalism"
          summary: "Every byte must justify its existence."

        - id: "DC-3"
          name: "Text-Editor Accessibility"
          summary: "Editable with a plain text editor."

  # ===========================================================================
  # @kno:kaml
  # ===========================================================================
  kaml:
    $schema: kno-section@0.0.1
    id: kaml
    title: "KAML: Knowledge-Adapted Markup Language"

    content:
      definition: |
        KAML is a markup language for .kno files. It uses YAML as its 
        serialization format, with microsyntax conventions that enable:
        - Semantic addressing (XRI)
        - Hierarchical containment (_contains)
        - Navigation index (_index)
        - Section markers (# @kno:)

      layering: |
        ┌─────────────────────────────────────────┐
        │  KAML (markup language)                 │  🐪
        │  - XRI addressing                       │
        │  - Container semantics (_contains)      │
        │  - Navigation index (_index)            │
        │  - Section markers (# @kno:)            │
        │  - Schema declarations ($schema)        │
        ├─────────────────────────────────────────┤
        │  YAML (serialization format)            │
        │  - Key: value syntax                    │
        │  - Indentation structure                │
        │  - Block scalars                        │
        │  - Comments                             │
        ├─────────────────────────────────────────┤
        │  .kno (file extension)                  │
        │  - Indicates KAML content               │
        └─────────────────────────────────────────┘

    _contains:
      # @kno:kaml/reserved-keys
      reserved-keys:
        $schema: kno-section@0.0.1
        id: reserved-keys
        title: "Reserved Keys"

        content:
          keys:
            - key: "$schema"
              purpose: "Schema declaration with version"
              required: true
              example: "kno@0.6"
            - key: "_index"
              purpose: "Navigation index for tooling"
              required: false
              example: "- path: 'section', line: 42"
            - key: "_contains"
              purpose: "Nested container contents"
              required: false
              example: "child-entity: { ... }"
            - key: "_offset"
              purpose: "Line hint for fast seeking"
              required: false
              example: "42"

      # @kno:kaml/xri
      xri:
        $schema: kno-section@0.0.1
        id: xri
        title: "XRI: Extensible Resource Identifier"

        content:
          description: |
            XRIs identify entities within and across .kno files.

          types:
            - name: "Fragment XRI (Internal)"
              pattern: "#path/to/entity"
              meaning: "Relative to current file"
              examples:
                - "#articles"
                - "#articles/introduction"
                - "#schema/tiers/basic"

            - name: "Absolute XRI (External)"
              pattern: "kno://authority/path"
              meaning: "Cross-file reference"
              examples:
                - "kno://specs/kno-spec"
                - "kno://pspace-kb/articles/intro"

            - name: "Parent Reference"
              pattern: "#"
              meaning: "Immediate parent container"

      # @kno:kaml/section-markers
      section-markers:
        $schema: kno-section@0.0.1
        id: section-markers
        title: "Section Markers"

        content:
          format: "# @kno:{path}"
          purpose: |
            Section markers are YAML comments that:
            - Standard parsers ignore completely
            - .kno tooling uses for indexing
            - Enable partial file parsing (read from marker forward)
          example: "# @kno:schema/tiers/basic"

  # ===========================================================================
  # @kno:schema
  # ===========================================================================
  schema:
    $schema: kno-section@0.0.1
    id: schema
    title: "Schema Definition"

    content:
      overview: |
        The .kno schema uses progressive enrichment — four tiers that add
        capability without requiring complexity. Files can stop at any tier.

      progression: |
        BASIC       Required fields (id, type, version)
           ↓
        STANDARD    Discovery fields (title, purpose)
           ↓
        RICH        Knowledge graph (taxonomy, relationships, sections, quality)
           ↓
        FEDERATED   Identity & services (canonical_id, equiv_ids, services)

    _contains:
      # @kno:schema/tiers
      tiers:
        $schema: kno-section@0.0.1
        id: tiers
        title: "Schema Tiers"

        _contains:
          # @kno:schema/tiers/basic
          basic:
            $schema: kno-section@0.0.1
            id: basic
            title: "BASIC Tier"

            content:
              description: "Minimum viable .kno document. All fields required."
              required: true

              fields:
                - name: "id"
                  type: "string"
                  format: "ulid | slug (kebab-case)"
                  description: |
                    Unique identifier. Two valid formats (RFC-013):

                    1. **ULID (preferred for entities)**: Immutable birth identity
                       - 26-character ULID assigned at creation
                       - Encodes creation timestamp
                       - NEVER changes, even if entity is renamed
                       - Example: "01KG1FRSBANYFVF3S0C7GVKREY"

                    2. **Slug (for specs/schemas)**: Human-readable identifier
                       - Kebab-case string
                       - Example: "kno-spec", "user-schema"

                    The `id` field is IMMUTABLE once assigned. To change how an
                    entity is referenced by name, use the `slug` field (STANDARD tier).

                    XRI format uses the id directly: pspace://type:id
                  required: true
                  immutable: true
                  examples:
                    - "01KG1FRSBANYFVF3S0C7GVKREY"
                    - "kno-spec"
                    - "user-schema"

                - name: "type"
                  type: "string"
                  description: |
                    Primary document classification. The type value is inferred
                    from schema conformance rather than hardcoded in the kernel.

                    Classification is determined by:
                    1. The $schema declaration (e.g., $schema: api-spec implies type)
                    2. Schema inheritance chains (conforms_to, extends)
                    3. Domain schema conventions

                    Common patterns (not exhaustive — new types emerge):
                    - "definition", "glossary" — terminology entities
                    - "schema", "spec" — normative documents
                    - "document", "guide" — prose content
                    - "workflow", "process" — procedural content
                    - "api", "endpoint" — service interfaces

                    The kernel does NOT constrain valid types. Domain schemas
                    define what types are meaningful in their context.
                  required: true
                  examples:
                    - "definition"
                    - "schema"
                    - "document"
                    - "workflow"
                    - "api"

                - name: "version"
                  type: "string"
                  format: "semver (MAJOR.MINOR.PATCH)"
                  description: "Document version"
                  required: true
                  examples:
                    - "1.0.0"
                    - "0.6.0"

          # @kno:schema/tiers/standard
          standard:
            $schema: kno-section@0.0.1
            id: standard
            title: "STANDARD Tier"

            content:
              description: "Recommended enrichment for searchable, navigable documents."
              required: false

              fields:
                - name: "slug"
                  type: "string"
                  format: "kebab-case"
                  description: |
                    Human-readable identifier for URLs and references (RFC-013).

                    Unlike `id` (immutable), `slug` can be changed freely without
                    breaking XRI references. Multiple slugs can alias to the same
                    entity via the resolution layer.

                    Named XRI format: pspace://type:slug
                    Example: pspace://playbook:structured-context-flow
                  mutable: true
                  examples:
                    - "structured-context-flow"
                    - "max-engel"
                    - "acme-corp"

                - name: "title"
                  type: "string"
                  description: "Human-readable document title"
                  examples:
                    - "Organization Onboarding Flow"
                    - "KNO Specification"

                - name: "name"
                  type: "string"
                  description: |
                    Display name (can include spaces, special characters).
                    Used for UI display when title is not appropriate.
                  mutable: true
                  examples:
                    - "Structured Context Flow (SCF)"
                    - "Max Engel"

                - name: "purpose"
                  type: "string"
                  description: "Single sentence explaining what this document is for"
                  examples:
                    - "Define the format for structured knowledge documents"

                - name: "description"
                  type: "text"
                  format: "markdown"
                  description: "Extended description of the document"
                # NOTE: `facets` field REMOVED in v0.0.6
                # facets.domain and facets.category were qualitative classifications
                # that duplicate information derivable from $schema and XRI:
                #   - domain: Inferred from $schema type (api-spec → infrastructure)
                #   - category: Inferred from schema inheritance graph
                # See kno-foundational-principles.md § Edge Inference Over Declarative Judgments

                # @kno:schema/tiers/rich
          rich:
            $schema: kno-section@0.0.1
            id: rich
            title: "RICH Tier"

            content:
              description: "Full enrichment for knowledge graph, quality tracking, and deep
                linking."
              required: false

              fields:
                - name: "taxonomy"
                  type: "object"
                  description: "Extended classification"
                  fields:
                    - name: "topics"
                      type: "array"
                      description: "Subject matter topics"
                    - name: "keywords"
                      type: "array"
                      description: "Search keywords (BM25-optimized)"

                - name: "relationships"
                  type: "object"
                  description: "Explicit links to other entities"
                  target_format:
                    description: |
                      Each predicate maps to an array of relationship targets.
                      Targets MUST be objects (not simple strings) for consistency
                      and extensibility. Per P7, relationships carry semantic meaning.
                    required_fields:
                      note: "ONE of xri OR url MUST be present (not both required)"
                      fields:
                        - name: "xri"
                          type: "string"
                          description: "XRI reference to a .kno entity"
                          examples: [ "kno://specs/user-schema", "pspace://org:acme" ]
                        - name: "url"
                          type: "string"
                          description: "External URL reference (non-.kno standards, specs, etc.)"
                          examples: [ "https://www.w3.org/ns/activitystreams", "https://schema.org/Thing" ]
                    optional_fields:
                      - name: "reason"
                        type: "string"
                        description: "Why this relationship exists (P7 semantic context)"
                        recommendation: "SHOULD include for non-obvious relationships"
                    example: |
                      relationships:
                        depends_on:
                          - xri: "kno://specs/identity-schema"
                            reason: "Requires identity tier for user resolution"
                        related_to:
                          - xri: "kno://specs/document-schema"
                            reason: "Documents are a foundational entity type"
                  predicates:
                    - name: "depends_on"
                      meaning: "Prerequisites — must read/understand first"
                    - name: "related_to"
                      meaning: "See also — related but not required"
                    - name: "supersedes"
                      meaning: "Replaces — older versions this obsoletes"
                    - name: "amends"
                      meaning: "Refines or extends — modifies without replacing"
                    - name: "enables"
                      meaning: "Makes possible — capabilities this unlocks"
                    - name: "part_of"
                      meaning: "Parent — collection this belongs to"
                    - name: "conforms_to"
                      meaning: "Schema this instance implements"
                    - name: "instance_of"
                      meaning: "Schema/spec this is an instance of (semantic alias for conforms_to)"
                    - name: "format"
                      meaning: "Format specification the content uses (e.g., markdown-format,
                        d2-format)"
                    - name: "documents"
                      meaning: "What this entity documents or explains"
                    - name: "documented_by"
                      meaning: "Inverse of documents — what entities document this one"
                    - name: "applies_to"
                      meaning: "Scope — source entity scopes / governs / targets the target (notice →
                        endpoint, capability → possibility, etc.)"
                      notes: |
                        Introduced in v0.0.10 for the `notice` entity (M52 #2052).
                        Per P10, scope is emergent from `applies_to` targets, not
                        declared via a subtype field. Per P7, every applies_to link
                        MUST have a reverse `affected_by` link from the target;
                        `lint-api-contract-honesty.ts` enforces this.
                    - name: "affected_by"
                      meaning: "Inverse of applies_to — target entity is scoped by the source notice /
                        capability / etc."
                    - name: "inferred_from"
                      meaning: "Source — unstructured content this entity's structure was derived
                        from"
                      notes: |
                        Used for schema-less conversions where structure is created, not transformed.
                        Supports schema_affinity to document WHY inference was attempted.
                        For text: source=embedded with location pointing to content field.
                        For binary: source=external with CID for content-addressed reference.

                - name: "sections"
                  type: "array"
                  description: "Structured content blocks"
                  item_fields:
                    - "id"
                    - "title"
                    - "content"
                    - "subsections"
                    - "data"

                - name: "quality"
                  type: "object"
                  description: "Quality and review tracking"
                  fields:
                    - name: "completeness"
                      type: "number"
                      range: "0.0 to 1.0"
                    - name: "last_reviewed"
                      type: "date"
                    - name: "review_status"
                      type: "string"
                      description: |
                        Quality review lifecycle stage. Common values include:
                        draft, review, approved, deprecated, canonical.
                        Domain schemas may define additional statuses.
                      examples:
                        - "draft"
                        - "review"
                        - "approved"
                        - "canonical"
                    - name: "reviewed_by"
                      type: "string"

                - name: "provenance"
                  type: "object"
                  description: |
                    Origin, integrity, and verification information (RFC-013).
                    Implements REQ-16 (Provenance & Audit) and REQ-17 (Validation & Assertion).
                  fields:
                    - name: "origin"
                      type: "object"
                      description: "Immutable creation metadata (birth identity)"
                      fields:
                        - name: "id"
                          type: "string"
                          description: "ULID assigned at creation (same as top-level id)"
                        - name: "timestamp"
                          type: "datetime"
                          description: "ISO 8601 creation timestamp"
                        - name: "creator"
                          type: "string"
                          format: "xri"
                          description: "XRI of creating agent/user"
                          examples:
                            - "pspace://agent:synthesis-pipeline"
                            - "pspace://user/01HXYZ123ABC"
                        - name: "tool"
                          type: "string"
                          required: false
                          description: "Optional: software that created the entity"
                          examples:
                            - "synthesis-pipeline v1.0"
                            - "manual-migration"
                            - "pspace-cli v2.0"

                    - name: "content"
                      type: "object"
                      description: "Current version integrity verification"
                      fields:
                        - name: "hash"
                          type: "string"
                          description: "Content hash (algorithm:value format)"
                          examples:
                            - "sha256:e3b0c44298fc1c149afbf4c8996fb924..."
                        - name: "algorithm"
                          type: "string"
                          description: "Hash algorithm used"
                          examples: [ "sha256", "sha3-256", "blake3" ]
                        - name: "normalized"
                          type: "boolean"
                          description: "Whether hash was computed on normalized form"

                    - name: "assertions"
                      type: "array"
                      description: "Node attestations of entity validity"
                      item_fields:
                        - name: "node"
                          type: "string"
                          format: "xri"
                          description: "XRI of asserting node"
                          examples:
                            - "pspace://node:hive.possibility.space"
                            - "ipfs://gateway"
                        - name: "timestamp"
                          type: "datetime"
                          description: "When assertion was made"
                        - name: "hash"
                          type: "string"
                          description: "Content hash the node verified"
                        - name: "cid"
                          type: "string"
                          description: "IPFS CID if content-addressed"
                        - name: "signature"
                          type: "string"
                          format: "base64"
                          description: "Cryptographic proof of assertion (optional)"

          # @kno:schema/tiers/federated
          federated:
            $schema: kno-section@0.0.1
            id: federated
            title: "FEDERATED Tier"

            content:
              description: |
                Federated identity and service discovery capabilities.
                Inspired by XRDS/XRI for entity resolution across distributed systems.
              required: false
              fields:
                - name: "identity"
                  type: "object"
                  description: "XRDS-inspired synonyms for federated identity"
                  fields:
                    - name: "canonical_id"
                      type: "string"
                      description: "Immutable, persistent identifier"
                      examples: [ "org_abc123xyz", "user_def456uvw" ]

                    - name: "local_ids"
                      type: "array"
                      description: "Human-friendly aliases (can change)"
                      examples: [ [ "acme-corp", "acme", "acme-inc" ] ]

                    - name: "equiv_ids"
                      type: "array"
                      description: "External identifiers from other systems"
                      item_fields:
                        - name: "provider"
                          examples: [ "mercury", "github", "google_workspace" ]
                        - name: "id"
                          description: "Identifier in that system"
                        - name: "verified"
                          type: "boolean"

                - name: "services"
                  type: "array"
                  description: "Service Endpoint (SEP) descriptors"
                  item_fields:
                    - name: "type"
                      description: "Service type (URN-style)"
                      examples: [ "pspace:finance", "pspace:identity", "xri:resolve" ]
                    - name: "provider"
                      description: "Service provider"
                      examples: [ "mercury", "github", "p9y" ]
                    - name: "endpoints"
                      type: "array"
                      description: "Concrete URIs"

                - name: "resolution"
                  type: "object"
                  description: "Entity resolution metadata"
                  fields:
                    - name: "resolver_uri"
                      type: "uri"
                      description: "URI to resolve this entity's full descriptor"
                    - name: "status"
                      type: "string"
                      description: |
                        Resolution status for federated identity. Common values:
                        active, redirect, deprecated, reserved.
                      examples:
                        - "active"
                        - "redirect"
                        - "deprecated"

  # ===========================================================================
  # @kno:container
  # ===========================================================================
  container:
    $schema: kno-section@0.0.1
    id: container
    title: "Container Structure"

    content:
      principle: |
        Every .kno entity is a CONTAINER that can hold nested entities.
        Containment is expressed through YAML nesting with `_contains` fields.

      key_decisions:
        - decision: ".kno is a container"
          status: "DECIDED"
          rationale: "Enables history, attachments, layers without external files"
        - decision: "Single-file format"
          status: "DECIDED"
          rationale: "No directory form; containers are nested YAML"
        - decision: "`_contains` for nesting"
          status: "DECIDED"
          rationale: "KAML microsyntax for hierarchical structure"
        - decision: "`_index` for navigation"
          status: "DECIDED"
          rationale: "Agent-optimized retrieval via manifest index"

      structure_example: |
        # article.kno
        $schema: kno@0.0.9
        id: article-001
        title: "Example Article"

        _index:
          - path: "content"
            line: 15
          - path: "content/introduction"
            line: 20

        contains:
          - xri: "#content"
            title: "Content"

        _contains:
          # @kno:content
          content:
            _contains:
              # @kno:content/introduction
              introduction:
                title: "Introduction"
                text: |
                  The introduction to this article...

    _contains:
      # @kno:container/manifest-pattern
      manifest-pattern:
        $schema: kno-section@0.0.1
        id: manifest-pattern
        title: "Manifest-First Pattern"

        content:
          description: |
            Every KAML container has a manifest at the root level.
            The manifest enables:
            - **Discovery** — `contains` lists what's inside
            - **Query without parse** — Keywords, titles in manifest
            - **Navigation** — `_index` provides line hints
            - **Lazy loading** — Parse manifest first, dive deeper as needed

      # @kno:container/history
      history:
        $schema: kno-section@0.0.1
        id: history
        title: "History Architecture"

        content:
          principle: |
            History is XRI-driven: embedded versions use fragment XRIs (#history/v0.5.0),
            external versions use absolute XRIs (kno://vcs/kno/v0.4.0).

            The relationship between embedded and external history emerges naturally
            from XRI resolution — not from declarative policy declarations.

          xri_patterns:
            - pattern: "#history/v{version}"
              meaning: "Embedded snapshot — exists in this file"
              example: "#history/v0.5.0"

            - pattern: "kno://vcs/{entity-id}/v{version}"
              meaning: "External snapshot — resolve via VCS service"
              example: "kno://vcs/kno/v0.4.0"

            - pattern: "kno://{authority}/history/{entity-id}"
              meaning: "External history index — list of available versions"
              example: "kno://possibility.space/history/kno"

          architecture: |
            ┌─────────────────────────────────────────────────────────────┐
            │  EMBEDDED HISTORY (this file)                               │
            │  #history/v0.6.0 ← current                                  │
            │  #history/v0.5.0 ← previous                                 │
            ├─────────────────────────────────────────────────────────────┤
            │  EXTERNAL HISTORY (via XRI resolution)                      │
            │  kno://vcs/kno/v0.4.0                                       │
            │  kno://vcs/kno/v0.3.0                                       │
            │  kno://vcs/kno/v0.2.0                                       │
            │  ...                                                        │
            └─────────────────────────────────────────────────────────────┘

          external_types:
            - type: "Extended"
              description: "External has MORE than embedded (embedded is subset)"
              xri_relationship: "External XRIs point to versions not in #history/*"

            - type: "Mirror"
              description: "External duplicates embedded (backup/redundancy)"
              xri_relationship: "Same versions available at both #history/* and kno://vcs/*"

            - type: "External-Only"
              description: "No #history/* — all versions at external XRIs"
              xri_relationship: "Entity has no embedded history; all via kno://vcs/*"

          note: |
            These "types" are not declarative policies — they describe the
            relationship between which XRIs resolve. The architecture emerges
            from what's present, not from what's declared.

  # ===========================================================================
  # @kno:history
  # This entity's own history (demonstrating P9)
  # ===========================================================================
  history:
    $schema: kno-section@0.0.1
    id: history-section
    title: "Version History"

    content:
      description: |
        This section demonstrates P9 (Temporal/Historical) by embedding
        actual version snapshots. Each snapshot is a valid .kno entity
        that can be extracted and used independently.

        Versioning was reset to 0.0.x to reflect early experimental status.
        All prior explorations are preserved as historical snapshots.

      current_version: "0.0.4"
      embedded_versions: [ "0.0.4", "0.0.3", "0.0.2", "0.0.1" ]
      external_versions_xri: "kno://vcs/kno-spec"
      external_note: "Older versions accessible via XRI resolution"

    _contains:
      # @kno:history/v0.0.4
      v0.0.4:
        $schema: kno-snapshot@0.0.1
        id: kno-spec-v0.0.4
        version: "0.0.4"
        date: "2026-01-07"
        author: "pspace-core-team"

        summary: "Removed audience and facets.complexity fields (DC-1, DC-2)"

        changes:
          - "Removed `audience` field from STANDARD tier"
          - "Removed `facets.complexity` field from STANDARD tier"
          - "Per DC-1: All .kno files serve all audiences by design"
          - "Per DC-2: No subjective fields (complexity is context-dependent)"
          - "Added 'no subjective fields' corollary to DC-2 in bedrock"

        rationale: |
          The `audience` field contradicted DC-1 (Triple-Audience Consumption),
          which mandates that ALL .kno files serve programmatic, agentic, AND
          human audiences equally. A per-file audience declaration was superfluous.

          The `facets.complexity` field violated DC-2 (Minimalism) because
          complexity is inherently subjective — what's complex to one reader
          may be simple to another. The format's strength is that the SAME file
          adapts to the needs of different readers.

        key_fields:
          id: "kno-spec"
          type: "schema"
          title: "Knowledge Notation Object Specification"

      # @kno:history/v0.0.3
      v0.0.3:
        $schema: kno-snapshot@0.0.1
        id: kno-spec-v0.0.3
        version: "0.0.3"
        date: "2026-01-07"
        author: "pspace-core-team"

        summary: "Removed deprecated fields; consolidated format explorations"

        changes:
          - "Removed deprecated `kno_type` field (use `type` instead)"
          - "Removed deprecated `kno_version` field (use `version` instead)"
          - "Removed `facets.layer` field (per P6/P10)"
          - "Absorbed kno-format.kno (v0.0.1) into history"
          - "Single canonical reference file for all .kno format knowledge"

        key_fields:
          id: "kno-spec"
          type: "schema"
          title: "Knowledge Notation Object Specification"

      # @kno:history/v0.0.2
      v0.0.2:
        $schema: kno-snapshot@0.0.1
        id: kno-spec-v0.0.2
        version: "0.0.2"
        date: "2026-01-07"
        author: "pspace-core-team"

        summary: "Original kno-spec.kno (v0.5.x series) — experimental format spec"

        description: |
          This represents all work from the original kno-spec.kno file, which
          iterated through versions 0.1.0 to 0.5.1 exploring format concepts.

          Key ideas explored in this lineage:
          - Progressive tier model (BASIC → STANDARD → RICH → FEDERATED)
          - Packed/Unpacked dual-format model (later abandoned for single-file)
          - XRDS-inspired identity and service discovery
          - Tooling CLI specifications (pack, unpack, flatten, validate, merge)
          - Git integration patterns (.gitattributes, merge drivers)
          - History via _history blocks

        lineage:
          - version: "0.5.1"
            date: "2026-01-06"
            summary: "Aligned terminology with bedrock docs (packed/unpacked)"
          - version: "0.5.0"
            date: "2026-01-01"
            summary: "Added $format, _history, merge, tooling, git integration"
          - version: "0.4.2"
            date: "2025-12-30"
            summary: "Added rfc and service to kno_type enum"
          - version: "0.4.0"
            date: "2025-12-28"
            summary: "Generalized sections field for domain-specific content"
          - version: "0.3.0"
            date: "2025-12-25"
            summary: "Added $schema field, kno_type, URI scheme"
          - version: "0.2.0"
            date: "2025-12-20"
            summary: "Added XRDS-inspired identity tier, services tier"
          - version: "0.1.0"
            date: "2025-12-15"
            summary: "Initial KNO specification with BASIC/STANDARD/RICH tiers"

        key_fields:
          id: "kno-spec"
          type: "spec"
          version: "0.5.1"
          title: ".kno File Specification"

        original_file: "kno-spec.kno (2347 lines, consolidated into v0.0.3)"

      # @kno:history/v0.0.1
      v0.0.1:
        $schema: kno-snapshot@0.0.1
        id: kno-spec-v0.0.1
        version: "0.0.1"
        date: "2026-01-07"
        author: "pspace-core-team"

        summary: "Container format exploration (kno-format.kno) — .kno/.kaml
          distinction"

        description: |
          This represents the kno-format.kno file which explored the 
          container/document distinction:

          Key insight: ".kno is the CONTAINER, .kaml is the DOCUMENT FORMAT inside"

          Concepts explored:
          - .kno as ZIP-like container (analogous to .epub, .docx)
          - Packed (.kno file) vs Unpacked (.kno/ directory) equivalence
          - manifest.kaml as the root entity
          - assets/ for binary attachments
          - history/ for version snapshots
          - XRI addressing scheme (kno://authority/path#fragment)

          This exploration influenced the final design but was superseded
          by the single-file KAML approach where containers are nested
          via _contains rather than directory structure.

        key_ideas:
          container_analogy: |
            .epub  = container for .xhtml chapters + images + metadata
            .docx  = container for .xml parts + media + styles
            .kno   = container for .kaml documents + assets + history

          representations:
            packed: "entity.kno (ZIP archive)"
            unpacked: "entity.kno/ (directory)"

          mime_type: "application/vnd.kno+zip"

          structure_explored: |
            my-entity.kno/
            ├── manifest.kaml      # Required: root entity
            ├── assets/            # Optional: binary files
            │   ├── logo.png
            │   └── spec.pdf
            └── history/           # Optional: versioning
                ├── ops.jsonl
                └── snapshots/

        key_fields:
          id: "kno-format"
          type: "format"
          version: "0.1.0"
          title: "KNO Container Format"

        original_file: "kno-format.kno (294 lines, consolidated into v0.0.3)"

        evolution_note: |
          The packed/unpacked directory model was later simplified to
          a single-file KAML approach where:
          - Container structure is expressed via _contains nesting
          - No separate directory form needed
          - History embedded via XRI-addressable snapshots
          - Assets referenced via XRI (external hosting or base64)

  # ===========================================================================
  # @kno:tooling
  # ===========================================================================
  tooling:
    $schema: kno-section@0.0.1
    id: tooling
    title: "Tooling Specification"

    content:
      cli_name: "kno"
      description: "Command-line tool for working with .kno files"

      commands:
        - name: "kno validate"
          description: "Validate .kno file against schema"
          usage: "kno validate <file.kno> [--schema <schema>]"

        - name: "kno index"
          description: "Generate or regenerate _index for a .kno file"
          usage: "kno index <file.kno>"

        - name: "kno resolve"
          description: "Resolve an XRI to its target content"
          usage: "kno resolve <xri> [--format json|yaml]"

        - name: "kno flatten"
          description: "Export for LLM consumption (single text file)"
          usage: "kno flatten <file.kno> [--output <file.txt>]"

        - name: "kno merge"
          description: "Schema-aware three-way merge"
          usage: "kno merge <base> <ours> <theirs>"

  # ===========================================================================
  # @kno:examples
  # ===========================================================================
  examples:
    $schema: kno-section@0.0.1
    id: examples
    title: "Examples"

    _contains:
      # @kno:examples/minimal
      minimal:
        $schema: kno-section@0.0.1
        id: minimal
        title: "Minimal .kno File (BASIC tier only)"

        content:
          example: |
            $schema: kno@0.0.9
            id: my-document
            type: context
            version: 1.0.0

      # @kno:examples/standard
      standard:
        $schema: kno-section@0.0.1
        id: standard
        title: "Standard .kno File (BASIC + STANDARD tiers)"

        content:
          example: |
            $schema: kno@0.0.9
            id: onboarding-guide
            type: instruction
            version: 1.0.0

            title: "New Developer Onboarding"
            purpose: "Guide new developers through project setup"

            # NOTE: `audience` field REMOVED per DC-1 (all .kno files serve all audiences)
            # NOTE: `facets` field REMOVED per DC-2 (domain/category inferred from structure)

      # @kno:examples/full
      full:
        $schema: kno-section@0.0.1
        id: full
        title: "Full .kno File (All tiers)"

        content:
          description: |
            This file you're reading (kno-spec.kno) is a full example.
            It demonstrates:
            - All four tiers (BASIC, STANDARD, RICH, FEDERATED)
            - Container structure with _contains
            - Navigation index with _index
            - Section markers (# @kno:)
            - XRI references
            - Multi-level nesting

# =============================================================================
# @kno:changelog
# =============================================================================
changelog:
  - version: "0.0.3"
    date: "2026-01-07"
    changes:
      - "Consolidated kno-format.kno into history as v0.0.1"
      - "Single canonical file for all .kno format knowledge"
      - "Renumbered: v0.0.2→v0.0.3, v0.0.1→v0.0.2, kno-format→v0.0.1"

  - version: "0.0.2"
    date: "2025-12-15 to 2026-01-06"
    changes:
      - "Original kno-spec.kno iterations (v0.1.0 through v0.5.1)"
      - "Explored progressive tiers, packed/unpacked formats"
      - "XRDS-inspired identity, tooling CLI, git integration"
      - "See #history/v0.0.2 for full lineage"

  - version: "0.0.1"
    date: "2026-01-07"
    changes:
      - "Container format exploration (kno-format.kno)"
      - "Established .kno/.kaml distinction"
      - "Explored packed/unpacked equivalence"
      - "See #history/v0.0.1 for key ideas"

# =============================================================================
# @kno:history-snapshots
# Embedded version snapshots for demonstration of P9
# See _contains.history for the actual snapshot data
# =============================================================================
history_snapshots:
  embedded:
    - xri: "#history/v0.0.4"
      version: "0.0.4"
      date: "2026-01-07"
      note: "Current canonical reference"
    - xri: "#history/v0.0.3"
      version: "0.0.3"
      date: "2026-01-07"
      note: "Removed deprecated fields (kno_type, kno_version, facets.layer)"
    - xri: "#history/v0.0.2"
      version: "0.0.2"
      date: "2025-12-15 to 2026-01-06"
      note: "Consolidates original kno-spec.kno v0.1.0-v0.5.1"
    - xri: "#history/v0.0.1"
      version: "0.0.1"
      date: "2026-01-07"
      note: "Consolidates kno-format.kno container exploration"

  external:
    index_xri: "kno://vcs/kno-spec"
    note: |
      External history is accessed via XRI resolution.
      When an XRI like kno://vcs/entity-id/v1.0.0 is resolved,
      the resolver returns the snapshot from a compliant host.