RDF/SPARQL Implementation Patterns — Status Record

Unit: rdf-sparql-patterns-phase Status: Slices 1 and 2 complete. ADR-A78/A79/A80 ratified. The compiler’s re-sync with the vocabulary extended on 2026-09-23 is complete in persistence-compiler-iri-sync (Slices 1–5 done, human-validated, 774/774 passing; Slice 6 documentation close-out in progress). Slice 3 (housekeeping first cut) not started. Last updated: 2026-09-25 (persistence-compiler-iri-sync re-sync complete) Owner: Agent (autonomous execution authorised by the human; Slice 2 delivered without further pause)

Executive summary

Slice 1 is complete: rdf-sparql-patterns-guide.md consolidates the four source notes into one corrected, cross-referenced reference.

ADR-A78, ADR-A79, and ADR-A80 are ratified (Status: Accepted).

Slice 2 is complete as delivered on 2026-09-22. ontology/persistence is authored (vocabulary, self-validating SHACL shapes, 14 example fixtures, two design-note documents) and tools/persistence is a working Python compiler: 239 tests pass under mise run check:persistence, covering the resolver, validator, capability self-check, boundary-shape walker, an 11-template Mustache library, a 164-case injection corpus, determinism under triple-order permutation, full compile→instantiate→parse round trips, and three Python architecture-policy checks. Doc deltas (root README.md, ontology-architecture.md, mise.toml) are done. Traceability matrix and validation pack are in place.

2026-09-23 update (superseded by the paragraph that follows): ontology/persistence/spec/persistence.ttl and shapes/constraints.ttl were substantially extended by the IRI-patterns remediation (commit c276afb) — three new profile dimensions, extensions to six existing ones, eight new SHACL shapes. None of it is consumed by tools/persistence; the 239 passing tests above exercise only the pre-c276afb vocabulary subset, which is still valid and unmodified, but no longer the complete picture. See persistence-compiler-iri-sync.md for the gap analysis and fix plan.

2026-09-23, current position: the sync unit has closed the epoch-guard correctness gap and the extension-property gap (526 tests), and a second review of the guide (iri-patterns-post-3866b21-remediation, complete) corrected the guide and realigned the templates. The generated SPARQL’s caller contract changed: payload and log-bucket lists are Mustache request-time slots, and every write records a request digest (see tools/persistence/README.md, “Using the generated SPARQL directly”). Identity profiles are resolved per resource role (sync Slice 3); privacy and claim-scheme profiles are still unwired (sync Slices 4–5).

2026-09-25, re-sync complete: persistence-compiler-iri-sync finished Slices 4 and 5 — privacy/erasure profile resolution and checks (Slice 4), and uniqueness dal:onViolation reconciler operations plus dal:ClaimScheme dal:Dual rotation (Slice 5) — both human-validated. The compiler is now fully re-synced against the post-c276afb vocabulary: every profile dimension and SHACL shape that vocabulary added is resolved, checked, and (where it drives generated SPARQL) selected by tools/persistence. 774/774 tests pass under mise run check:persistence. Slice 6 (documentation close-out) is that unit’s own final pass.

Slice 3 (housekeeping first cut) has not been started and remains scoped as written in the plan.

Key findings from building Slice 2, beyond what the sketch anticipated:

• A class alone cannot be the unit of resolution. The sketch’s lending/credit worked example needed an actual implementation decision the sketch’s prose did not spell out mechanically: a Target is a (class, deployment) pair, one per distinct dal:GraphPatternScope a class has (via a new dal:coversClass property, added during implementation), plus one unscoped/fallback target. Documented in tools/persistence/README.md and ontology/persistence/docs/precedence-and-resolution.md.
• Two real SPARQL-validity bugs existed in the design as sketched, both caught only by actually rendering and parsing the templates with rdflib’s own SPARQL parser: (1) SPARQL 1.1 permits a property path only inside WHERE, never inside a DELETE/INSERT template block, and has no bounded {n,m} repetition at all — the sketch’s CompositePropertyBoundary worked SPARQL used both incorrectly. (2) A single SPARQL variable cannot stand in for an entire set of triples (GRAPH ?g { $payload } is not valid SPARQL) — every template needing to accept caller-supplied payload triples now uses a documented, non-SPARQL #PAYLOAD# text marker instead, which whatever eventually executes the template must splice in before submission. (Since 2026-09-23 this is the Mustache request-time slot }.)
• ontology/persistence/spec/persistence.ttl had one property the sketch’s Appendix A never declared (dal:aggregateBoundary, used inconsistently against the actually-declared dal:strategy), found and fixed in both the ontology and the sketch itself during implementation.
• Mustache double-brace tags must never appear inside a `` block, including when the comment is describing Mustache syntax for documentation purposes — chevron’s comment parser ends at the first closing double-brace it finds, silently truncating the comment and corrupting everything after it. Found by the template test suite, not by inspection.
• pyshacl’s conforms flag treats any result, including sh:Warning severity, as non-conformant unless allow_warnings=True is passed — needed for the SharedClassProfileWarningShape design to work as a non-blocking warning at all.

