#OKF Knowledge Packages

OKF (Open Knowledge Format) is an open knowledge-package format for people and agents: just Markdown, just files, just YAML frontmatter. A3S Use accepts only OKF v0.2, which organizes shareable domain knowledge as a typed, cross-linked, incrementally indexable concept graph.

In A3S Use, OKF is a first-class cognitive surface alongside Tool, MCP, Flow, Skill, and UI, but it is not an executable workload.

Current status: the standalone lifecycle includes a bundled cross-platform SQLite/FTS5 Knowledge backend, complete User/Workspace isolation, transactional stage/promote/remove, exact projection-authorized cited search, restart recovery, bounded storage quota/retention/GC, scope-local integrity audit, verified database backup with exact-plan oldest-first rotation, authority-preserving FTS repair, authority-bound database and exact-subset missing-binding restore, and signed real-process coverage. Reviewed same-version/OS/architecture whole-installation restore is also implemented. A3S Code-managed leased-query qualification, missing Registry/package/lifecycle/Grant authority and clean-machine recovery, cross-platform operational drills, rollback-evidence retention policy, and whole-product disaster recovery remain pending; without exact promoted evidence, the surface is not published.

#Bundle structure

An OKF bundle is a bounded directory. Each non-reserved Markdown file represents one concept; its bundle-relative path without .md is the concept ID. An optional index.md provides hierarchical navigation, and an optional log.md may record history at any level.

okf/domain-knowledge/
├── index.md
├── concepts/
│   ├── index.md
│   ├── package-lifecycle.md
│   └── runtime-boundary.md
├── decisions/
│   ├── index.md
│   └── no-provider-fallback.md
└── log.md

Concepts use standard Markdown links rather than a private wikilink syntax:

See [Runtime boundary](/concepts/runtime-boundary.md).

#Concept contract

Every non-reserved concept is UTF-8 Markdown beginning with a properly delimited YAML frontmatter block. OKF requires one field: a non-empty scalar type.

---
type: Architecture Decision
title: No provider fallback
description: Why plugin workloads require one explicit Runtime provider.
resource: docs/adr-001-plugin-runtime-broker-boundary.md
tags: [runtime, security, plugins]
generated:
  by: a3s-okf-compiler/1.0
  at: 2026-07-31T00:00:00Z
sources:
  - id: runtime-boundary
    resource: docs/adr-001-plugin-runtime-broker-boundary.md
    title: Runtime Broker ADR
---

title, description, resource, and tags are recommended fields. OKF v0.2 also defines optional provenance, trust, lifecycle, and attested-computation families. Producer extension keys and unknown concept types remain conformant and must be preserved. A3S Use does not reinterpret older timestamp or # Citations layouts as v0.2 authority.

index.md and log.md are reserved rather than concepts. Only the bundle-root index.md may contain frontmatter, and only to declare okf_version. Missing indexes and safe dangling links remain conformant and are reported as diagnostics rather than rejected.

#Relationship to other surfaces

OKF v0.2 may describe an Attested Computation, executor, and attester. A3S Use treats all of that as inert metadata. It never turns those fields into execution authority; runnable behavior still requires a separately declared and authorized Tool or host binding.

#Install and index boundary

The lifecycle reuses A3S Use package identity, plans, receipts, and capability generations:

signed catalog
  → review exact OKF digest, concept count, bytes, provenance
  → verify package and bounded OKF conformance
  → stage exact package generation
  → A3S Knowledge builds/stages its deterministic index
  → atomically promote the candidate OKF generation
  → publish the shared capability snapshot

A3S Use owns package and bundle integrity. The Knowledge host owns conformant promotion, indexing, and cited retrieval. Current results cite the exact package, surface, generation, projection receipt, index, concept path, and source digest; they do not claim line-level citation. If candidate validation or indexing fails, the last successful generation remains searchable.

The frozen host boundary uses three canonical records:

• a3s.use.okf-projection-receipt.v2 for the exact full-scope staged candidate;
• a3s.use.okf-knowledge-observation.v2 for full-scope staged, promoted, failed, or removed state plus last-good selection; and
• a3s.use.okf-capability-projection.v2 for exact full-scope promoted evidence safe to publish.

The standalone backend keeps one SQLite/FTS5 database per complete scope. A current capability snapshot selects the newly promoted generation. An already-open session holding the exact prior projection may continue querying it during drain; receipt-owned removal invalidates that projection. Unknown database user_version values are rejected without migration or rewrite because no stable Knowledge database format has shipped yet.

#Storage policy and diagnostics

The default standalone policy bounds each complete User or Workspace scope to:

• 512 MiB of retained expanded OKF content;
• 256 retained projections across all packages and surfaces;
• 32 retained generations for any one surface; and
• 256 scope-wide removal tombstones.

Expanded bytes come from each immutable projection receipt and are revalidated when accounting is rebuilt after restart. Staging checks byte and projection quota inside the same immediate transaction that inserts the candidate, so a rejected candidate cannot change the selected generation or consume a partial row. Receipt-owned removal frees quota, globally prunes old tombstones, vacuums free SQLite pages, and truncates the WAL.

Inspect an exact User or Workspace installation without reading concept content:

a3s-use knowledge usage \
  --scope-kind user \
  --scope-id user/current \
  --json
a3s-use knowledge usage \
  --scope-kind workspace \
  --scope-id workspace/acme-project \
  --json

