OKF Explorer architecture and implementation plan
Assessment date: 23 October 2026. Implementation baseline:
460f7245352e5d1e407d37e9d40a9b2b6b55ee0a.
Status: maintained architecture and prioritised delivery plan. The capability inventory below records the implementation at that baseline. Planned acceptance criteria are future gates, not results already obtained. Update the baseline, evidence and decisions together when capabilities change.
Explorer has a working foundation for governed knowledge, evidence assembly and human inspection. The next milestone is a dependable journey from a question to inspected evidence and a separately assessed explanation. Prioritise that journey before expanding the feature set.
This plan coordinates current priorities. The semantic contract, publication contract and versioned profiles remain the implementation contracts. Dated architecture documents and experiment receipts retain their original scope; this plan does not revise their results.
Product purpose and architecture
Help a person and their AI find, inspect and reuse knowledge while retaining source identity, meaning, authority, rights, dates and visible gaps. An OKF bundle can support discovery and explanation within its declared scope. Professional decisions and operational actions require their own authority.
Keep the small OKF 0.2 core separate from the additive Bundle Wiki and domain profiles. In this plan, OKF+ refers to the richer experimental knowledge and evidence practices around those profiles; it does not introduce a new universal OKF core requirement.
| Layer | Responsibility | Implementation boundary |
|---|---|---|
| Sources and domain authoring | Select sources, retain originals, declare coverage, rights, date roles, concepts, assertions and dependencies | Producer-owned Markdown, YAML-LD and governed source artefacts; domain review remains explicit |
| Build and federation | Validate authored meaning and generate descriptors, JSON/JSON-LD, shards, search indexes and registries | Deterministic projections; independently versioned publication units |
| Evidence assembly | Resolve declared concepts, follow directed assertions and retain whole evidence within explicit budgets | Shared transport-independent context engine; source and engine versions bind each package |
| Human inspection | Search, filter, navigate, read sources, inspect provenance and gaps, and propose corrections | Explorer Reader, reading help and Evidence workbench; a proposal requires separate producer adoption |
| Tool delivery | Expose bounded operations and exact evidence reads | Optional page tools and remote MCP; each has its own source admission, deployment and client observations |
| AI-assisted work | Help author, explain, review and create outputs from admitted evidence | Codex, ChatGPT or another compatible client; model responses remain interpretations with their own assessment |
Assurance spans all layers: source constraints, semantic validation, A–H context evaluation, failure controls, browser journeys and exact-candidate publication. Search ranking, graph layout and model confidence must not upgrade authority or turn missing evidence into a negative fact. Preserve asserted, normalised, inferred, model-derived, synthetic and historical material as distinct planes.
The federated architecture, context decision and Evidence workbench describe these existing seams. The ontology design also contains future inference and validation proposals; its presence is not evidence that every proposed standards capability is implemented.
Capability inventory
These labels describe implementation maturity, separately from a bundle's
semantic status, publication authority or live service health:
- Implemented: code and contracts exist for the stated scope. Acceptance evidence and deployment claims remain limited to their recorded revisions.
- Experimental: an isolated prototype or bounded integration has evidence, with adoption or compatibility questions still open.
- Proposed: delivery or an acceptance programme remains to be completed.
An implemented transport can have experimental client compatibility. Record those separately instead of assigning one readiness label to the whole system.
| Capability | State | Evidence and remaining boundary |
|---|---|---|
| OKF 0.2, additive semantic profiles and deterministic projections | Implemented | Semantic contract; producer conformance does not establish source truth or completeness |
| Independent bundles, registries and bounded rich-graph loading | Implemented | Federated architecture; individual source populations and editions require their own coverage evidence |
| Reader search, facets, relationship inspection and shared interaction state | Implemented | Interaction implementation; general learnability and assistive-technology acceptance remain separate |
| Source-bound reading help and passage review | Implemented | Reading help, workbench; explanations retain review status and unresolved references |
| Foundry authoring profiles, facet validation and evaluation fixtures | Implemented | Facet policy and gates, evaluation harness; a valid profile does not prove a producer's actual output or Reader passed |
| Project Studio learning pathway | Implemented documentation | Eight-stage pathway; an integrated guided authoring application is proposed |
| Bounded context assembly and independent A–H controls | Implemented | Engine, evaluation; sufficiency is limited to adequately declared requirements and scope |
| Compact remote MCP delivery, versioned replay and exact reads | Implemented transport | Service; recorded hosting, delivery, model-visible context and Voice compatibility have separate evidence |
| Page tools and host-assisted evidence exploration | Implemented tools; experimental client compatibility | Context interface boundary, workbench routes; registration alone does not prove invocation |
| Portable repository-authoring agent package | Implemented package | Repository guidance review, manifest; this is distinct from a validated consumer evidence workflow |
| Controlled-language rendering | Experimental, isolated research prototype | Findings; three offline illustrative fixtures, no independent model trial or human comprehension study |
| Consumer workflow packaging and current cross-client acceptance matrix | Proposed | P1-C below; retain existing package contracts and reuse the repository package where applicable |
| Independently accepted domain answers and broadly usable authoring workflow | Proposed acceptance work | P1-B and P2 below; current technical checks do not discharge these gates |
| Research BEP schema migration, alternative storage and restricted-data service assurance | Proposed, conditional | BEP status; require a separate decision and evidence before adoption |
The October baseline includes the merged latest-Ubuntu/CPython 3.12.11 repair, dependency updates, reading-help changes and isolated rendering prototype. An Explorer merge does not update a separately hosted MCP service. Use its publication record for dated deployment evidence.
Lessons carried into acceptance
- Retrieve dependencies as well as relevant passages. The retained DWP scenario omitted a controlling provision in its earlier retrieval. The source-guided rendering fixture does not repair that retrieval result. Evaluate source, semantics, retrieval, traversal, assembly, provenance, boundaries and answerability separately using the A–H method.
- Declare the denominator and relationship meaning. GIS and other OKF+ experiments motivate explicit population, jurisdiction, edition, direction, method and cardinality checks. A count of records or links is not coverage; an association does not establish access rights, routing or operational permission. This plan makes no new GIS coverage or entitlement claim.
- Preserve qualifications through explanation. The controlled negative fixture retained citations and had zero language-checker findings while losing conditions. Semantic fidelity and human comprehension need separate assessors. Keep original wording available beside any explanation.
- Observe every delivery boundary. Assembly, response paging, complete reconstruction, model-visible content and actual client use are different checks. SDK success cannot stand in for an observed browser or Voice journey.
- Design for the reader's task. Meaningful facets, exact source help and progressive disclosure require actual-consumer checks and formative user testing. Generic metadata and large graph views cannot establish usefulness.
Priorities and delivery order
The P0 review has completed its source review and implemented six initial corrections, followed by three dependency/toolchain corrections from the post-merge refresh and stable-component check; exact-candidate assurance and publication use required CI and deployment gates. B–F remain proposed. Owner roles below are responsibilities to assign, not named appointments. P1 establishes one dependable domain and client journey. P2 tests reuse and authoring usability. P3 retains bounded research options.
| Item | Priority | Accountable role | Depends on | Completion evidence |
|---|---|---|---|---|
| A. Integration and code review baseline | P0 | Explorer maintainer and independent reviewer | Current frozen implementation | Review coverage map, findings and disposition, targeted verification |
| B. One domain evidence-to-explanation pilot | P1 | Domain producer and independent domain assessor | A; blocking findings resolved | Frozen held-back cases, A–H results, specialist assessment and retained responses |
| C. Consumer workflow and client acceptance | P1 | Integration maintainer | A; B's frozen pilot packages | Reproducible workflow package and per-client observations |
| D. Reader and authoring usability | P2 | Product owner and accessibility reviewer | A; B/C baseline | Formative task results, actual Reader evidence and adopted corrections |
| E. Second-domain portability and scale | P2 | Second producer and Explorer maintainer | B and C | Independent producer, shared-engine results and resource measurements |
| F. Optional model rendering and research decisions | P3 | Research lead and independent assessor | B/C; approved protocol and resources | Comparative trial, failure analysis and explicit adoption/defer decision |
A. Review the whole implementation through its boundaries
Source review completed: see the findings, corrections and limits. The stable component review records the selected stable releases and the separately proposed toolchain and transport maintenance. Those proposals do not extend this P0 implementation. The following scope and gates govern the baseline review. Review the whole first-party implementation in bounded workstreams, then test the interfaces between them. Recent PR reviews and green checks are useful inputs; they do not replace a current integration review. Keep reported coverage and exclusions visible.
Start with a frozen commit and an inventory covering application routes, workers and persistence, context assembly, source loaders, workbench and reading help, page tools, remote MCP, generators, profile validators, evaluation runners, CI and publication. Review vendored dependencies through provenance, lockfiles, advisories and exposure; record exclusions explicitly.
| Workstream | Review questions and required controls |
|---|---|
| Source and semantic contracts | Trace authored inputs to generated assertions; check identity, direction, scope, date roles, rights, schema enforcement and compatibility |
| Fetching, parsing and rendering | Trace untrusted descriptors, URLs, source text, archives and proposals; check path/origin/redirect policy, bounded decompression, digests, safe rendering and inert source instructions |
| Assembly and delivery | Check dependency closure, ambiguity, conflict, truncation, canonical package identity, exact continuations, cancellation and resource ceilings |
| Human and tool interfaces | Compare UI, page-tool and remote-service semantics; check focus/navigation state, source explanations, proposal/export boundaries and actual client visibility |
| Build and publication | Check generated-file authority, dependency routing, reproducibility, permissions, locked environments and promotion of the exact assured candidate |
| Evaluation quality | Check assessor independence, negative controls, fixture representativeness, stale receipts, skipped coverage and gaps hidden by aggregate scores |
Acceptance criteria:
- Every inventoried first-party component has a reviewer, risk level, reviewed revision, linked findings and explicit coverage or exclusion. Include the seams between components, not only individual modules.
- Each finding records severity, trigger, affected invariant, reproduction or supporting evidence, corrective action and an appropriate regression check. Every workstream receives independent review; authors do not solely approve their own fixes.
- All critical and high findings are resolved and verified before broadening the pilot. Other findings have a recorded disposition, owner and target milestone; unresolved scope is visible in the completion report.
- Negative controls cover changed trust boundaries: corrupt or mixed snapshots, unsafe URLs, oversized/expanded inputs, missing dependencies, reversed edges, incomplete continuations and source text containing instructions.
- Equivalent frozen inputs yield the expected package identities across supported surfaces. Compare a remote service only with its declared paired engine; a historical pin is not the current Reader engine by implication.
- The review report separates code/security correctness, domain evidence, accessibility, hosting and client acceptance. Any specialist security review has a stated scope; no blanket certification follows from this review.
Deliver a dated review report and findings register in docs/, with bounded
fixes and their affected-plane checks. Use existing assurance tooling before
adding a new framework. Complete this baseline once, then review subsequent
changes through their dependency impact.
B. Close one domain journey
Use the DWP effective-date research question as a candidate pilot because its failure is retained. The domain owner must approve its scope and assessment protocol before treating it as an answerable case. A narrower independently reviewable question is acceptable if the legal dependency closure remains open.
Acceptance criteria:
- Freeze the source snapshot, question scope, date/jurisdiction roles, rights, engine and independent assessor requirements before the candidate run.
- Predeclare at least ten held-back cases, including answerable, ambiguous, insufficient, conflicting and budget-limited cases. Keep assessor requirements out of retrieval hints; report each case and its limitations.
- For cases expected to be answerable, retain every declared mandatory source, qualification and directed dependency. Insufficient cases stay insufficient. An unresolved controlling source blocks that case's answerability acceptance.
- Bind any observed model response to the exact evidence package, model/version, settings and prompt. An independent specialist assesses every pilot response for support, contradictions, omissions, temporal applicability and uncertainty.
- Accept no critical unsupported claim, lost controlling qualification or false claim of sufficiency. Record all other errors and the rationale for the pilot decision. The small pilot does not establish general domain accuracy.
C. Package and test the consumer workflow
Current OpenAI documentation supports plugins combining skills and MCP, page-scoped Site tools and multi-step Work tasks. These are integration opportunities reviewed on 23 October 2026, not promises of availability in every account, model, browser or execution environment.
Reuse Explorer's existing logic through small adapters. Extend the existing repository-authoring package where appropriate; separately define the consumer workflow for finding evidence, reading it, inspecting gaps and producing a source-linked output. Keep browser page tools, remote MCP and file-based use explicitly distinguishable.
Acceptance criteria:
- A capability preflight records the actual client/version, model where observable, execution location, admitted source, engine, available tools and limits. Unsupported routes receive an explicit result and a usable human path.
- Test the ordinary human browser route, one actual Codex route and one actual ChatGPT route. Name the transport for each. Claim automatic Site-tools support only after a genuine invocation in that exact supported host.
- Preserve source, engine, budget and context identity through catalogue reads, continuations and outputs. Verify complete reconstruction and compare it with the reference package. Instrument clipping where possible; otherwise record model-visible completeness as unverified and restrict the compatibility claim.
- Fail closed on changed identities, malformed input, incomplete mandatory reads and unavailable evidence. Test recovery and cancellation without silent retries or substitution of another source/engine.
- Keep evidence operations read-only. Any proposed correction remains a local preview/export until separately reviewed and adopted by the producer.
- Record latency, bytes, tool calls, retries and available usage observations. Freeze task-specific resource ceilings before testing. Distinguish estimates from billed charges; use included allowance and a zero paid-credit budget unless the owner explicitly approves a different amount and scope.
Voice gets its own later gate: actual microphone recognition, spoken source and uncertainty handling, correction, interruption and end-call behaviour. Typed input with audio output establishes only that tested mode.
D. Make the journey usable and authorable
Acceptance criteria:
- Test a source-to-bundle-to-Reader workflow on actual producer output. Required facets have useful distinctions, explicit missing values and exact single, OR, AND and empty-result membership; validate both emitted data and the Reader.
- A new author can follow the documented pathway, resume a saved checkpoint, inspect a failure and export a correction without editing generated files.
- Run a formative study with at least five representative participants. At least four complete each core discovery/inspection task without intervention; all can locate the source and the stated evidence limitation. Record failures and retest material corrections. This is a formative gate, not population proof.
- Verify keyboard navigation, visible focus, Escape/focus return, zoom and narrow layouts on the affected journey, plus a human assistive-technology review. Report automated accessibility results separately.
E. Demonstrate portability and bounded scale
Acceptance criteria:
- Add one independently authored second-domain pilot, such as an authorised GIS identifier journey. Declare its population, edition, jurisdiction, rights and unresolved coverage before interpreting results.
- Run the shared engine without domain-specific branching. Retain relationship direction, method, cardinality and date roles; do not infer identity, legal access or routing from association alone.
- Exercise small and sharded/indexed inputs, mixed snapshots, absent shards and minimum/maximum supported budgets. Record cancellation, peak memory where observable, bytes and latency against predeclared ceilings.
- Require measured evidence before choosing a storage replacement, new schema or architectural extraction. Prove migration/round-trip preservation and historical replay before changing any accepted identity contract.
F. Retain optional rendering as research
Acceptance criteria:
- Keep the current controlled-language prototype isolated and retain its original evidence. Freeze an independent corpus and questions before any new comparison.
- Give each rendering condition the same complete evidence. Record actual generation, exact inputs/outputs, model/settings and any bounded feedback.
- Independently assess source fidelity and human comprehension. Retain negative controls that lose meaning despite passing language measurements or retaining citation labels. Report insufficient evidence independently of wording quality.
- Adopt a rendering policy only after a documented comparison and review. Formal STE compliance, pre-extraction rewriting, restricted-data processing and BEP schema/storage changes require their own decisions and evidence.
Delivery and maintenance gates
Keep one traceable record for every item: accountable owner, state, dependencies,
candidate/source/engine identities, acceptance results, findings, unrun checks
and next action. Update this inventory and CHANGELOG.md when a capability moves
state. A historical pass cannot approve changed bytes or a new client version.
For each implementation change, use the publication dependency graph to select affected authored sources, generated projections, documentation, tests, browser journeys and release gates. Preserve historical receipts. Promote only the exact candidate that passed required checks; verify deployed identity and the intended journey in a real browser before describing a public experience as verified.
The plan itself is a documentation change: update its entry points and changelog, check generated projections for drift, run documentation/language and Site link checks, and inspect the rendered page. It does not authorise model trials, provider acquisition, private-data transmission or service deployment. Those activities need the item-specific scope, resources and acceptance protocol first.