Completed artifacts

Guide: docs/architecture/rdf-sparql-patterns-guide.md

Status: ✅ Complete.

Sketch: docs/developer/sketches/persistence-profile-substrate.md

Status: ✅ Complete, remediated per human review (concurrency renamed for what it provides, the capability model rebuilt as an unconditional-requirement-plus-optional-self-check with no live-backend dependency, the compiler’s canonical output made TTL rather than SPARQL text, and the hand-declared composition-property authoring surface dropped in favour of SHACL only). Governs Slice 2 and Slice 3.

ADRs: A78, A79, A80

Status: ✅ Accepted.

Plan: docs/developer/plans/rdf-sparql-patterns-phase-plan.md

Status: ✅ Complete. Slice 2 executed as scoped; Slice 3 unchanged.

ontology/persistence

tools/persistence

Python package (persistence), pyproject.toml, installable via mise run bootstrap:persistence. Modules: terms (the injection-safety encoder hierarchy), render (the type-enforced Mustache renderer), namespaces, scopes (including the Target model), resolver (the precedence algorithm), boundary (the SHACL closure walker), capability (requirement/spec/check), validator (every cross-axis check, named exception types), operations (template selection), compiler (orchestration and RDF emission), instantiate (the optional SPARQL-rendering stage), cli. 11 Mustache templates. 239 tests across 7 test modules, all passing.

Validation pack: docs/developer/validation/persistence-substrate-and-compiler.md. Traceability: docs/traceability/matrix.csv.

Doc deltas

• docs/architecture/ontology-architecture.md — new §8a (Persistence), plus an Implementation Status table row.
• Root README.md — a new paragraph in “Ontology Layers”, a tree entry, a repository-structure check entry, and a “Validate the persistence compiler” section.
• mise.toml — bootstrap:persistence and check:persistence tasks, wired into the aggregate bootstrap and check tasks.
• .gitignore — *.egg-info/ added (missing before this slice).

Slice status

Open questions

Unchanged from before Slice 2 began. Building the compiler did not resolve any of these; it also did not need to.

New, found during Slice 2 (not previously tracked):

Blocking other work

• lattice-platform-agentic-development-v0.2.md Part 6 is still marked pending revision once this plan’s Slice 2 lands. Slice 2 has now landed. That revision itself remains out of scope for this plan and is not scheduled here.
• Slice 3 (housekeeping) depends on Slice 2’s generated queries, which now exist and are consumable via python -m persistence instantiate.

Traceability

Links to the guide

Links to ADRs

• A78: substrate and boundaries — implemented in ontology/persistence and persistence.{scopes,resolver,boundary}.
• A79: compiler toolchain — implemented in tools/persistence in full (both compile and instantiate subcommands).
• A80: housekeeping boundary — not yet implemented (Slice 3).

Full requirement-to-test mapping

See docs/traceability/matrix.csv.

Next steps

1. Slice 3 (housekeeping first cut), per the plan, including the job changes listed in the plan’s Slice 3 “Changes since this slice was scoped” note: platform/housekeeping Maven module, job contracts, configuration model split, generated queries via persistence instantiate, README, and docs/architecture/platform-housekeeping.md.
2. Resolve or continue deferring the two new open questions found during Slice 2 (items 6 and 7 above) before Slice 3 generates housekeeping job queries against CompositePropertyBoundary targets, if any exist.

Appendix: Validation pack locations

• Slice 2: docs/developer/validation/persistence-substrate-and-compiler.md ✅ complete.
• Slice 3: docs/developer/validation/housekeeping-first-cut.md (to be created at slice start).
• Sign-off log: docs/developer/validation/LOG.md (not yet created; human sign-off per the plan’s Part 3 five-step gate is still pending).