Open Context Domain Glossary

This document defines the shared domain language used by OCTX and by its integrations with SAG and zleap-sag.

OCTX Terms

OCTX Format: OCTX is the abbreviation and technical identifier for Open Context, and its published files use the .octx extension. It is an open, vendor-neutral context-asset packaging and derived-data standard built on OKF knowledge content. It adds identity, versioning, integrity, installation semantics, and optional indexing layers. SAG and zleap-sag are producers and consumers, but neither is a prerequisite for using OCTX. OCTX does not define search APIs, retrieval algorithms, or Agent protocols. Avoid: OKF competitor format, SAG proprietary format, database backup format, zleap-sag storage format

OCTX Reference Tooling: A specification implementation independent of any knowledge system. It provides OCTX create, open/inspect, validate, and unpack operations, along with JSON Schema Draft 2020-12, fixed Arrow schemas, canonical examples, and conformance tests. The public creation entry point handles both initial identity establishment and subsequent Releases, while read entry points do not write to a knowledge database. Database mapping, content extraction, and index construction are the responsibility of each system's adapter layer. Avoid: zleap-sag, SAG importer, knowledge extraction engine

OCTX Knowledge Document / OKF Concept: A Markdown file in an OCTX Package that follows the OKF Concept conventions. It is the only formal Document in v0.1 and is a knowledge unit that people and Agents can read, link, and maintain directly. The OKF-reserved index.md and log.md files are navigation and log files, not Knowledge Documents. The document path provides OKF navigation, while octx.document_id in frontmatter provides cross-version and derived-data references. Pre-conversion PDF, DOCX, and similar files do not enter OCTX v0.1. Avoid: pre-conversion PDF, chunk, event, database row

OCTX Frontmatter Namespace (octx): The object in a Knowledge Document's YAML frontmatter dedicated to OCTX extension fields. v0.1 defines document_id inside this object so that the generic name document_id does not occupy OKF's shared top-level field space. Avoid: top-level document_id, octx_id, producer-private field collection

OCTX Capability: An explicitly declared, versioned standard data capability in an OCTX Package. v0.1 defines sag-structured and vectors: the former contains chunks, events, entities, and relations as one unit, while the latter carries optional vectors. The manifest uses the capability name as the key and declares only its version; the specification fixes file paths and dependencies. Avoid: private field collection, separate chunks/events/entities capabilities, database plugin

OCTX Private Extension Data: Data not yet standardized by OCTX, stored under extensions/<reverse-domain-namespace>/<major.minor>/..., for example extensions/com.zleap.sag/1.0/data.jsonl. Every file must be listed in the manifest and participate in the Package Digest. Unknown consumers may ignore its semantics, but must preserve it during a round trip. A private extension cannot replace a standard Capability. Avoid: additional file omitted from the manifest, standard capability, SAG-Structured data

Unknown Optional Field: A manifest, JSON, or JSONL field that the current consumer does not recognize within a supported format or capability version. It does not cause validation failure and should be preserved when the Package is rewritten, but it cannot change the semantics of known fields or satisfy a Capability. Avoid: missing required field, unknown Capability, incompatible version

SAG-Structured Data: An explicit collection of chunks, events, entities, and relations that satisfies the sag-structured/0.1 Capability and can be imported directly into the structure layer by a compatible SAG consumer. It requires every Concept Document to have a Chunk, every Chunk to have an Event, every Event to have an Entity, and every Entity to be used by an Event. Orphan records are not allowed. Missing layers must be generated through genuine chunking or extraction processes; they cannot be synthesized by falling back to content from the preceding layer. Avoid: Markdown-only OCTX Package, local fallback view, incomplete index

OCTX Entity: A semantic entity identified by the producer within an OCTX Asset, rather than an individual textual mention. Every record must have id, name, and a non-empty type; description is optional. OCTX does not prescribe a type vocabulary or naming format. The same entity can be associated with multiple Events and can retain its entity_id across subsequent Releases of the same Asset. normalized_name belongs to the consumer's local index and does not enter OCTX. Identically named entities in independent Assets are not merged automatically. Avoid: entity mention, globally unique entity, record automatically merged by name

OCTX Event: A complete event expression extracted from one or more explicit Chunks that can be understood independently of the original Chunk. Every Event must have id, title, and content, and records its source only through chunk-events.jsonl. A top-level Event omits the hierarchy field and is treated as level 0; a child Event stores both parent_id and level. Avoid: Chunk summary, title-only label, duplicated relation with an embedded chunk_id

OCTX Relation Record: A directed relation expressed in JSONL through the logical IDs at its two endpoints. The relation itself has no UUID: the endpoint ID pair is its identity and must be unique within the corresponding file. An event-entity relation can include weight and description. Avoid: database join-table primary key, duplicate edge, relation creation time

OCTX ID: The UUIDv7 identity used by OCTX for Assets, Knowledge Documents, Chunks, Events, and Entities. It is stored as a canonical lowercase UUID string with hyphens and no type prefix. A Knowledge Document uses octx.document_id; derived records use their respective id fields. An ID represents object identity, while a content digest determines content equality. The two cannot replace one another. Avoid: auto-incrementing database primary key, content digest, private ID with a type prefix

OCTX Asset: A portable knowledge asset that persists across multiple published versions and is identified by a stable asset identity. One OCTX Asset can produce multiple OCTX Packages over time. Avoid: OCTX Package, SAG Source, database record collection

OCTX Release: A versioned publication of an OCTX Asset that records the Package lifecycle from building to ready or failed. A successful Release corresponds to one OCTX Package uniquely identified by its content digest. Avoid: OCTX Asset, OCTX Package, export task

