feat: SPARQL conversion layer with SparqlStore base class

.changeset/sparql-conversion-layer.md

@@ -0,0 +1,45 @@
+---
+"@_linked/core": minor
+---
+
+Add SPARQL conversion layer — compiles Linked IR queries into executable SPARQL and maps results back to typed DSL objects.
+
+**New exports from `@_linked/core/sparql`:**
+
+- **`SparqlStore`** — abstract base class for SPARQL-backed stores. Extend it and implement two methods to connect any SPARQL 1.1 endpoint:
+  ```ts
+  import {SparqlStore} from '@_linked/core/sparql';
+
+  class MyStore extends SparqlStore {
+    protected async executeSparqlSelect(sparql: string): Promise<SparqlJsonResults> { /* ... */ }
+    protected async executeSparqlUpdate(sparql: string): Promise<void> { /* ... */ }
+  }
+  ```
+
+- **IR → SPARQL string** convenience functions (full pipeline in one call):
+  - `selectToSparql(query, options?)` — SelectQuery → SPARQL string
+  - `createToSparql(query, options?)` — CreateQuery → SPARQL string
+  - `updateToSparql(query, options?)` — UpdateQuery → SPARQL string
+  - `deleteToSparql(query, options?)` — DeleteQuery → SPARQL string
+
+- **IR → SPARQL algebra** (for stores that want to inspect/optimize the algebra before serialization):
+  - `selectToAlgebra(query, options?)` — returns `SparqlSelectPlan`
+  - `createToAlgebra(query, options?)` — returns `SparqlInsertDataPlan`
+  - `updateToAlgebra(query, options?)` — returns `SparqlDeleteInsertPlan`
+  - `deleteToAlgebra(query, options?)` — returns `SparqlDeleteInsertPlan`
+
+- **Algebra → SPARQL string** serialization:
+  - `selectPlanToSparql(plan, options?)`, `insertDataPlanToSparql(plan, options?)`, `deleteInsertPlanToSparql(plan, options?)`, `deleteWherePlanToSparql(plan, options?)`
+  - `serializeAlgebraNode(node)`, `serializeExpression(expr)`, `serializeTerm(term)`
+
+- **Result mapping** (SPARQL JSON results → typed DSL objects):
+  - `mapSparqlSelectResult(json, query)` — handles flat/nested/aggregated results with XSD type coercion
+  - `mapSparqlCreateResult(uri, query)` — echoes created fields with generated URI
+  - `mapSparqlUpdateResult(query)` — echoes updated fields
+
+- **All algebra types** re-exported: `SparqlTerm`, `SparqlTriple`, `SparqlAlgebraNode`, `SparqlExpression`, `SparqlSelectPlan`, `SparqlInsertDataPlan`, `SparqlDeleteInsertPlan`, `SparqlDeleteWherePlan`, `SparqlPlan`, `SparqlOptions`, etc.
+
+**Bug fixes included:**
+- Fixed `isNodeReference()` in MutationQuery.ts — nested creates with predefined IDs (e.g., `{id: '...', name: 'Bestie'}`) now correctly insert entity data instead of only creating the link.
+
+See [SPARQL Algebra Layer docs](./documentation/sparql-algebra.md) for the full type reference, conversion rules, and store implementation guide.

.gitignore

@@ -2,3 +2,4 @@ node_modules/
 lib/
 .claude/
 .agents/
+OLD

README.md

@@ -6,6 +6,7 @@ Linked core gives you a type-safe, schema-parameterized query language and SHACL
 ## Linked core offers
 
 - **Schema-Parameterized Query DSL**: TypeScript-embedded queries driven by your Shape definitions.
+- **Fully Inferred Result Types**: The TypeScript return type of every query is automatically inferred from the selected paths — no manual type annotations needed. Select `p.name` and get `{id: string; name: string}[]`. Select `p.friends.name` and get nested result types. This works for all operations: select, create, update, and delete.
 - **Shape Classes (SHACL)**: TypeScript classes that generate SHACL shape metadata.
 - **Object-Oriented Data Operations**: Query, create, update, and delete data using the same Shape-based API.
 - **Storage Routing**: `LinkedStorage` routes query objects to your configured store(s) that implement `IQuadStore`.
@@ -31,11 +32,6 @@ npm run setup
 - `.claude/agents`
 - `.agents/agents`
 
-```typescript
-import {Shape, LinkedStorage} from '@_linked/core';
-import {linkedPackage} from '@_linked/core/utils/Package';
-```
-
 ## Related packages
 
 - `@_linked/rdf-mem-store`: in-memory RDF store that implements `IQuadStore`.
@@ -44,6 +40,128 @@ import {linkedPackage} from '@_linked/core/utils/Package';
 ## Documentation
 
 - [Intermediate Representation (IR)](./documentation/intermediate-representation.md)
