Skip to content

Federation Phase 0: registry producer contract + SPEC §11 - #22

Merged
nicholsn merged 1 commit into
mainfrom
feat/registry-phase0
Jul 10, 2026
Merged

Federation Phase 0: registry producer contract + SPEC §11#22
nicholsn merged 1 commit into
mainfrom
feat/registry-phase0

Conversation

@nicholsn

Copy link
Copy Markdown
Owner

First slice of meta-lokf — a registry that aggregates independent lokf bundles into one cross-repo graph, with no central database. Design context: SPEC §11 (added here).

What ships

Producer contractlokf export now additively writes two artifacts a registry harvests, alongside the existing graph.json + datasets.jsonld:

New artifact Role
graph.nt The whole bundle as N-Triples — the RDF a registry loads for cross-bundle SPARQL.
concepts.jsonld Every concept's frontmatter + body under one @context/@graph — offline access to a concept's source document without re-fetching markdown.

The two are isomorphic (86 triples on the acme example); concepts.jsonld additionally carries raw frontmatter+body. Both are gitignored under web/public/.

SPEC §11 "Federation: registries of bundles" (Versioning → §12) documents the whole design so this groundwork has a north star:

  • the producer contract above;
  • the lokf-registry.yaml DCAT/VoID manifest (one entry per bundle, keyed by base_iri);
  • owner(iri) = longest-base_iri-prefix match — the exact inverse of §7 IRI minting, so cross-bundle resolution is pure string math (no network, no shared DB) — plus its three guards (explicit-id index, namespace precedence/non-nesting, ownership validation);
  • the forthcoming lazy named-graph-per-repo traversal + lokf registry CLI / lokf-registry MCP surface (marked informative);
  • governance: public-artifact/local-checkout membership only in v0.1 (no credentials in the shared manifest), metadata not row-level data with a sensitivity gate, best-effort freshness.

Adds the void: prefix to Appendix B.

Why this slice first

It's independently useful (any bundle can now publish a complete harvestable footprint) and unblocks every later phase, with zero new runtime surface. Later phases (registry manifest + routing, document access, lazy federated store, agent MCP tools) build on it.

Verification

  • lokf export examples/acme-knowledge → all four artifacts; graph.ntconcepts.jsonld (86 triples), both parse cleanly.
  • 135 tests pass (2 new asserting the producer contract + round-trip).
  • Docs site builds; Specification page renders §11 with Versioning correctly renumbered to §12.

Decisions folded in (from discussion)

PHI/governance and PURL operation are owned by @nicholsn; freshness is best-effort; private/perimeter-bound bundles are explicitly a future extension (v0.1 is public-artifact/local only).

Groundwork for meta-lokf, a registry that aggregates independent lokf bundles
into one cross-repo graph without a central database.

`lokf export` now additively writes two artifacts a registry harvests:
- graph.nt      — the whole bundle as N-Triples (the SPARQL harvest source)
- concepts.jsonld — every concept's frontmatter + body under one @context/@graph
                    (offline access to a concept's source document)
alongside the existing graph.json + datasets.jsonld. The two are isomorphic
(86 triples on the acme example); concepts.jsonld additionally carries the raw
frontmatter+body so a consumer can read a foreign concept without refetching
markdown. Both new outputs are gitignored under web/public/.

SPEC gains §11 "Federation: registries of bundles" (Versioning → §12): the
producer contract, the lokf-registry.yaml DCAT/VoID manifest, owner(iri)
longest-base_iri-prefix resolution as the inverse of §7 IRI minting plus its
three guards, the forthcoming lazy named-graph traversal + agent surface, and
governance (public/local-only membership, metadata-not-rows, best-effort
freshness). Adds the void: prefix to Appendix B.

135 tests pass; docs site builds and renders §11.
@nicholsn
nicholsn merged commit 3ce66c4 into main Jul 10, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant