@opengroundplan/core 0.1.1

package/templates/architectures/rag-hybrid/files/docs/architecture/rag-hybrid.node.md

@@ -0,0 +1,159 @@
+# RAG with Hybrid Retrieval
+
+**Stack:** `{{ stack }}` · Covers the TypeScript and Node bases — the layout is the same
+whether this repo is Next.js, Hono, Nest, or a plain Node service.
+
+Retrieval-augmented generation where the retriever is a *hybrid*: a dense vector search and a
+BM25 keyword search run over the same chunks, their ranked lists are fused by reciprocal rank
+fusion, and the survivors are reranked before anything reaches the model. This is the
+production default. Naive top-k over a single vector index is the thing this layout exists to
+stop you from shipping.
+
+Each stage is a folder with its own boundary, because each one fails differently and each one
+needs to be swapped without touching its neighbours.
+
+## The one rule that matters
+
+> **Generation may not fetch its own context.**
+
+`src/rag/generate/` imports no retrieval stage. Passages arrive as an argument, already fused
+and reranked, and the type says so: `answer()` accepts `RerankedPassages`, a branded type that
+only `rerank/` mints.
+
+Everything else follows from that one constraint:
+
+- **Provenance is real.** Every passage in a prompt came through `retrieve()`, so every answer
+  can be traced to the chunks that produced it.
+- **Retrieval is measurable.** The eval harness scores what the retriever returns without a
+  model in the loop. A model cannot be allowed to grade its own inputs.
+- **The retriever is replaceable.** Swap the vector store, the reranker, or the fusion
+  strategy and generation does not change, because it never knew.
+
+The moment `generate/` is allowed one direct query — "just this once, for a follow-up" —
+you have an ungoverned second retrieval path that no eval covers and no trace records.
+
+The rule is checked mechanically. It is not a code-review convention.
+
+## Layout
+
+```
+src/rag/
+  config.ts          every tunable, one typed default each — nothing else reads process.env
+  contracts.ts       Document, Chunk, Scored, RetrievalResult, RerankedPassages
+  ingest/            sources -> Document            (connectors live here and nowhere else)
+  chunk/             Document -> Chunk
+  embed/             text -> vectors                (provider resolved by role, never named inline)
+  store/             the two indexes, built together so they cannot drift apart
+  retrieve/          THE SEAM
+    dense.ts         cosine over the vector index
+    keyword.ts       Okapi BM25 over the postings
+    fusion.ts        reciprocal rank fusion
+  rerank/            cuts candidates to what fits the prompt; mints RerankedPassages
+  generate/          prompt + model call. Imports none of the above.
+  indexing.ts        composition root, offline half
+  pipeline.ts        composition root, online half
+  evaluation/        retrieval-quality harness (no generation in its import graph)
+
+evals/
+  corpus/            sample documents so the harness runs on a fresh checkout
+  golden/queries.jsonl
+scripts/check-retrieval-seam.mjs
+```
+
+## Boundary enforcement
+
+| Rule | Enforced by | Fails |
+|---|---|---|
+| Generation imports no retrieval stage | `scripts/check-retrieval-seam.mjs` | `npm run check:retrieval-seam` |
+| Eval harness imports no generation | `scripts/check-retrieval-seam.mjs` | `npm run check:retrieval-seam` |
+| Stages run one way | `scripts/check-retrieval-seam.mjs` | `npm run check:retrieval-seam` |
+| Only `rerank/` mints `RerankedPassages` | the type system, plus a cast check in the script | `tsc`, `npm run check:retrieval-seam` |
+
+The check is a zero-dependency Node script rather than an ESLint rule because the bases
+disagree on linter — ESLint in some, Biome in others — and a boundary rule that only exists in
+one config is a boundary rule half the repo does not have. Wire it into CI next to `lint`.
+
+`RerankedPassages` is a branded type: `readonly Scored[]` intersected with a unique symbol that
+nothing can produce by accident. Passing a plain `Scored[]` to `answer()` is a **compile
+error**, so `tsc` is the first line of defence and the seam script only has to stop someone
+writing the cast themselves.
+
+Paths are configurable — set `RAG_PIPELINE_DIR` if the pipeline does not live at `src/rag`.
+
+## What is *not* enforced mechanically
+
+Say it here rather than pretend:
+
+- **Nothing checks that passages in a prompt are the ones retrieval returned.** The brand
+  stops you handing over unranked candidates; it cannot stop a caller from casting hand-written
+  text into shape. Review prompt construction.
+- **Nothing checks that the golden set is honest.** A golden set written by reading the
+  retriever's output measures agreement, not relevance. Write queries from real user questions,
+  and label them before you look at what comes back.
+- **Nothing checks that a config value is sensible.** `MIN_NDCG` defaults to `0`, which gates
+  nothing. Raise it once you have a baseline you are willing to defend.
+
+## Running it
+
+```bash
+npm run check:retrieval-seam    # boundary check
+npm run eval:retrieval          # retrieval quality
+```
+
+The eval prints one row per retriever variant:
+
+```
+variant           recall@8   ndcg    mrr
+dense-only          ...
+keyword-only        ...
+fused-rrf           ...
+fused-rrf+rerank    ...
+```
+
+The comparison is the point, not the absolute numbers.
+
+**On the shipped sample this table proves nothing about quality**, and it will tell you so.
+The default embedder is a bag-of-words hash, so the `dense-only` row is lexical rather than
+semantic, and four sample documents cannot separate the variants. It is a wiring smoke test.
+
+The comparison becomes real once you point `EMBEDDING_PROVIDER` at a genuine embedding model
+and replace `evals/corpus/` and the golden set with your own. Then `fused-rrf` should beat both
+single-retriever baselines. If it does not on your corpus, the second index is not earning its
+maintenance cost — record that in an ADR and drop it rather than keep it out of habit.
+
+## Configuration
+
+Everything is read once, in `config.ts`, from `{{ envPrefix }}_*` environment variables:
+
+| Setting | Default | Why you would change it |
+|---|---|---|
+| `{{ envPrefix }}_CHUNK_CHARS` | `{{ chunkChars }}` | Bigger chunks dilute the embedding; smaller ones lose context. |
+| `{{ envPrefix }}_CHUNK_OVERLAP_CHARS` | `{{ chunkOverlapChars }}` | Keeps a sentence straddling a boundary retrievable from either side. |
+| `{{ envPrefix }}_CANDIDATE_K` | `{{ candidateK }}` | Candidates *per retriever* before fusion. This sets the recall ceiling. |
+| `{{ envPrefix }}_RRF_K` | `{{ rrfK }}` | Larger flattens the curve and lets deeper results matter. |
+| `{{ envPrefix }}_RERANK_TOP_N` | `{{ rerankTopN }}` | All the model ever sees. More is not better. |
+| `{{ envPrefix }}_EMBEDDING_PROVIDER` | `hash` | `hash` is a deterministic offline stand-in. Use `http` for real. |
+| `{{ envPrefix }}_RERANK_PROVIDER` | `lexical` | `lexical` is a placeholder for a cross-encoder, not a substitute. |
+| `{{ envPrefix }}_GENERATION_PROVIDER` | `echo` | `echo` returns the prompt, so the pipeline runs with no key. |
+
+The three defaults marked as stand-ins exist so a fresh checkout runs end to end without
+credentials. **They are baselines, not implementations.** Point `EMBEDDING_PROVIDER`,
+`RERANK_PROVIDER` and `GENERATION_PROVIDER` at real services — with their endpoint, model and
+key set — before this pipeline is load-bearing.
+
+## The trade-off you accepted
+
+Fusing two retrievers reliably improves recall across query types, but you now own two indexes
+to build, tune, and keep in sync, and the fused score is no longer interpretable as a relevance
+magnitude. Use it to order results. Never threshold on it, and never show it to a user as a
+confidence value.
+
+Rank fusion also breaks features that assume one scored ordering: explicit sorts, scroll, and
+rescoring over vector fields. If you need an explicit sort, you do not want a fused ranking.
+
+## Sources
+
+- Lewis et al., [Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks](https://arxiv.org/abs/2005.11401)
+- Microsoft, [Hybrid search overview](https://learn.microsoft.com/en-us/azure/search/hybrid-search-overview)
+- Microsoft, [Hybrid search ranking (RRF)](https://learn.microsoft.com/en-us/azure/search/hybrid-search-ranking)
+- Elastic, [Reciprocal rank fusion](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/reciprocal-rank-fusion)

package/templates/architectures/rag-hybrid/files/docs/architecture/rag-hybrid.python.md

@@ -0,0 +1,157 @@
+# RAG with Hybrid Retrieval
+
+**Stack:** `{{ stack }}` · **Package:** `{{ solutionName | snake }}`
+
+Retrieval-augmented generation where the retriever is a *hybrid*: a dense vector search and a
+BM25 keyword search run over the same chunks, their ranked lists are fused by reciprocal rank
+fusion, and the survivors are reranked before anything reaches the model. This is the
+production default. Naive top-k over a single vector index is the thing this layout exists to
+stop you from shipping.
+
+Each stage is a package with its own boundary, because each one fails differently and each one
+needs to be swapped without touching its neighbours.
+
+## The one rule that matters
+
+> **Generation may not fetch its own context.**
+
+`{{ solutionName | snake }}.rag.generate` imports no retrieval stage. Passages arrive as an
+argument, already fused and reranked, and the type says so: `answer()` accepts
+`RerankedPassages`, which only `rerank/` constructs.
+
+Everything else follows from that one constraint:
+
+- **Provenance is real.** Every passage in a prompt came through `retrieve()`, so every answer
+  can be traced to the chunks that produced it.
+- **Retrieval is measurable.** The eval harness scores what the retriever returns without a
+  model in the loop. A model cannot be allowed to grade its own inputs.
+- **The retriever is replaceable.** Swap the vector store, the reranker, or the fusion
+  strategy and generation does not change, because it never knew.
+
+The moment `generate/` is allowed one direct query — "just this once, for a follow-up" —
+you have an ungoverned second retrieval path that no eval covers and no trace records.
+
+The rule is checked mechanically. It is not a code-review convention.
+
+## Layout
+
+```
+src/{{ solutionName | snake }}/rag/
+  config.py          every tunable, one typed default each — nothing else reads os.environ
+  contracts.py       Document, Chunk, Scored, RetrievalResult, RerankedPassages
+  ingest/            sources -> Document            (connectors live here and nowhere else)
+  chunk/             Document -> Chunk
+  embed/             text -> vectors                (provider resolved by role, never named inline)
+  store/             the two indexes, built together so they cannot drift apart
+  retrieve/          THE SEAM
+    dense.py         cosine over the vector index
+    keyword.py       Okapi BM25 over the postings
+    fusion.py        reciprocal rank fusion
+  rerank/            cuts candidates to what fits the prompt; mints RerankedPassages
+  generate/          prompt + model call. Imports none of the above.
+  indexing.py        composition root, offline half
+  pipeline.py        composition root, online half
+  evaluation/        retrieval-quality harness (no generation in its import graph)
+
+evals/
+  corpus/            sample documents so the harness runs on a fresh checkout
+  golden/queries.jsonl
+tests/architecture/  the boundary check
+```
+
+## Boundary enforcement
+
+| Rule | Enforced by | Fails |
+|---|---|---|
+| Generation imports no retrieval stage | `.importlinter` contract + AST test | `lint-imports`, `pytest` |
+| Eval harness imports no generation | `.importlinter` contract + AST test | `lint-imports`, `pytest` |
+| Stages run one way | `.importlinter` layers contract + AST test | `lint-imports`, `pytest` |
+| Only `rerank/` mints `RerankedPassages` | AST test | `pytest` |
+
+Both mechanisms check the same rules on purpose. `lint-imports` is more thorough — it follows
+indirect import chains, so `generate -> helper -> retrieve` is caught too — but it only runs if
+someone installed it. The test in `tests/architecture/` uses nothing but the standard library,
+so the boundary survives a repo that has not adopted import-linter yet.
+
+`RerankedPassages` is a `NewType`. That makes it a real gate under mypy or pyright and a
+documented intent without one, which is why the AST test also checks that nothing outside
+`rerank/` constructs it.
+
+## What is *not* enforced mechanically
+
+Say it here rather than pretend:
+
+- **Nothing checks that passages in a prompt are the ones retrieval returned.** The type
+  system stops you handing over unranked candidates; it cannot stop a caller from building a
+  `RerankedPassages` out of hand-written text. Review prompt construction.
+- **Nothing checks that the golden set is honest.** A golden set written by reading the
+  retriever's output measures agreement, not relevance. Write queries from real user
+  questions, and label them before you look at what comes back.
+- **Nothing checks that a config value is sensible.** `MIN_NDCG` defaults to `0`, which gates
+  nothing. Raise it once you have a baseline you are willing to defend.
+
+## Running it
+
+```bash
+lint-imports                                          # boundary contracts
+pytest tests/architecture                             # the same rules, no extra install
+python -m {{ solutionName | snake }}.rag.evaluation.cli   # retrieval quality
+```
+
+The eval prints one row per retriever variant:
+
+```
+variant           recall@8   ndcg    mrr
+dense-only          ...
+keyword-only        ...
+fused-rrf           ...
+fused-rrf+rerank    ...
+```
+
+The comparison is the point, not the absolute numbers.
+
+**On the shipped sample this table proves nothing about quality**, and it will tell you so.
+The default embedder is a bag-of-words hash, so the `dense-only` row is lexical rather than
+semantic, and four sample documents cannot separate the variants. It is a wiring smoke test.
+
+The comparison becomes real once you point `EMBEDDING_PROVIDER` at a genuine embedding model
+and replace `evals/corpus/` and the golden set with your own. Then `fused-rrf` should beat both
+single-retriever baselines. If it does not on your corpus, the second index is not earning its
+maintenance cost — record that in an ADR and drop it rather than keep it out of habit.
+
+## Configuration
+
+Everything is read once, in `config.py`, from `{{ envPrefix }}_*` environment variables:
+
+| Setting | Default | Why you would change it |
+|---|---|---|
+| `{{ envPrefix }}_CHUNK_CHARS` | `{{ chunkChars }}` | Bigger chunks dilute the embedding; smaller ones lose context. |
+| `{{ envPrefix }}_CHUNK_OVERLAP_CHARS` | `{{ chunkOverlapChars }}` | Keeps a sentence straddling a boundary retrievable from either side. |
+| `{{ envPrefix }}_CANDIDATE_K` | `{{ candidateK }}` | Candidates *per retriever* before fusion. This sets the recall ceiling. |
+| `{{ envPrefix }}_RRF_K` | `{{ rrfK }}` | Larger flattens the curve and lets deeper results matter. |
+| `{{ envPrefix }}_RERANK_TOP_N` | `{{ rerankTopN }}` | All the model ever sees. More is not better. |
+| `{{ envPrefix }}_EMBEDDING_PROVIDER` | `hash` | `hash` is a deterministic offline stand-in. Use `http` for real. |
+| `{{ envPrefix }}_RERANK_PROVIDER` | `lexical` | `lexical` is a placeholder for a cross-encoder, not a substitute. |
+| `{{ envPrefix }}_GENERATION_PROVIDER` | `echo` | `echo` returns the prompt, so the pipeline runs with no key. |
+
+The three defaults marked as stand-ins exist so a fresh checkout runs end to end without
+credentials. **They are baselines, not implementations.** Point `EMBEDDING_PROVIDER`,
+`RERANK_PROVIDER` and `GENERATION_PROVIDER` at real services — with their endpoint, model and
+key set — before this pipeline is load-bearing.
+
+## The trade-off you accepted
+
+Fusing two retrievers reliably improves recall across query types, but you now own two indexes
+to build, tune, and keep in sync, and the fused score is no longer interpretable as a relevance
+magnitude. Use it to order results. Never threshold on it, and never show it to a user as a
+confidence value.
+
+Rank fusion also breaks features that assume one scored ordering: explicit sorts, scroll, and
+rescoring over vector fields. If you need an explicit sort, you do not want a fused ranking.
+
+## Sources
+
+- Lewis et al., [Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks](https://arxiv.org/abs/2005.11401)
+- Microsoft, [Hybrid search overview](https://learn.microsoft.com/en-us/azure/search/hybrid-search-overview)
+- Microsoft, [Hybrid search ranking (RRF)](https://learn.microsoft.com/en-us/azure/search/hybrid-search-ranking)
+- Elastic, [Reciprocal rank fusion](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/reciprocal-rank-fusion)

package/templates/architectures/rag-hybrid/files/evals/corpus/chunking.md

@@ -0,0 +1,20 @@
+# Chunking
+
+Chunking splits a document into the units that are actually embedded, indexed, and retrieved.
+It is the highest-leverage knob in a retrieval pipeline and the easiest one to change by
+accident.
+
+Chunks that are too large dilute the embedding: one vector has to represent several topics, so
+it is close to nothing in particular. Chunks that are too small lose the context that makes a
+passage answerable on its own, and they inflate the index.
+
+Overlap between neighbouring chunks keeps a sentence that straddles a boundary retrievable
+from either side. The cost is duplication in the index and near-duplicate hits in the
+candidate set.
+
+Split on structure before falling back to length. Paragraph and heading boundaries usually
+mark a topic change; a fixed character window does not, and cuts mid-sentence.
+
+Pin a golden set to document identifiers rather than chunk identifiers. A golden set keyed on
+chunk ids is invalidated by the very change -- retuning chunk size -- that you most want to
+measure.

package/templates/architectures/rag-hybrid/files/evals/corpus/fusion.md

@@ -0,0 +1,17 @@
+# Reciprocal rank fusion
+
+Reciprocal rank fusion (RRF) merges ranked lists using only the position of each document,
+never its score. For each list, a document at rank r contributes 1 / (k + r), and the
+contributions are summed. Ranks start at 1.
+
+Because it ignores scores, RRF needs no calibration between the retrievers it combines and no
+tuning of relative weights. The relevance indicators do not even have to be related. That is
+what makes it the cheap default for fusing a BM25 list with a vector list.
+
+The ranking constant is written rank_constant in Elasticsearch and defaults to 60. A larger
+constant flattens the curve and lets deeper results influence the merged order; a smaller one
+concentrates weight at the top of each list.
+
+The trade-off is interpretability. A fused score is a sum of reciprocal ranks, so it carries
+no meaning as a relevance magnitude. Use it to order results. Never threshold on it, and never
+show it to a user as a confidence value.

package/templates/architectures/rag-hybrid/files/evals/corpus/hybrid-retrieval.md

@@ -0,0 +1,21 @@
+# Hybrid retrieval
+
+Hybrid retrieval runs a keyword search and a vector search over the same corpus and merges
+the two result sets before anything is passed to a model.
+
+The two retrievers fail differently, which is the entire reason to pay for both. Vector search
+finds conceptually similar content even when the query and the document share no vocabulary:
+a question about cancelling an order matches a passage about refund policy. Keyword search
+(BM25) supplies precision on exact tokens that an embedding model tends to smear together --
+product codes, part numbers, error codes, specialised jargon, dates, and people's names.
+
+Recall is the ceiling on everything downstream. A document that neither retriever returns
+cannot be recovered by fusion, by reranking, or by a larger context window. Widen the
+candidate set first; tighten it afterwards.
+
+The cost is two indexes to build, tune, and keep in sync, and a query that fans out to both.
+Rank fusion also breaks features that depend on a single scored ordering, such as explicit
+sorts, scroll, and rescoring.
+
+This sample corpus exists so the eval harness runs end to end on a fresh checkout. Replace it
+with your own documents.

package/templates/architectures/rag-hybrid/files/evals/corpus/reranking.md

@@ -0,0 +1,17 @@
+# Reranking
+
+Reranking is the last gate before a model sees anything. Retrieval and fusion optimise for
+recall over a wide candidate set; the reranker scores each surviving candidate against the
+query directly and cuts the list to the handful that fit in a prompt.
+
+A cross-encoder reads the query and the passage together, so it can judge relevance in a way
+that comparing two independently produced vectors cannot. It is far too slow to run over a
+whole corpus, which is why it runs over candidates rather than replacing retrieval.
+
+A reranker cannot rescue a candidate set that never contained the answer. It reorders what it
+is given and nothing more. When answer quality is poor, measure recall before tuning the
+reranker.
+
+Cutting to a small number of passages is a quality decision, not only a cost one. Irrelevant
+passages in a prompt actively degrade the answer, and a model given twenty mediocre passages
+usually does worse than the same model given five good ones.

package/templates/architectures/rag-hybrid/files/evals/golden/queries.jsonl

@@ -0,0 +1,5 @@
+{"id": "q-exact-token", "query": "rank_constant 60", "relevantDocumentIds": ["fusion.md"]}
+{"id": "q-paraphrase", "query": "how do I stop the model from seeing irrelevant passages", "relevantDocumentIds": ["reranking.md"]}
+{"id": "q-mixed", "query": "BM25 keyword search for product codes", "relevantDocumentIds": ["hybrid-retrieval.md", "fusion.md"]}
+{"id": "q-splitting", "query": "how big should a chunk be and how much should it overlap", "relevantDocumentIds": ["chunking.md"]}
+{"id": "q-recall-ceiling", "query": "why can a reranker not fix a bad candidate set", "relevantDocumentIds": ["reranking.md", "hybrid-retrieval.md"]}

package/templates/architectures/rag-hybrid/files/package.json

@@ -0,0 +1,9 @@
+{
+  "scripts": {
+    "check:retrieval-seam": "node scripts/check-retrieval-seam.mjs",
+    "eval:retrieval": "tsx src/rag/evaluation/cli.ts"
+  },
+  "devDependencies": {
+    "tsx": "^4.23.1"
+  }
+}

package/templates/architectures/rag-hybrid/files/pyproject.toml

@@ -0,0 +1,2 @@
+[dependency-groups]
+dev = ["import-linter==2.13"]

package/templates/architectures/rag-hybrid/files/scripts/check-retrieval-seam.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// Fails when generation reaches past the retrieval seam, when the eval harness imports
+// generation, or when a stage imports a later stage.
+// Zero dependencies on purpose: the bases disagree on linter (ESLint vs Biome), so this check
+// has to work without editing whichever config the base already owns.
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+/** The only place these paths are written. Environment overrides them per repo. */
+const defaults = {
+  pipelineDir: 'src/rag',
+  extensions: '.ts,.tsx,.mts,.cts,.js,.jsx,.mjs,.cjs',
+};
+
+// Same prefix the pipeline's config module reads, so one knob moves the whole surface.
+const PREFIX = '{{ envPrefix }}_';
+
+const pipelineDir = toPosix(process.env[PREFIX + 'PIPELINE_DIR'] || defaults.pipelineDir);
+const extensions = new Set((process.env[PREFIX + 'EXTENSIONS'] || defaults.extensions).split(','));
+
+/** The last segment of the pipeline root, as it appears in alias imports like `@/rag/embed`. */
+const pipelineSegment = pipelineDir.split('/').filter(Boolean).at(-1);
+
+// The pipeline runs one way. Position is the rule.
+const STAGES = ['ingest', 'chunk', 'embed', 'store', 'retrieve', 'rerank'];
+const ORDER = new Map(STAGES.map((name, at) => [name, at]));
+const AFTER_SEAM = new Set([...STAGES, 'indexing', 'pipeline', 'evaluation']);
+
+const SPECIFIER_PATTERNS = [
+  /\bfrom\s*['"]([^'"]+)['"]/g,
+  /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  /\bimport\s+['"]([^'"]+)['"]/g,
+];
+
+function toPosix(value) {
+  return value.split(path.sep).join('/');
+}
+
+async function listFiles(dir) {
+  const found = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return found;
+  }
+
+  for (const entry of entries) {
+    const child = `${dir}/${entry.name}`;
+    if (entry.isDirectory()) found.push(...(await listFiles(child)));
+    else if (extensions.has(path.extname(entry.name))) found.push(child);
+  }
+  return found;
+}
+
+function specifiersIn(source) {
+  const found = new Set();
+  for (const pattern of SPECIFIER_PATTERNS) {
+    for (const match of source.matchAll(pattern)) found.add(match[1]);
+  }
+  return found;
+}
+
+/** The pipeline module a repo-root-relative path belongs to, or null when outside the root. */
+function moduleOfPath(posixPath) {
+  const prefix = `${pipelineDir}/`;
+  if (!posixPath.startsWith(prefix)) return null;
+  const rest = posixPath.slice(prefix.length).split('/');
+  // A file directly under the root is its own module: `pipeline.ts` -> `pipeline`.
+  return rest.length === 1 ? rest[0].replace(/\.\w+$/, '') : rest[0];
+}
+
+/** Alias and package specifiers carry no repo path, so match on the `<root>/<module>` segment. */
+function moduleOfSpecifier(specifier) {
+  const parts = toPosix(specifier).split('/');
+  const at = parts.lastIndexOf(pipelineSegment);
+  if (at < 0 || at >= parts.length - 1) return null;
+  const rest = parts.slice(at + 1);
+  return rest.length === 1 ? rest[0].replace(/\.\w+$/, '') : rest[0];
+}
+
+function targetModule(specifier, fromFile) {
+  if (!specifier.startsWith('.')) return moduleOfSpecifier(specifier);
+  const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), specifier));
+  return moduleOfPath(resolved);
+}
+
+async function findViolations() {
+  const violations = [];
+
+  for (const file of await listFiles(pipelineDir)) {
+    const owner = moduleOfPath(file);
+    if (owner === null) continue;
+
+    const source = await readFile(file, 'utf8');
+
+    // The seam only holds if the model cannot fetch its own context.
+    if (owner === 'generate' && !file.endsWith('.d.ts')) {
+      for (const specifier of specifiersIn(source)) {
+        const target = targetModule(specifier, file);
+        if (target !== null && AFTER_SEAM.has(target)) {
+          violations.push(
+            `${file}: generate imports "${target}" via "${specifier}" — generation must not ` +
+              `reach past the retrieval seam. Take passages as an argument instead.`,
+          );
+        }
+      }
+    }
+
+    // A retrieval metric that can call a model is measuring the wrong thing.
+    if (owner === 'evaluation') {
+      for (const specifier of specifiersIn(source)) {
+        if (targetModule(specifier, file) === 'generate') {
+          violations.push(
+            `${file}: the eval harness imports generate via "${specifier}" — retrieval quality ` +
+              `must be measurable without a language model in the loop.`,
+          );
+        }
+      }
+    }
+
+    if (ORDER.has(owner)) {
+      for (const specifier of specifiersIn(source)) {
+        const target = targetModule(specifier, file);
+        if (target === null || target === owner || !ORDER.has(target)) continue;
+        if (ORDER.get(target) > ORDER.get(owner)) {
+          violations.push(
+            `${file}: stage "${owner}" imports later stage "${target}" via "${specifier}" — ` +
+              `the pipeline runs ${STAGES.join(' -> ')}.`,
+          );
+        }
+      }
+    }
+
+    // RerankedPassages is the token that says "a reranker has seen these". Minting it
+    // elsewhere would let unranked candidates reach the model with the right type.
+    if (owner !== 'rerank' && owner !== 'contracts' && / as\s+RerankedPassages\b/.test(source)) {
+      violations.push(
+        `${file}: casts to RerankedPassages — only ${pipelineDir}/rerank may mint that type.`,
+      );
+    }
+  }
+
+  return violations;
+}
+
+const violations = await findViolations();
+if (violations.length > 0) {
+  console.error(`Retrieval seam violations (${violations.length}):`);
+  for (const violation of violations) console.error(`  ${violation}`);
+  process.exit(1);
+}
+
+console.log(`Retrieval seam holds: nothing in ${pipelineDir}/generate reaches past it.`);

package/templates/architectures/rag-hybrid/files/src/__solutionName.snake__/rag/__init__.py

@@ -0,0 +1,23 @@
+"""Hybrid-retrieval RAG pipeline for {{ solutionName | title }}.
+
+Stages are separate packages and run in one direction:
+ingest -> chunk -> embed -> store -> retrieve -> rerank -> generate.
+
+`generate` is the only stage that talks to a language model, and it imports none of the
+others: passages arrive as an argument. See docs/architecture/rag-hybrid.python.md.
+"""
+
+from .contracts import Chunk, Document, RerankedPassages, RetrievalResult, Scored
+from .indexing import build_index
+from .pipeline import answer_question, retrieve_passages
+
+__all__ = [
+    "Chunk",
+    "Document",
+    "RerankedPassages",
+    "RetrievalResult",
+    "Scored",
+    "answer_question",
+    "build_index",
+    "retrieve_passages",
+]

package/templates/architectures/rag-hybrid/files/src/__solutionName.snake__/rag/chunk/__init__.py

@@ -0,0 +1,57 @@
+"""Stage 2 — Documents become Chunks.
+
+Chunking is the highest-leverage retrieval knob and the easiest to change by accident, which
+is why it is its own stage with its own eval run rather than a helper inside ingest.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from ..config import Settings
+from ..contracts import Chunk, Document
+
+_PARAGRAPH = "\n\n"
+
+
+def _windows(text: str, size: int, overlap: int) -> list[str]:
+    """Paragraph-aligned windows, falling back to a hard cut for a single oversized block."""
+    step = max(1, size - overlap)
+    blocks = [block.strip() for block in text.split(_PARAGRAPH) if block.strip()]
+
+    out: list[str] = []
+    buffer = ""
+    for block in blocks:
+        if len(block) > size:
+            if buffer:
+                out.append(buffer)
+                buffer = ""
+            out.extend(block[at : at + size] for at in range(0, len(block), step))
+            continue
+        candidate = f"{buffer}{_PARAGRAPH}{block}" if buffer else block
+        if len(candidate) > size:
+            out.append(buffer)
+            buffer = block
+        else:
+            buffer = candidate
+    if buffer:
+        out.append(buffer)
+    return out
+
+
+def chunk_documents(documents: Iterable[Document], settings: Settings) -> list[Chunk]:
+    chunks: list[Chunk] = []
+    for document in documents:
+        for ordinal, text in enumerate(
+            _windows(document.text, settings.chunk_chars, settings.chunk_overlap_chars)
+        ):
+            chunks.append(
+                Chunk(
+                    id=f"{document.id}#{ordinal}",
+                    document_id=document.id,
+                    ordinal=ordinal,
+                    text=text,
+                    source=document.source,
+                )
+            )
+    return chunks