+- [SPARQL Algebra Layer](./documentation/sparql-algebra.md)
+
+## How Linked works — from shapes to query results
+
+Linked turns TypeScript classes into a type-safe query pipeline. Here is the full flow, traced through a single example:
+
+```
+Shape class → DSL query → IR (AST) → Target query language → Execute → Map results
+```
+
+### 1. SHACL shapes from TypeScript classes
+
+Shape classes use decorators to generate SHACL metadata. These shapes define the data model, drive the DSL's type safety, and can be synced to a store for runtime data validation.
+
+```typescript
+@linkedShape
+export class Person extends Shape {
+  static targetClass = schema('Person');
+
+  @literalProperty({path: schema('name'), maxCount: 1})
+  get name(): string { return ''; }
+
+  @objectProperty({path: schema('knows'), shape: Person})
+  get friends(): ShapeSet<Person> { return null; }
+}
+```
+
+### 2. Type-safe query DSL with inferred result types
+
+The DSL uses these shape classes to provide compile-time checked queries. You cannot write a query that references a property not defined on the shape. The result type is **fully inferred** from the selected paths — no manual type annotations needed:
+
+```typescript
+// TypeScript infers: Promise<{id: string; name: string}[]>
+const result = await Person.select(p => p.name);
+
+// TypeScript infers: Promise<{id: string; friends: {id: string; name: string}[]}[]>
+const nested = await Person.select(p => p.friends.name);
+```
+
+### 3. SHACL-based Intermediate Representation (IR)
+
+The DSL compiles to a backend-agnostic AST — the [Intermediate Representation](./documentation/intermediate-representation.md). This is the contract between the DSL and any store implementation.
+
+```json
+{
+  "kind": "select",
+  "root": { "kind": "shape_scan", "shape": ".../Person", "alias": "a0" },
+  "projection": [
+    { "alias": "a1", "expression": { "kind": "property_expr", "sourceAlias": "a0", "property": ".../name" } }
+  ],
+  "resultMap": [{ "key": ".../name", "alias": "a1" }]
+}
+```
+
+The IR uses full SHACL-derived URIs for shapes and properties. Any store that implements `IQuadStore` receives these IR objects and translates them into its native query language.
+
+### 4. IR → SPARQL Algebra
+
+For SPARQL-backed stores, the IR is converted into a formal [SPARQL algebra](./documentation/sparql-algebra.md) — a tree of typed nodes aligned with the SPARQL 1.1 specification.
+
+```
+SparqlSelectPlan {
+  projection: [?a0, ?a0_name]
+  algebra: LeftJoin(
+    BGP(?a0 rdf:type <Person>),
+    BGP(?a0 <name> ?a0_name)       ← wrapped in OPTIONAL
+  )
+}
+```
+
+Properties are wrapped in `LeftJoin` (OPTIONAL) so missing values don't eliminate result rows.
+
+### 5. SPARQL Algebra → SPARQL string
+
+The algebra is a plain data structure — stores can inspect or optimize it before serialization (e.g., rewriting patterns, adding graph clauses, or pruning redundant joins).
+
+The algebra tree is then serialized into a SPARQL query string with automatic PREFIX generation:
+
+```sparql
+PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
+SELECT DISTINCT ?a0 ?a0_name
+WHERE {
+  ?a0 rdf:type <.../Person> .
+  OPTIONAL {
+    ?a0 <.../name> ?a0_name .
+  }
+}
+```
+
+### 6. Execute and map results
+
+The SPARQL endpoint returns JSON results, which are mapped back into typed result objects:
+
+```
+Endpoint returns:                        Mapped to:
+┌──────────┬──────────┐                  ┌──────────────────────────────┐
+│ a0       │ a0_name  │                  │ { id: ".../p1", name: "Semmy" } │
+│ .../p1   │ "Semmy"  │        →         │ { id: ".../p2", name: "Moa"   } │
+│ .../p2   │ "Moa"    │                  │ ...                          │
+└──────────┴──────────┘                  └──────────────────────────────┘
+```
+
+Values are automatically coerced: `xsd:boolean` → `boolean`, `xsd:integer` → `number`, `xsd:dateTime` → `Date`. Nested traversals are grouped and deduplicated into nested result objects.
+
+### The SparqlStore base class
+
+`SparqlStore` handles this entire pipeline. Concrete stores only implement the transport:
+
+```typescript
+import { SparqlStore } from '@_linked/core/sparql';
+
+class MyStore extends SparqlStore {
+  protected async executeSparqlSelect(sparql: string) {
+    // Send SPARQL to your endpoint, return JSON results
+  }
+  protected async executeSparqlUpdate(sparql: string) {
+    // Send SPARQL UPDATE to your endpoint
+  }
+}
+```
+
+See the [SPARQL Algebra Layer docs](./documentation/sparql-algebra.md) for the full type reference, conversion algorithm, and store implementation guide.
 
 ## Linked Package Setup
 
