CogniFlow Ontology

cf_ontology is a data-only package whose maintained output is the packaged ontology N-Quads resources under src/cf_ontology/ontology/** plus the minimal package metadata needed to ship them.

Active semantics behavior is owned by cf_semantics_runtime. That package consumes the packaged ontology N-Quads, discovers installed step packages, and writes the active ontology and step views into the semantics store through service contracts.

Semantics are authored as RDF documents:

• ontology fragments
• step packages
• pipelines

Ownership

This package no longer owns the active runtime surface.

• cf_semantics_runtime is the maintained contract-backed runtime for snapshots, validation, and step-package discovery.
• cf_semantics_store owns the workspace-local RDF semantics store.
• New integrations should not add direct cf_ontology runtime dependencies.

Storage (Semantics Store)

The default RDF semantics store remains under ~/.cogniflow/workspace/semantics, but the maintained runtime behavior is resolved through ProviderKey.SEMANTICS_STORE and the cf_semantics_runtime contracts.

• Pipeline runtime state is handled separately by cf_pipeline_manager.
• Step packages are discovered and materialized by cf_semantics_runtime, not by cf_ontology directly.

Graph IDs (binding conventions)

Step packages

• Split steps (split_steps=True): g = "pkg:{package_name}@{package_version}#{step_id}"
• Unsplit: g = "pkg:{package_name}@{package_version}"

package_name is the StepPackage id (from cf:packageId in steps.nq).

Package upgrades generate new graph ids (the version is part of g). Existing graphs are not deleted; missing/uninstalled packages are marked inactive via graphs.is_active=false.

Pipelines (versioned)

• Stable pipeline identifier: pipeline_id (UUID or user-provided stable id)
• Revision graph: g = "pipe:{pipeline_id}@{rev}" with monotonically increasing rev starting at 1
• "Current" is a pointer in the pipelines table (no separate quad graph)

What is included

• Packaged N-Quads fragments: ontology/core/*.nq, ontology/foundations/contracts/*.nq, ontology/vocab/*.nq, and ontology/shapes/*.nq.
• Packaged ontology resources consumed by cf_semantics_runtime.
• Step-package manifests and other RDF assets that are ingested through the runtime contracts.

Installation

From the sandcastle/cf_ontology directory:

pip install .

Published distribution name:

pip install cf-ontology

Optional (for unified cf CLI integration):

pip install -e ../cf_core_cli

Usage

Policy: all reads and writes to the semantics store must go through the cf_semantics_runtime and cf_semantics_store service-contract boundary. Do not access cf-*.store.db files directly from other packages.

Data-only runtime ownership

cf_ontology does not own the active runtime APIs, installers, or pipeline revision machinery.

• cf_semantics_runtime ingests packaged ontology and step-package N-Quads, discovers installed step packages, and materializes the active semantics store views through contracts.
• cf_semantics_store owns the RDF store layout.
• cf_pipeline_manager owns runtime state, run history, and revision metadata.

Step package entry point convention

Entry point group: cogniflow.steps

Supported entry point values:

• Resource path: some_pkg_module:steps.nq (path relative to that package/module)
• Loader function: some_pkg_module:load_steps returning an RDF document dict or JSON string

Package metadata is read from the cf:StepPackage node in steps.nq (cf:packageId / cf:packageVersion).

Normative documentation in repository-tracked ontology assets is SKOS-only:

• skos:prefLabel
• skos:definition
• skos:scopeNote
• skos:example

The cf_web-facing step DTO contract keeps those four fields as the standard documentation surface for steps, ports, and parameters, and exposes bounded adaptive SKOS metadata only when present:

• skos:altLabel
• skos:notation
• skos:inScheme
• skos:broader
• skos:narrower
• skos:related

The adaptive surface is intentionally constrained. cf_ontology only ships the packaged RDF assets; it does not expose an unrestricted predicate dump or runtime write path to downstream services or the browser.

Pipeline plugins header

Pipelines should also declare plugin directories so the runner can load implementations without --plugins:

{
  "@id": "ex:MyPipeline",
  "@type": "cf:ProcessingPipeline",
  "cf:hasPluginsHeader": { "@id": "ex:pluginsHeader" }
},
{
  "@id": "ex:pluginsHeader",
  "@type": "cf:PluginsHeader",
  "cf:pluginPath": [
    "path/to/plugin/bin",
    "path/to/other/plugin/bin"
  ]
}

Publishing

cf_ontology is published with the dedicated Windows workflow:

• Workflow: .github/workflows/cf_ontology_windows_publish.yml
• Package directory: sandcastle/cf_ontology
• PyPI tag: cf-ontology-v<version>
• TestPyPI tag: cf-ontology-v<version>-test

Local preflight:

powershell -ExecutionPolicy Bypass -File scripts/mimic_windows_python_publish_workflow.ps1 `
  -WorkflowFile .github/workflows/cf_ontology_windows_publish.yml `
  -PackageDir sandcastle/cf_ontology `
  -PythonExe py `
  -PythonVersion 3.14

The workflow test phase is expected to run the full package test surface from sandcastle/cf_ontology via:

python -m pytest tests -q

This hard gate should stay aligned with the package contents under cf-package.yaml and the packaged ontology resources shipped from src/cf_ontology/ontology/**.

Queue a dry-run dispatch:

powershell -ExecutionPolicy Bypass -File scripts/queue_windows_python_publish_workflow.ps1 `
  -WorkflowFile .github/workflows/cf_ontology_windows_publish.yml `
  -PackageDir sandcastle/cf_ontology `
  -PublishTarget testpypi `
  -Ref main `
  -RequireLocalPass `
  -DryRun