Overview

OKF Store is an ODC app providing entity storage, ingestion, and trust-aware read access for Open Knowledge Format (OKF) v0.2 knowledge bundles.

It ingests a bundle from a zip archive, parses every concept's frontmatter through OkfParsingLibrary, and persists concepts, tags, sources, verifications, and resolved links between concepts. Trust tier and lifecycle status are derived at query time from the underlying records rather than stored directly, so they always reflect a concept's actual verification history rather than a value that could drift out of sync.

A set of service actions expose bundle discovery, concept retrieval by path, filtered multi-concept search, and link traversal in both directions. These are designed to be called directly or wrapped as agent tools, as OKF Agent does on top of this app.

OKF Store implements the consumer side of OKF v0.2, reading and storing conformant bundles. There is no producer or export action in this release.

Installation

1. Install OkfParsingLibrary first. OKF Store depends on it directly for frontmatter parsing, archive extraction, and link extraction, and will not publish without it.
2. Install OKF Store from Forge, or import the .oml if installing from a release package.
3. Publish the app. No Site Properties, REST integrations, or external connections need configuring; OKF Store has none.

Configuration

OKF Store ships with three timers, none scheduled by default.

1. Open IngestBatch and LinkResolution in Service Studio and set both to run every 5 minutes, the minimum interval ODC allows. These process newly ingested bundles and resolve their links; see Ingesting a Bundle below for why both are needed.
2. Leave ResetData unscheduled. It deletes all data across every OKF Store entity and exists for development and testing only.

Ingesting a Bundle

Ingestion is a three-step process, not a single action.

1. Upload. Use the Ingest Bundle screen, or call Ingest_BundleArchive directly, with a zip archive and a bundle name. BundleName must be unique unless Overwrite is set. This creates the Bundle record and stages every file in BundleIngestionQueue. No Concept records exist yet at this point.
2. IngestBatch runs. On its schedule, this timer processes every staged file: parsing frontmatter through OkfParsingLibrary and creating Concept, ConceptTag, ConceptSource, and ConceptVerification records. Every concept created this way is flagged NeedsLinkResolution.
3. LinkResolution runs. On its schedule, this timer resolves outbound links for flagged concepts. Until it runs, a concept's links exist as unresolved raw paths, and Get_ConceptByPath's RelatedConcepts and ReferencedBy fields will be incomplete.

With both timers on a 5-minute schedule, allow up to roughly 10 minutes after upload before a bundle is fully queryable with links resolved.

Why timers, not a Workflow: an ODC Workflow was considered, to run staging, parsing, and link resolution as one orchestrated process immediately after upload. Workflows can't be packaged into a Forge component; a workflow module has to be downloaded as its own .oml file from a separate location and installed manually by each user, outside the normal Forge install flow. Two scheduled timers, while not instant, work within what a single Forge install can actually deliver.

Querying Data

Eleven Service Actions make up the public API. Every read action returns a Result structure (IsSuccess, Message) instead of throwing on a not-found condition.

• Ingest_BundleArchive — ingests a zip archive as a named bundle. See Ingesting a Bundle above.
• List_Bundles — returns every ingested bundle, with Id and name. No inputs.
• Get_BundleIndex — returns a lightweight index of concepts in a bundle: path, title, type, status, trust tier, without the full body. Takes BundleId and an optional DirectoryPath to scope to part of the bundle.
• Get_Concept — returns one concept's full detail by internal Id.
• Get_ConceptByPath — returns one concept's full detail by BundleId and ConceptPath, the way most callers will address a concept. Includes resolved outbound links (RelatedConcepts) and inbound links (ReferencedBy) already attached.
• List_Concepts — returns a filtered list of concepts. Takes BundleId as its own top-level input, and a Filter structure for everything else. See The ConceptFilter Shape below.
• Get_OutboundLinks / Get_OutboundLinksByPath — return a concept's resolved outbound links, by internal Id or by BundleId + ConceptPath.
• Get_InboundLinks / Get_InboundLinksByPath — return the concepts that link into a given concept, by internal Id or by BundleId + ConceptPath.
• DownloadLatestTrace — returns the most recent agent session's trace log as a downloadable JSON file. Not part of the knowledge query API; exists to support debugging an agent built on top of OKF Store.

The ConceptFilter Shape

List_Concepts takes BundleId as its own top-level parameter, separate from Filter. Everything else that narrows a result sits inside Filter, a ConceptFilter structure with six fields:

• MinTrustTierId — TrustTierOption Identifier, required. One of the three trust tier records (Unverified, MachineConfirmed, HumanReviewed). This is an entity Identifier, not free text; a caller needs to resolve a tier name to its Id before calling. Callers that only have a tier as a string, an LLM-facing tool, for instance, should translate it to the correct Identifier at their own boundary.
• TypeFilter — Text, optional. Blank matches any concept type.
• StatusFilter — Text, optional. Blank matches any status.
• IsExcludeStale — Boolean, optional. Requires AsOfDate to also be set.
• IsExcludeDeprecated — Boolean, optional.
• AsOfDate — Date, required only when IsExcludeStale is True. Evaluates a concept's StaleAfter date against a caller-supplied point in time rather than the current date.

Entities

• Bundle — an ingested OKF bundle. Name is unique across every bundle, which is what makes cross-bundle links resolvable by name. Records OkfVersion, the original archive, and a maintained ConceptCount.
• Concept — one markdown file within a bundle, .md stripped from its path. ConceptPath is unique within a bundle. Status is stored as "stable", "deprecated", or blank; blank resolves to "stable" at query time. StaleAfter uses 1900-01-01 to represent no staleness date. ExtraFrontMatter preserves any frontmatter key not otherwise modeled, as JSON.
• ConceptTag, ConceptSource, ConceptVerification — one row per tag, cited source, or verification record on a concept, each with a SortOrder. ConceptVerification.VerifiedBy values prefixed "human:" are what trust tier derivation reads to identify human-attributed verification.
• ConceptLink — one outbound markdown link from a concept to another, same bundle or a different one. TargetConceptId and TargetBundleId are nullable, since a link may not resolve. IsResolved and IsCrossBundle record the outcome.
• BundleIngestionQueue — staging table holding each file from an archive between upload and processing.
• BundleAuxFile — holds the two reserved, non-concept files a bundle may contain, index.md and log.md, distinguished by FileKind.
• TrustTierOption (static) — the three OKF trust tiers, each with a Rank used to compare against a minimum threshold.
• IngestSource (static) — records how a bundle was ingested: Native, ZipUpload, SingleFileUpload, or UrlFetch.

Dependencies

OKF Store calls into OkfParsingLibrary directly for frontmatter parsing, archive extraction, link extraction, and legacy citation parsing. No Site Properties, REST or SOAP integrations, or AI provider references exist in OKF Store itself; everything LLM-facing lives one layer up, in OKF Agent.