@@ -478,7 +596,7 @@ All IR types are available from `@_linked/core/queries/IntermediateRepresentatio
 
 **Store packages:**
 
-- `@_linked/sparql-store` — SPARQL endpoint store (coming soon)
+- `SparqlStore` base class — included in `@_linked/core/sparql`, extend it for any SPARQL endpoint
 - `@_linked/rdf-mem-store` — in-memory RDF store
 
 ## Changelog

docs/agents/skills/implementation/SKILL.md

@@ -20,6 +20,16 @@ Run only after explicit user confirmation to enter implementation mode, with an
 7. Continue to next phase without pausing only if there are no deviations and no major problems.
 8. If any deviation/blocker/major risk appears, pause and report.
 
+## Parallel execution
+
+When the plan marks phases as parallelizable, use the Task tool (or any available sub-agent spawning tool) to run them concurrently:
+
+- **Spawn one sub-agent per independent phase** using `run_in_background: true`. Give each agent a self-contained prompt with all context it needs (file paths, types, contracts, test specifications, validation criteria).
+- **Avoid file conflicts**: If two phases write to the same file, combine them into a single agent or sequence them. Different agents should own different files.
+- **Shared files** (barrel exports, test config): Let each agent add its own entries. After all agents complete, verify the shared files have no duplicates or conflicts.
+- **Wait and verify**: After all parallel agents finish, run a full integration check (compile + full test suite) before committing. This catches cross-agent conflicts in shared files.
+- **Single commit for parallel group**: All work from a parallel group goes into one commit after integration verification passes.
+
 ## Required pause report content
 
 - What was done

docs/agents/skills/plan/SKILL.md

@@ -20,6 +20,7 @@ Run only when the user explicitly confirms plan mode (for example: converting id
    - Small code examples
    - Potential pitfalls
    - Remaining unclear areas/decisions
+   - **Inter-component contracts**: When the architecture has separable parts (layers, modules, packages), make the contracts between them explicit — type definitions, function signatures, shared data structures. These contracts enable parallel implementation in tasks mode.
 4. Mention tradeoffs only to explain why chosen paths were selected.
 5. Continuously refine the plan with user feedback until it is explicitly approved for implementation.
 

docs/agents/skills/review/SKILL.md

@@ -35,27 +35,39 @@ After decisions are clear:
   - create separate ideation docs only for very different, large deferred tasks
   - assign the next available 3-digit prefix in `docs/ideas` for each new ideation doc
 
-Then report in chat what was updated and ask the user to review those updates.
+Then report in chat what was updated.
 Do not create a separate review report file in this mode.
 
+## Follow-up questions before switching modes
+
+**After updating the plan with new phases, always ask the user implementation-specific follow-up questions before offering to switch modes.** New phases added during review are often under-specified because they came from gap analysis rather than upfront design. Proactively ask about:
+
+- **Placement decisions**: Where should new files/configs live? (e.g. project root vs subfolder)
+- **Tool/dependency choices**: Which specific library, image, or tool version to use?
+- **Configuration details**: Ports, environment variables, naming conventions
+- **Scope boundaries**: How thorough should tests/error messages be? What's worth the maintenance cost vs what's overkill?
+- **Anything the agent is unsure about** that would affect the implementation
+
+Only offer to switch to tasks mode after these questions are answered. This prevents wasted implementation effort from under-specified phases.
+
 
 ## Guardrails
 
 - Do not perform cleanup/release tasks in this mode; use wrapup mode for that.
 - Do not remove `docs/plans/<nnn>-<topic>.md` in review mode; plan removal happens in wrapup after report approval.
 - If big remaining work is identified, discuss tradeoffs/solutions in chat first.
 - Only convert review findings into new not-yet-completed phases/tasks after the user confirms scope and approach.
-- After adding new tasks, ask the user to review the updated plan and explicitly ask whether to start implementation with the first new phase.
-- For newly uncovered work, do not switch directly from review to implementation; switch to tasks mode first.
+- After adding new phases/tasks, ask the user to review the updated plan and ask whether to switch to tasks mode to refine them.
+- For newly uncovered work, **always switch to tasks mode first** — never directly to implementation. Tasks mode validates that phases have proper validation criteria, dependency graphs, and parallel opportunities before implementation begins.
+- If the user's response to review findings involves clarifying approach or scope (e.g. "do X but not Y", "let's use approach A"), treat this as still in the clarification loop — ask follow-up questions for any remaining ambiguity before switching modes.
 
 ## Exit criteria
 
 - Gaps are clarified with explicit user decisions (now vs future, and chosen approach where needed).
-- If now-work exists, plan was updated with new phases/tasks and user was asked whether to start implementation of the first new phase.
+- If now-work exists, plan was updated with new phases/tasks and user was asked whether to switch to tasks mode.
 - If future-work exists, ideation docs were created according to grouping rules and user was informed.
 - User has explicitly confirmed whether to:
   - stay in review mode,
-  - switch to tasks mode,
-  - switch to implementation mode for approved next phase,
+  - switch to tasks mode (required path for any new implementation work),
   - switch to ideation mode for future work,
-  - or move to wrapup mode.
+  - or move to wrapup mode (only when no new implementation work remains).

docs/agents/skills/tasks/SKILL.md

@@ -12,10 +12,45 @@ Run only when the user explicitly confirms tasks mode.
 ## Steps
 
 1. Update the active plan doc in `docs/plans/<nnn>-<topic>.md`. Task breakdown MUST be persisted in this same on-disk plan file.
-2. Define ordered implementation phases.
+2. Define implementation phases.
 3. Define concrete tasks under each phase.
 4. Add explicit validation criteria per phase (for example: unit tests, integration tests, build/typecheck commands, targeted runtime checks).
-5. Ensure phases are commit-friendly (one commit per phase).
+5. Write detailed test specifications for every phase (see **Test specification** below).
+6. Ensure phases are commit-friendly (one commit per phase).
+
+## Parallel execution
+
+Phases should be designed for maximum parallelism — different agents may implement different phases or tasks concurrently.
+
+- **Identify the dependency graph**: Which phases depend on which? Which can run in parallel? Mark this explicitly in the task breakdown.
+- **Contracts first**: If the plan defines inter-component contracts (types, interfaces, shared data structures), schedule the contract/types phase first. Once contracts are established, phases that only depend on those contracts can run in parallel.
+- **Stub boundaries**: When a phase depends on another phase's output, note what stubs or mocks are needed so it can proceed independently. For example: "Agent B can stub `irToAlgebra()` with hand-crafted algebra objects to test `algebraToString()` independently."
+- **Mark parallel groups**: Use explicit notation in the task breakdown to indicate which phases can run simultaneously. For example: "Phase 2a, 2b, 2c can run in parallel after Phase 1."
+- **Integration phase last**: After all parallel phases complete, include an explicit integration phase that: (1) replaces stubs with real wiring between components, (2) verifies all parts compile and work together, (3) runs end-to-end / golden tests that exercise the full pipeline. This phase must be planned even when stubs seem trivial — it catches type mismatches, import issues, and cross-component edge cases that unit tests miss.
+
+## Validation specification
+
+Every phase must include a **Validation** section that describes the checks an implementing agent must perform and pass before considering the phase complete. Validation is not limited to coded tests — it includes any check that truly proves the work is correct.
+
+**Types of validation checks** (use whichever are appropriate for the phase):
+- **Unit/integration tests**: Coded test files with named test cases and concrete assertions.
+- **Compilation/type-check**: e.g. `npm run compile` passes with no errors.
+- **Runtime checks**: e.g. "execute the generated SPARQL against a running store and verify results".
+- **Manual structural checks**: e.g. "assert the exported function is importable from the barrel", "assert the generated file exists and contains expected content".
+- **HTTP/network checks**: e.g. "POST to the endpoint and verify 200 response with expected payload".
+
+**When describing coded tests:**
+- **Name each test case** with the fixture or scenario it covers (e.g. `` `selectName` — `Person.select(p => p.name)` ``).
+- **State concrete assertions** — not just "test that it works" but what specifically must be true. Use "assert" language: "assert result is array of length 4", "assert field `name` equals `'Semmy'`", "assert plan type is `'select'`".
+- **Include input and expected output** where practical — hand-crafted input objects, specific field values, structural expectations (e.g. "assert algebra contains a LeftJoin wrapping the property triple").
+- **Cover edge cases explicitly** — null handling, missing values, type coercion, empty inputs.
+- **Specify test file paths** — e.g. `src/tests/sparql-algebra.test.ts`.
+
+**When describing non-test validation:**
+- **State the exact command or check** to run and what a passing result looks like.
+- **Be specific about success criteria** — "compiles" is too vague; "`npx tsc --noEmit` exits 0 with no errors" is clear.
+
+The validation specifications serve as the phase's acceptance criteria: a phase is only complete when all described checks pass.
 
 ## Guardrails
 
@@ -24,5 +59,6 @@ Run only when the user explicitly confirms tasks mode.
 ## Exit criteria
 
 - Every phase has tasks and validation criteria.
-- Execution order/dependencies are clear.
+- Dependency graph and parallel opportunities are explicit.
+- Stubs needed for parallel execution are noted.
 - User has explicitly confirmed whether to switch to implementation mode or remain in tasks mode.