The report includes retained projections, tombstones, expanded bytes, active policy limits, allocated database bytes, and reclaimable bytes. Every diagnostic requires an explicit installation identity; the CLI never guesses a current User or Workspace installation.

Audit the current database without exposing concept content:

a3s-use knowledge audit \
  --scope-kind user --scope-id user/current --json

Audit verifies SQLite integrity, foreign keys, exact receipt/scope accounting, and FTS consistency. Create and then independently verify a non-overwriting scope snapshot:

a3s-use knowledge backup ./user.a3s-okf-backup \
  --scope-kind user --scope-id user/current --json
a3s-use knowledge verify-backup ./user.a3s-okf-backup \
  --scope-kind user --scope-id user/current --json
a3s-use knowledge backup-retention ./backups \
  --scope-kind user --scope-id user/current --json

The versioned backup manifest binds complete scope, creation time, exact database length and SHA-256, storage accounting, and policy limits. The digest detects corruption; it is not a package or Registry signature. The artifact does not contain Registry receipts, immutable package roots, Knowledge bindings, lifecycle journals, Grants, Flow history, or UI state.

The inactive Control Store qualification layer now wraps this format in a stricter owner snapshot. Under one exclusive installation maintenance fence it binds the archive to the canonical Control export digest, hashes the exact retained-binding/selection inventory, and enforces the registered limit over the complete archive before publication. A missing database becomes an explicit zero-file manifest without creating live Knowledge state. This is not a CLI or production-backup path yet. Both live and offline verification also require the exact bound Control export, exact prepare/bundle origin, matching applied observation/projection evidence, and a remove effect for removed or missing applied payload. The Control join runs against the temporary SQLite snapshot before the archive is written, so semantic failure leaves neither an archive nor a receipt. Deferred effects remain safe-no-effect scheduling evidence; claimed and unknown effects remain reconciliation evidence only. None selects desired state. A verified owner snapshot can now stage and re-audit its exact database beneath a clean target state root without changing live Knowledge. Activation requires that target's exclusive maintenance fence, rejects unowned, existing, or ambiguous state, and publishes by one replayable atomic rename. The result is path-free and snapshot-bound; post-rename retry requires the same staged attempt and fence. The private complete-set snapshot coordinator now includes this exact Knowledge snapshot in the same canonical, single-file archive as the Control export and every registered owner, then reuses this offline verifier before no-clobber publication. The verified aggregate now preflights the exact Knowledge policy before touching a target, binds it in one path-free complete-attempt descriptor, and stages this database beside Control and every owner candidate under one retained exclusive fence. The live Knowledge root is unchanged. Complete-set activation, durable cross-owner recovery, and production backup/restore wiring remain pending.

backup-retention returns a canonical plan for at most 4,096 directory entries, one complete scope, and bounded backup-count/byte limits. It fully verifies managed candidates, selects the oldest required prefix, and preserves the last verified scope backup. Removal requires --yes plus the unchanged --plan-digest; another scope, unrelated files, linked candidates, and stale plans cannot be removed.

If audit reports only a derived FTS mismatch, an operator may explicitly rebuild FTS from already-validated documents:

a3s-use knowledge repair-search-index \
  --scope-kind user --scope-id user/current --yes --json

Repair never edits projection receipts, selected generations, bindings, lifecycle evidence, or Grants.

Never copy a backup into live state. Create a path-free review and apply only its exact digest:

a3s-use knowledge plan-restore ./user.a3s-okf-backup \
  --scope-kind user --scope-id user/current --json
a3s-use knowledge restore ./user.a3s-okf-backup \
  --scope-kind user --scope-id user/current \
  --plan-digest sha256:<reviewed-plan-digest> \
  --yes \
  --json
a3s-use knowledge restore-status \
  --scope-kind user --scope-id user/current --json

Planning verifies the backup, exact package/lifecycle/Registry/Grant authority, and an exact-subset current binding inventory, then binds that state and the current main database, WAL, and SHM. Confirmed apply revalidates the same authority, creates only missing exact binding files, retains the exact prior database files, and resumes its durable operation after process exit. Conflicting or newer binding evidence is never overwritten. It cannot recreate missing independent authority, recover a clean machine or another state family, or provide whole-product disaster recovery. Scope-local backup rotation does not rotate restore rollback evidence or other state families. See the OKF Knowledge operations runbook.

restore-status needs neither a backup path nor a plan digest. Its bounded, path-free diagnostic reports any global active phase plus the requested scope's validated operation history, marker-handoff directory count, and remaining capacity. It does not rotate, delete, or rewrite recovery evidence.

#Compilation is not installation

PDF, Office, image, email, archive, and web content are compiler inputs—not OKF search authority. An independent knowledge compiler may normalize those sources into OKF, but the install plan reviews the final normalized bundle. Installation does not download or execute a compiler that changes reviewed content.

#Security and uninstall

• Concept text, frontmatter, links, and compiler provenance cannot change ACL policy or grants.
• Paths, file count, expanded bytes, document bytes, and links per document are bounded. A safe dangling link is diagnostic; a reference that resolves outside the package boundary is rejected.
• Search admits only a conformant generation atomically promoted by the host; it never infers success from a staging directory.
• Disable only hides the OKF capability from new sessions.
• Uninstall removes only package receipt-owned projection/index content, never personal notes, raw sources, or another package's index.

See the roadmap and the repository's Managed Knowledge workstream for the remaining implementation order.