id: https://conceptkernel.org/ontology/v3.4/
name: conceptkernel-org-v1
title: ConceptKernel Governance Schema
description: >
  LinkML schema governing Concept Kernel shape. Drives scaffolding tool —
  the tool reads this schema to create CK folders and enforce structure.
  Aligned with BFO2020 + PROV-O.

prefixes:
  ck: https://conceptkernel.org/ontology/v3.4/
  bfo: http://purl.obolibrary.org/obo/BFO_
  prov: http://www.w3.org/ns/prov#
  linkml: https://w3id.org/linkml/

default_range: string

classes:

  Kernel:
    class_uri: bfo:0000040
    description: >
      A sovereign concept kernel — one capability, one identity, one tool.
      BFO Material Entity. Folder prefix: CK.{Name}
    attributes:
      apiVersion: { required: true, ifabsent: "conceptkernel/v1" }
      kind: { required: true, ifabsent: "Kernel" }
      metadata: { range: KernelMetadata, required: true }
      spec: { range: KernelSpec, required: true }

  KernelMetadata:
    attributes:
      name:
        required: true
        pattern: "^[A-Z][a-zA-Z]+\\.[A-Z][a-zA-Z]+$"
        description: "{Domain}.{Name} PascalCase"
      urn:
        required: true
        pattern: "^ckp://Kernel#.+:v\\d+\\.\\d+$"
      version: { required: true }
      created_at: { range: datetime }

  KernelSpec:
    attributes:
      type: { range: KernelType, required: true }
      description: { required: true }
      nats: { range: NATSConfig, required: true }
      tool: { range: ToolSpec, required: true }
      web: { range: WebConfig }
      resources: { range: ResourceSpec }
      edges: { range: EdgeSpec }
      lifecycle: { range: LifecycleConfig }
      workspace: { range: WorkspaceConfig }
      governance_mode: { range: GovernanceMode, required: true }

  NATSConfig:
    attributes:
      input_topic: { required: true }
      result_topic: { required: true }
      event_topic: { required: true }
      conversation: { range: ConversationConfig }

  ConversationConfig:
    description: >
      When enabled, kernel accepts conversation over NATS WSS
      and streams responses back to result topic.
    attributes:
      enabled: { range: boolean, required: true }
      stream_responses: { range: boolean }

  ToolSpec:
    attributes:
      language: { required: true }
      entrypoint: { required: true, ifabsent: "tool/processor.py" }
      runtime: { required: true }

  WebConfig:
    description: >
      If serve=true, web/index.html is deployed to subdomain via
      ConfigMap + nginx + Service + HTTPRoute.
    attributes:
      serve: { range: boolean }
      subdomain: {}

  ResourceSpec:
    attributes:
      requests: { range: ResourceLimits }
      limits: { range: ResourceLimits }

  ResourceLimits:
    attributes:
      cpu: {}
      memory: {}

  EdgeSpec:
    attributes:
      outbound:
        range: Edge
        multivalued: true

  Edge:
    class_uri: bfo:0000031
    description: First-class BFO GenericallyDependentContinuant (information entity) mediating K-to-K communication
    attributes:
      target_kernel: { required: true }
      predicate: { range: EdgePredicate, required: true }
      nats_subject: { required: true }
      requires_consensus: { range: boolean }
      requires_target_auth: { range: boolean }

  LifecycleConfig:
    description: For temporal CKs (sites spawned for limited duration)
    attributes:
      temporal: { range: boolean }
      duration: { description: "ISO 8601 duration (e.g. P30D)" }
      created_by: { description: "URN of the factory kernel that created this CK" }

  WorkspaceConfig:
    description: >
      Virtual desktop layout config for CK.Layout. Controls how
      VS Code + Terminal are tiled on a virtual desktop via yb runners.
    attributes:
      runner:
        description: "yb runner script name (split, tile, solo)"
        ifabsent: "split"
      bar:
        description: "SketchyBar style (standard, minimal, none)"
        ifabsent: "standard"
      gap:
        range: integer
        description: "Pixel gap between tiled windows"
        ifabsent: "0"
      padding:
        description: "Window padding T,B,L,R (e.g. 52,0,0,0)"
        ifabsent: "52,0,0,0"
      zoom:
        range: integer
        description: "VS Code zoom level (Cmd+= count)"
        ifabsent: "0"
      cmd:
        description: "Optional command to run in Terminal"

  Instance:
    class_uri: bfo:0000031
    description: >
      Immutable result artifact (BFO GenericallyDependentContinuant).
      Stored at instances/i-{identifier}/
    attributes:
      id: { required: true }
      created_at: { range: datetime, required: true }
      status: { range: InstanceStatus, required: true }
      kernel_urn: { required: true }

  FolderStructure:
    description: >
      Three Loops directory structure for every CK. The scaffolding tool
      reads this to create compliant CK directories. Each loop is an
      independently-versioned volume on SeaweedFS.
    attributes:
      ck_loop_files:
        range: string
        multivalued: true
        ifabsent: '["conceptkernel.yaml", ".ck-guid", "README.md", "CLAUDE.md", "SKILL.md", "CHANGELOG.md", "ontology.yaml", "rules.shacl", "serving.json"]'
        description: "Files at CK root (identity loop — ck-{guid}-ck volume)"
      tool_dir:
        ifabsent: "tool/"
        description: "Tool loop directory (capability — ck-{guid}-tool volume)"
      storage_dir:
        ifabsent: "storage/"
        description: "Data loop directory (knowledge — ck-{guid}-storage volume)"
      storage_subdirs:
        range: string
        multivalued: true
        ifabsent: '["instances/", "ledger/", "proof/", "index/", "llm/", "web/"]'
        description: "Required subdirectories under storage/"
      instance_prefix:
        ifabsent: "i-"
        description: "Instance folder prefix"

enums:

  KernelType:
    permissible_values:
      node:cold: { description: "Always running, low latency" }
      node:hot: { description: "Scales to zero, on-demand" }
      service: { description: "Stateful service" }
      agent: { description: "Autonomous agent" }

  GovernanceMode:
    permissible_values:
      STRICT: { description: "Unanimous consensus" }
      RELAXED: { description: "Simple majority" }
      AUTONOMOUS: { description: "Owner only" }

  EdgePredicate:
    permissible_values:
      PRODUCES: {}
      REQUIRES: {}
      TRIGGERS: {}
      CONSUMES: {}
      ENHANCES: {}
      VALIDATES: {}
      TRANSFORMS: {}

  InstanceStatus:
    permissible_values:
      pending: {}
      active: {}
      completed: {}
      failed: {}
      archived: {}