RDF/SPARQL Implementation Patterns — Phase Plan

Unit type: Plan Identifier: rdf-sparql-patterns-phase Status: Slice 1 complete. ADR-A78/A79/A80 ratified. Slice 2 complete (see validation pack), and since re-synced against the extended vocabulary by the follow-on unit persistence-compiler-iri-sync (in progress). Slice 3 not started. Live state: status record. Blocks: ontology/persistence authoring, tools/persistence compiler, platform/housekeeping first cut, and (once the store SPI exists) the Request Query Mapping and Query Execution work items this plan explicitly excludes. Estimated scope: see Part 2 for a per-slice token estimate. These are planning estimates, not commitments, and are to be checked against actual consumption once each slice completes.

This is a rewrite. It replaces the previous version of this plan in place, at the same path and under the same unit identifier. The previous Slice 2 (“Store-specific adapters and policy”) is removed entirely: store adapter documentation is deferred to a future SPI-focused phase, not part of this plan. Its replacement Slice 2 is the ontology substrate and the compiler toolchain described below, per the commissioning conversation that produced persistence-profile-substrate.md. The previous Slice 3 (“Proposed ADRs and decision record”) is superseded because its ADRs are delivered alongside this rewrite, per the Design First rule in .github/copilot-instructions.md, rather than scheduled as a future slice. Slice 3 is repurposed for the housekeeping first cut.

Purpose: Turn rdf-sparql-patterns-guide.md’s portable patterns into something an adopter of LATTICE can actually select and generate SPARQL from, at whatever granularity their own applied ontology needs, without requiring them to hand-write the guide’s SPARQL or adopt a store SPI that does not yet exist.

Entry criteria:

Success criteria:

Part 0 — Dependencies, ordering, and governance

0.1 Proposed ADRs delivered with this rewrite

Per the Design First rule, a plan of this scope is preceded by a proposed ADR. Three were delivered with this rewrite and have since been ratified (Status: Accepted):

ADR Decision
ADR-A78 ontology/persistence substrate: six independently scopable dimensions, five scope kinds, a fixed precedence algorithm, two boundary mechanisms behind two authoring surfaces
ADR-A79 tools/persistence compiler: design-time only, template-based, injection-safe by construction, explicit exclusion of Request Query Mapping and Query Execution
ADR-A80 platform/housekeeping: contracts and configuration model now, execution engine deferred alongside the SPI

0.2 Hard ordering

No external blockers beyond ADR ratification. Slice 2 must complete before Slice 3 begins, because the housekeeping module’s generated queries are produced by the Slice 2 compiler.

0.3 What this plan does not schedule

Three items depend on the store SPI (proposed A75), which this plan does not build:

  1. The store SPI itself.
  2. A runtime “Request Query Mapping” library binding compiled templates and live requests to an SPI.
  3. A “Query Execution” component rewriting a compiled template’s dialect for a specific backend at request time.

All three are recorded as open design questions in lattice-platform-agentic-development-v0.2.md, Part 13, rows 11 and 12, and Part 6 of that plan carries a note that its ingestion and query-plane slices need revision once this plan’s Slice 2 lands, because several of those slices currently assume ad hoc query construction this plan’s compiler is meant to replace.

Part 1 — Slice breakdown

1.1 Slice 1 — Core patterns and design specs (complete)

Original objective: document each of the five core patterns (K, O, C, T, Q) as a design spec with runnable SPARQL examples.

Status: fulfilled, not by the five fragmented documents originally planned under docs/architecture/design-patterns/, but by the single consolidated rdf-sparql-patterns-guide.md, which covers every sub-pattern (P0–P7, O1–O5, §1.1–1.6, A1–A7, F1–F13, QP1–QP5) with more worked Turtle and SPARQL than the original slice scoped, in one navigable document rather than five. No further work is scheduled against this slice. Its validation, a documentation review rather than a runnable test suite, is recorded in this plan’s status record.

1.2 Slice 2 — Persistence profile substrate and compiler toolchain (✅ complete)

Slice identifier: persistence-substrate-and-compiler

Objective: author ontology/persistence, implement tools/persistence, and deliver the policy enforcement (lint, ArchUnit, injection corpus) that keeps both honest, per ADR-A78 and ADR-A79.

Deliverables:

  1. ontology/persistence (Turtle, literate spec, matching the ontology/mork and ontology/surface layout convention):
  2. tools/persistence (Python package, mise bootstrap:persistence / mise check:persistence, following tools/surface’s pyproject.toml and package layout), two subcommands per sketch §5.2:
  3. Injection corpus and property tests, scoped to instantiate only, since compile never produces SPARQL text (tools/persistence/src/persistence/test_injection.py or equivalent):
  4. Policy enforcement, expanding the original plan’s Slice 2 policy section rather than discarding it:

Doc delta (performed in this slice, per the mandatory slice shape):

Validation pack:

Traceability: docs/traceability/matrix.csv gains rows for ADR-A78, ADR-A79, and every guide chapter listed in sketch Part 8, each linked to the test IDs in tools/persistence’s test suite.

Token estimate (planning only, to be checked against actuals): ontology authoring and shapes, roughly 1.5–2.5M tokens. Compiler implementation including templates and the encoder hierarchy, roughly 4–6M tokens. Injection corpus and determinism tests, roughly 1.5–2.5M tokens. Documentation and doc delta, roughly 1–1.5M tokens. Total order of magnitude 8–12.5M tokens across the slice.

1.3 Slice 3 — Housekeeping first cut

Slice identifier: housekeeping-first-cut

Objective: deliver the contracts, configuration model, and generated queries described in ADR-A80, with no store-calling execution.

Changes since this slice was scoped (2026-09-23). The post-3866b21 review remediation (status) changed what the jobs must do. Read rdf-sparql-patterns-guide.md §24.2 and §24.4 before starting:

Deliverables:

  1. platform/housekeeping Maven module, org.nebularis.lattice.housekeeping, added to platform/pom.xml’s <modules>:

  2. Generated queries, produced by running the Slice 2 compiler’s instantiate stage for each job type, checked into platform/housekeeping/src/main/resources/queries/, never hand-written inline in Java

  3. Documentation:

Doc delta (performed in this slice):

Validation pack:

Traceability: docs/traceability/matrix.csv gains rows for ADR-A80, linked to the guide’s P7/S3/F5 references and to the Slice 2 compiler’s generated-query test IDs for the housekeeping templates specifically.

Token estimate (planning only): Java module scaffolding and contracts, roughly 1–1.5M tokens. Configuration model and its tests, roughly 1M tokens. README and architecture document, roughly 1–1.5M tokens. Total order of magnitude 3–4M tokens.

Part 2 — Execution plan and dependencies

Timeline

Slice Identifier Depends on Estimated tokens
1. Core patterns rdf-sparql-core-patterns — complete (delivered as the guide)
ADRs A78–A80 — Slice 1 (as prior art) complete (delivered with this rewrite)
2. Substrate and compiler persistence-substrate-and-compiler ADR-A78, ADR-A79 ratified ✅ ✅ complete
3. Housekeeping first cut housekeeping-first-cut Slice 2 complete ✅ (ADR-A80 already ratified ✅) 3–4M (not started)

Total remaining scope: order of magnitude 11–16.5M tokens across Slices 2 and 3. These figures are rough planning estimates. Record actual consumption per slice in the status file at completion, so future estimates in this style improve.

Entry and exit criteria

Entry (whole plan):

Exit (whole plan):

Part 3 — Success criteria and validation

Acceptance criteria (5-step gate, per .github/copilot-instructions.md)

Step 1: Review VPs before running. Confirm the injection corpus in Slice 2 actually attempts the failure modes named in sketch §5.3, not a weaker substitute, and that Slice 3’s deliberate UnsupportedOperationException stubs are not mistaken for missing test coverage.

Step 2: Run the single command per slice.

mise check:persistence
mvn -pl platform/housekeeping -am verify

Step 3: Inspect named artifacts. Compiled profile reports and generated SPARQL for every example fixture, the injection-corpus and determinism reports, the housekeeping module’s generated query resources, both new architecture documents.

Step 4: Adversarial probe. Pick one injection-corpus entry and demonstrate the encoder fails open to rejection, not silent pass-through, by temporarily reverting the encoder to naive string interpolation and showing the corpus test catches it. Pick one cross-axis consistency check from sketch §3.5 and demonstrate the compiler accepts the invalid configuration when the check is disabled.

Step 5: Sign-off in docs/developer/validation/LOG.md, naming both slice IDs, and the ADR ratification decision.

Part 4 — Integration with the epic plan

lattice-platform-agentic-development-v0.2.md Part 6 (Phase 2, ingestion and query planes) is marked, in the same edit that accompanies this rewrite, as pending revision once this plan’s Slice 2 lands, because P2.1 (mapping plan compiler), P2.3 (ingestion gateway), and P2.4 (query and decision plane) currently assume SPARQL is constructed ad hoc rather than compiled from a dal: profile. That revision is not scoped here. Part 13 of the same document gains two new open-question rows for the Request Query Mapping and Query Execution items this plan excludes.

Part 5 — Explicitly out of scope

Item Why Recorded
Store SPI (proposed A75) Its shape is undecided, and both excluded items below depend on it not yet an ADR, referenced throughout the guide and this plan as pending
Request Query Mapping library Needs the SPI to inject, would need redoing once the SPI exists lattice-platform-agentic-development-v0.2.md Part 13, row 11
Query Execution component Same dependency, plus a live-request-time SPARQL rewriting concern this plan does not want to solve twice lattice-platform-agentic-development-v0.2.md Part 13, row 12
Store-specific adapter documentation Covered conceptually by the guide’s Chapter 26 already, and concretely blocked on the SPI existing to adapt to removed from this plan per the commissioning instruction, not rescheduled elsewhere yet

Appendix: Reference documents