Release Conflict: Two OCTX Packages that each pass complete integrity validation and declare the same asset_id + release.version but have different package_digest values. The importer must warn and require confirmation. Confirmation only switches the current Installation; both immutable Packages and their installation history must be retained. A mismatch between a single Package's declared and calculated digest is an integrity failure, not a Release Conflict. Avoid: silent overwrite, deleting the old Package, treating conflicting digests as the same content

OCTX Working Directory: The editable form of the OCTX logical directory tree, used by people, Agents, and version-control systems to maintain knowledge content. Packaging it as .octx creates a convenient distribution file, but both forms share the same logical content structure. Avoid: OCTX Release, temporary extraction cache, database directory

OCTX Package: An immutable knowledge snapshot of one version of an OCTX Asset. It can contain one or more documents and retain traceable evidence and derived knowledge. It can be distributed, validated, and imported independently, and by default becomes a new Source. Avoid: OCTX Asset, single-document package, database snapshot, SAG Source

Package Digest: An immutable digest calculated after validating the per-file SHA-256 values in manifest.files. The calculation removes the digest itself, sorts files by path, applies JCS to the manifest calculation copy, and then applies SHA-256. It identifies the exact content of a Release and is unaffected by ZIP compression level, entry order, archive tool, or safe additional files that are not listed in the manifest. Avoid: ZIP file digest, version number, digital signature

Archive Digest: A transport checksum calculated over the raw bytes of a particular .octx ZIP file. Recompressing the same logical Package can produce a different Archive Digest. Avoid: Package Digest, Asset identity

Derived Asset: An editable knowledge asset that starts from an existing OCTX Release or from readable Markdown in an invalid Package, but has a new asset identity. Through asset.derived_from, it records the direct source's Asset ID, version, and Package Digest, while no longer claiming to be a subsequent version from the original publisher. Recovery from an invalid Package must also generate new valid identities for its documents. An imported Asset enriched locally must become a Derived Asset before it can be exported again. Avoid: new version of the original Asset, Package modified in place, copy without provenance

OCTX Installation: The state in which an OCTX Release has been validated in a local knowledge system and made available as a knowledge collection. In SAG it appears as a managed Source. Upgrading an Installation atomically switches the local collection to a new Release of that Asset; it does not modify an existing Package. A format-valid Package without sag-structured can generate local structure after installation, and the absence of structure is not itself an installation error. Avoid: OCTX Package, import task, extracted directory

Locally Rebuilt Data: Chunks, events, entities, relations, or vectors regenerated from valid OCTX Markdown by a consumer when a Package lacks a structure layer, has an invalid structure layer, or carries incompatible vectors, and then attached to the current Installation. If any layer of the SAG structure is invalid, the entire structure is rebuilt rather than patching individual records or mixing old and new results. Locally Rebuilt Data does not modify the original Package and cannot make an invalid Capability in the original Package valid. Avoid: original Package payload, corrected Release, silently skipped invalid record

Source Chunk: A complete original-text evidence unit retained after a document is parsed and chunked. It is the content boundary ultimately returned by SAG retrieval results and citations. An OCTX Package can omit Source Chunks, but once it declares sag-structured/0.1, it must preserve the complete Chunk text; an event, entity, or summary cannot replace it. Avoid: summary, event, original file

Vector Configuration: The embedding-space declaration stored in vectors/config.json. It contains at least model, dimensions, normalized, and a fingerprint of the complete configuration; revision is optional. OCTX v0.1 permits at most one configuration per Package, shared by all bundled Arrow files. A consumer can reuse vectors only when its local embedding pipeline has the same fingerprint. The numeric type is fixed as float32, while the retrieval distance algorithm is determined locally by the consumer. Avoid: compatibility determined only by model name, API address, key, vendor connection configuration, multi-model configuration collection

SAG Terms

Knowledge Base Application: The complete product used directly by users, including knowledge import, organization, retrieval, provenance, conversation, and reuse capabilities. SAG's brand expression is "your last knowledge base application." Avoid: using "knowledge base" alone to mean the complete product

Knowledge Base: A knowledge collection within a Knowledge Base Application, composed of Sources, documents, and their structured indexes. It is not the application itself. Avoid: application, product

SAG: The complete Knowledge Base Application used directly by users and the product delivered by this repository. Avoid: using SAG alone to refer to the paper's method or a Python package

SAG Retrieval Architecture: The event-entity index and query-time dynamic hyperedge retrieval method originally introduced by the SAG paper. It is not a combination, wrapper, or dual-path retrieval system made from traditional RAG and GraphRAG. Avoid: SAG application, zleap-sag, fusion of RAG and GraphRAG

Unified Retrieval Pipeline: The original event-entity index and execution mechanism through which the SAG Retrieval Architecture provides both semantic-similarity retrieval and relational reasoning. It replaces choosing between traditional RAG and GraphRAG, or deploying two systems and stitching their results together. Avoid: dual RAG, fusion of traditional RAG and GraphRAG, result stitching

zleap-sag: The Python engine that implements the SAG Retrieval Architecture and provides import, extraction, and retrieval capabilities to other applications. It depends on the independent octx reference package, re-exports the general OCTX create/open/validate entry points, and provides import/export adapters between .octx and SAG. Avoid: SAG application

SAG Self-hosted API: The HTTP, OpenAI-compatible, and MCP interfaces provided by the SAG application's FastAPI backend. Developers run SAG on their own servers and use these interfaces to connect custom frontends or external Agents. It is not a public cloud API hosted by the project. Avoid: zleap-sag Python API, public cloud API