@lde/search 0.8.0 → 0.9.0

package/README.md

@@ -29,11 +29,11 @@ It provides four things:
   out of it, so the two cannot drift;
 - **engine port** – `SearchEngine` and the logical result types
   (`SearchResult` / `SearchHit` / `ResultDocument` / `Reference` / …);
-- **streaming projection** – `projectGraph`, RDF `CONSTRUCT` quads → flat
-  search documents.
+- **streaming projection** – `projectRoots`, RDF `CONSTRUCT` quads → flat
+  search documents, one root type at a time.
 
 ```
-SearchSchema ─┬─► projection      (projectGraph → flat documents)        [here]
+SearchSchema ─┬─► projection      (projectRoots → flat documents)        [here]
               ├─► engine adapter  (collection definition + query compiler)   e.g. @lde/search-typesense
               ├─► query semantics (SearchQuery, filter/sort/facet)       [here]
               └─► API surface     (GraphQL / REST)                       e.g. @lde/search-api-graphql
@@ -58,7 +58,7 @@ a typed, deterministic function – easy to test, and swappable per deployment.
 Exports are stratified by audience:
 
 - **`@lde/search`** – the authoring surface: `defineSearchType`,
-  `searchSchema`, `projectGraph` (+ the IR readers `derive` functions use),
+  `searchSchema`, `projectRoots` (+ the IR readers `derive` functions use),
   validation, and every model/query/result type.
 - **`@lde/search/adapter`** – plumbing for engine adapters and API surfaces:
   `physicalFields`, the field selectors, `assertValidQuery`, the filter
@@ -78,8 +78,9 @@ and GraphQL (one of the surfaces):
 | `SearchType`   | One root type’s complete declaration: its logical API `name`, its `class` IRI and its fields (incl. derived)     | NodeShape      | object type |
 | `SearchSchema` | The whole search declaration: every `SearchType`, keyed by `class` IRI – build one with `searchSchema(...types)` | shapes graph   | schema      |
 
-`projectGraph` and the GraphQL surface consume a `SearchSchema` (projecting
-every type in one pass); the engine port executes one `SearchType` at a time.
+`projectRoots` and the engine port each execute one `SearchType` at a time –
+projection over the roots the pipeline selector supplied for that type; the
+GraphQL surface consumes the whole `SearchSchema`.
 
 ### API conventions
 
@@ -110,7 +111,7 @@ query compiler all share.
 ```ts
 import {
   defineSearchType,
-  projectGraph,
+  projectRoots,
   irisOf,
   searchSchema,
 } from '@lde/search';
@@ -150,14 +151,12 @@ const DATASET = defineSearchType({
   ],
 });
 
-for await (const { searchType, document } of projectGraph(
-  quads,
-  searchSchema(DATASET),
-)) {
-  // one flat search document per matching subject, streamed and tagged with the
-  // SearchType it was framed from — so a multi-collection writer can route each
-  // document to the collection for its type. A single-collection consumer just
-  // reads `document`.
+const schema = searchSchema(DATASET);
+for await (const document of projectRoots(quads, roots, schema, DATASET)) {
+  // one flat search document per given root subject, streamed. The caller (the
+  // pipeline selector) supplies `roots`; pairing a document with its type for a
+  // multi-collection writer is the pipeline glue’s job (see
+  // `@lde/search-pipeline`), not the projection’s.
 }
 ```
 
@@ -219,31 +218,38 @@ source fails at startup. A reference without a `labelSource` stays id-only.
 
 ## Projection
 
-`projectGraph` is fully streaming: subjects are grouped and framed one at a time
-and documents are yielded as produced, so beyond a subject index memory stays
-flat at scale (framing the whole graph at once is roughly O(N²)). Duplicate
-triples are collapsed first, because some SPARQL engines (e.g. QLever) do not
-deduplicate `CONSTRUCT` output. The IR carries no `@context`, so a `derive` function
-reading it sees full predicate IRIs with language tags preserved.
-
-Each yielded value is a `{ searchType, document }` pair: the whole schema
-projects into **one** mixed stream, and every document is tagged with the
-`SearchType` it was framed from. That tag is what lets the write side fan the
-stream out to per-type collections without re-deriving the type from the
-document – see `@lde/search-pipeline`’s multi-collection writer.
-
-`projectGraph` **consumes the quads once** – a single scan builds the subject
-index every type frames off – and so accepts any `Iterable<Quad>`, not just a
-materialized array. A caller merging several sources can pass a chained
+`projectRoots` projects **one root type** over the roots the caller supplies –
+the pipeline selector already holds them, so nothing is discovered from
+`rdf:type` and a `CONSTRUCT` need emit no type triple. It is fully streaming:
+each root’s subgraph is framed one at a time and its document yielded as
+produced, so beyond a subject index memory stays flat at scale (framing the
+whole graph at once is roughly O(N²)). Duplicate triples are collapsed first,
+because some SPARQL engines (e.g. QLever) do not deduplicate `CONSTRUCT` output.
+The IR carries no `@context`, so a `derive` function reading it sees full
+predicate IRIs with language tags preserved. `assertTypeInSchema` guards that
+the passed `SearchType` is a member of the schema – the port’s own membership
+check – so no schema is ever forged to scope a projection to one type.
+
+`projectRoots` yields a **bare** `SearchDocument`. Pairing each document with the
+`SearchType` it belongs to, so the write side can fan a mixed stream out to
+per-type collections, is a routing concern owned by the pipeline glue – see
+`@lde/search-pipeline`’s `searchStages` and multi-collection writer – not the
+projection. One stage per root type keeps `@lde/search` pipeline-free.
+
+`projectRoots` **consumes the quads once** – a single scan builds the subject
+index the roots frame off – and so accepts any `Iterable<Quad>`, not just a
+materialized array. A caller merging several readers can pass a chained
 generator instead of building a third full array at the projection peak:
 
 ```ts
-projectGraph(
+projectRoots(
   (function* () {
     yield* registerQuads;
     yield* dkgQuads;
   })(),
+  roots,
   schema,
+  DATASET,
 );
 ```
 
@@ -307,7 +313,7 @@ unrepresentable; the port enforces them for everyone else (deployment
 ## Typed results
 
 An engine is **bound to the whole `SearchSchema` at construction** – like
-every other schema consumer (`projectGraph(quads, schema)`,
+every other schema consumer (`projectRoots(quads, roots, schema, type)`,
 `buildGraphQLSchema(schema)`): the adapter factory takes the deployment’s
 declaration, so a query can never meet the wrong index, and deployment-level
 concerns (the label cache, cross-type search, facet batching) have one home.

package/dist/engine.d.ts

@@ -3,10 +3,10 @@ import type { SearchSchema, SearchType } from './schema.js';
 /**
  * The engine port: the boundary a concrete engine adapter (e.g. the engine
  * `@lde/search-typesense`’s `createTypesenseSearchEngine` returns) implements.
- * An engine is **bound to the whole {@link SearchSchema} at construction** —
+ * An engine is **bound to the whole {@link SearchSchema} at construction** –
  * the adapter factory takes the deployment’s declaration together with the
  * physical location of every type (its collections map), mirroring the other
- * schema consumers (`projectGraph(quads, schema)`,
+ * schema consumers (`projectRoots(quads, roots, schema, type)`,
  * `buildGraphQLSchema(schema)`): everything is a function of the schema. A
  * query can never meet the wrong index, deployment-level concerns (label
  * cache, cross-type search, facet batching) have one home, and a search names
@@ -19,8 +19,8 @@ import type { SearchSchema, SearchType } from './schema.js';
  *
  * Port contract: an adapter ALWAYS rejects a `searchType` that is not in its
  * bound schema, and ALWAYS validates the incoming query against it
- * (`assertValidQuery`) — unknown or non-filterable fields, mismatched
- * operators, unknown facets — rather than passing garbage to its engine.
+ * (`assertValidQuery`) – unknown or non-filterable fields, mismatched
+ * operators, unknown facets – rather than passing garbage to its engine.
  * Validation is not the caller’s job: it must hold for every surface and for
  * injected deployment policy.
  *
@@ -31,7 +31,7 @@ import type { SearchSchema, SearchType } from './schema.js';
  * gracefully to string keys ({@link FacetFieldsOf}).
  */
 export interface SearchEngine<Types extends readonly SearchType[] = readonly SearchType[]> {
-    /** The declaration this engine serves — exposed so a surface can route and
+    /** The declaration this engine serves – exposed so a surface can route and
      *  a caller can enumerate the searchable types. */
     readonly schema: SearchSchema<Types>;
     search<T extends Types[number]>(searchType: T, query: SearchQuery): Promise<SearchResult<FacetFieldsOf<T>, OutputFieldsOf<T>>>;
@@ -78,7 +78,7 @@ export interface SearchResult<FacetField extends string = string, OutputField ex
  */
 export type FacetMap<FacetField extends string = string> = Readonly<Partial<Record<FacetField, readonly FacetBucket[]>>>;
 /**
- * The facet-field-name union of a search type — the keys a {@link SearchResult}’s
+ * The facet-field-name union of a search type – the keys a {@link SearchResult}’s
  * `facets` can hold. Narrow for a declaration captured as a literal (via
  * `defineSearchType` or `as const satisfies SearchType`); a plain
  * `: SearchType` annotation degrades to `string` (its field names are not
@@ -88,7 +88,7 @@ export type FacetFieldsOf<Type extends SearchType> = SearchType extends Type ? s
     readonly facetable: true;
 }>['name'];
 /**
- * The output-field-name union of a search type — the keys a {@link ResultDocument}
+ * The output-field-name union of a search type – the keys a {@link ResultDocument}
  * can hold. Like {@link FacetFieldsOf}, degrades to `string` for a widened
  * declaration.
  */
@@ -98,7 +98,7 @@ export type OutputFieldsOf<Type extends SearchType> = SearchType extends Type ?
 /**
  * One result row. `id` (the stable document key, an IRI) is kept *out* of
  * {@link ResultDocument}: it is always present and is the hit’s identity, a
- * different contract from the optional, typed logical field values — and it maps
+ * different contract from the optional, typed logical field values – and it maps
  * straight onto the GraphQL output’s guaranteed `id: String!`. The document
  * holds only the selectable fields.
  */
@@ -107,7 +107,7 @@ export interface SearchHit<OutputField extends string = string> {
     readonly document: ResultDocument<OutputField>;
 }
 /**
- * The logical result document at the query seam — engine- and RDF-neutral.
+ * The logical result document at the query seam – engine- and RDF-neutral.
  * Distinct from the flat, fanned-out projection `SearchDocument` that lives
  * index-side: this carries logical fields with language maps and references,
  * ready for a surface to shape. Keyed by output field name; `Partial` because a

package/dist/frame-by-type.d.ts

@@ -2,45 +2,40 @@ import type { Quad } from '@rdfjs/types';
 /** A framed JSON-LD node (full-IRI keys); the engine-agnostic search IR. */
 export type FramedNode = Record<string, unknown>;
 /**
- * A one-pass index of a quad source: every subject’s (deduplicated) triples,
- * plus the root subjects of each requested type in appearance order. Built by
- * {@link buildSubjectIndex} from a single iteration of the source, so a caller
- * can pass a chained generator (`function* () { yield* a; yield* b; }`) rather
- * than materialize a merged array; a multi-type projection then frames every
- * type off this one index instead of re-scanning per type.
+ * A one-pass index of a quad source: every subject’s (deduplicated) triples.
+ * Built by {@link buildSubjectIndex} from a single iteration of the source, so a
+ * caller can pass a chained generator (`function* () { yield* a; yield* b; }`)
+ * rather than materialize a merged array, then frame any of its subjects off
+ * this one index.
  */
 export interface SubjectIndex {
     /** Each subject IRI → its own deduplicated triples, in first-seen order. */
     readonly bySubject: ReadonlyMap<string, readonly Quad[]>;
-    /** Each requested root type IRI → its root subjects, in appearance order. */
-    readonly rootsByType: ReadonlyMap<string, readonly string[]>;
 }
 /**
- * Iterate `quads` once, grouping each subject’s triples and collecting the root
- * subjects of every type in `rootTypes`. Duplicate triples are collapsed here
- * because some SPARQL engines (e.g. QLever) do not deduplicate CONSTRUCT
- * output. The source is consumed a single time, so it may be a one-shot
- * iterable (a generator chaining several sources); the whole subject index is
- * held, but never more than that plus one framed subgraph at a time
+ * Iterate `quads` once, grouping each subject’s triples. Duplicate triples are
+ * collapsed here because some SPARQL engines (e.g. QLever) do not deduplicate
+ * CONSTRUCT output. The source is consumed a single time, so it may be a
+ * one-shot iterable (a generator chaining several sources); the whole subject
+ * index is held, but never more than that plus one framed subgraph at a time
  * downstream.
+ *
+ * Roots are never discovered here – the caller ({@link projectRoots}, from the
+ * pipeline selector) already holds them and passes them to {@link frameSubjects}
+ * – so `quads` need carry no `rdf:type` triple.
  */
-export declare function buildSubjectIndex(quads: Iterable<Quad>, rootTypes: Iterable<string>): SubjectIndex;
+export declare function buildSubjectIndex(quads: Iterable<Quad>): SubjectIndex;
 /**
- * Frame every root subject of `rootType` from a prebuilt {@link SubjectIndex}
- * into one JSON-LD node – the reusable core behind {@link frameByType}. Each
- * root subject’s own triples plus the one-hop nodes it references (e.g. nested
- * publisher/distribution resources) are framed one subject at a time, so beyond
- * the shared subject index only a single subgraph is held (whole-graph
- * `jsonld.frame()` is ~O(N²)). The frame carries no `@context`, so framed keys
- * are full predicate IRIs.
+ * Frame each of the given `roots` from a prebuilt {@link SubjectIndex} into one
+ * JSON-LD node. Each root subject’s own triples plus the one-hop nodes it
+ * references (e.g. nested publisher/distribution resources) are framed one
+ * subject at a time, so beyond the shared subject index only a single subgraph
+ * is held (whole-graph `jsonld.frame()` is ~O(N²)). The frame carries no
+ * `@context`, so framed keys are full predicate IRIs.
+ *
+ * The roots are supplied explicitly rather than discovered from `rdf:type`: the
+ * caller ({@link projectRoots}, from the pipeline selector) already holds them
+ * and passes them directly. A root absent from the index simply frames nothing.
  */
-export declare function frameSubjects(index: SubjectIndex, rootType: string): AsyncIterable<FramedNode>;
-/**
- * Frame CONSTRUCT quads into one JSON-LD node per subject of `rootType`, for a
- * single root type. Consumes `quads` once (see {@link buildSubjectIndex}), so
- * it accepts any `Iterable` – a materialized array or a chained generator. For
- * a multi-type schema, {@link buildSubjectIndex} + {@link frameSubjects} share
- * one index across types rather than re-scanning per type.
- */
-export declare function frameByType(quads: Iterable<Quad>, rootType: string): AsyncIterable<FramedNode>;
+export declare function frameSubjects(index: SubjectIndex, roots: readonly string[]): AsyncIterable<FramedNode>;
 //# sourceMappingURL=frame-by-type.d.ts.map

package/dist/frame-by-type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frame-by-type.d.ts","sourceRoot":"","sources":["../src/frame-by-type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAMzC,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAIjD;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,CAAC,CAAC;IACzD,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;CAC9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,EACrB,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,GAC1B,YAAY,CA8Bd;AAED;;;;;;;;GAQG;AACH,wBAAuB,aAAa,CAClC,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,MAAM,GACf,aAAa,CAAC,UAAU,CAAC,CA+B3B;AAED;;;;;;GAMG;AACH,wBAAuB,WAAW,CAChC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,EACrB,QAAQ,EAAE,MAAM,GACf,aAAa,CAAC,UAAU,CAAC,CAE3B"}
+{"version":3,"file":"frame-by-type.d.ts","sourceRoot":"","sources":["../src/frame-by-type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAGzC,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAIjD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,CAAC,CAAC;CAC1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,YAAY,CAkBrE;AAED;;;;;;;;;;;GAWG;AACH,wBAAuB,aAAa,CAClC,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,aAAa,CAAC,UAAU,CAAC,CA6B3B"}

package/dist/frame-by-type.js

@@ -1,22 +1,19 @@
 import jsonld from 'jsonld';
-import { rdf } from '@tpluscode/rdf-ns-builders';
-const RDF_TYPE = rdf.type.value;
 const FRAME_OPTIONS = { omitGraph: false, embed: '@always' };
 /**
- * Iterate `quads` once, grouping each subject’s triples and collecting the root
- * subjects of every type in `rootTypes`. Duplicate triples are collapsed here
- * because some SPARQL engines (e.g. QLever) do not deduplicate CONSTRUCT
- * output. The source is consumed a single time, so it may be a one-shot
- * iterable (a generator chaining several sources); the whole subject index is
- * held, but never more than that plus one framed subgraph at a time
+ * Iterate `quads` once, grouping each subject’s triples. Duplicate triples are
+ * collapsed here because some SPARQL engines (e.g. QLever) do not deduplicate
+ * CONSTRUCT output. The source is consumed a single time, so it may be a
+ * one-shot iterable (a generator chaining several sources); the whole subject
+ * index is held, but never more than that plus one framed subgraph at a time
  * downstream.
+ *
+ * Roots are never discovered here – the caller ({@link projectRoots}, from the
+ * pipeline selector) already holds them and passes them to {@link frameSubjects}
+ * – so `quads` need carry no `rdf:type` triple.
  */
-export function buildSubjectIndex(quads, rootTypes) {
+export function buildSubjectIndex(quads) {
     const bySubject = new Map();
-    const rootsByType = new Map();
-    for (const type of rootTypes) {
-        rootsByType.set(type, []);
-    }
     const seen = new Set();
     for (const quad of quads) {
         const key = `${quad.subject.value} ${quad.predicate.value} ${quad.object.value} ${quad.object.termType === 'Literal' ? quad.object.language || quad.object.datatype.value : ''}`;
@@ -32,31 +29,23 @@ export function buildSubjectIndex(quads, rootTypes) {
         else {
             owned.push(quad);
         }
-        // `rootsByType` is keyed by exactly the requested root types, so the lookup
-        // doubles as the membership test: a hit means this subject is a root.
-        if (quad.predicate.value === RDF_TYPE) {
-            const roots = rootsByType.get(quad.object.value);
-            if (roots !== undefined) {
-                roots.push(subject);
-            }
-        }
     }
-    return { bySubject, rootsByType };
+    return { bySubject };
 }
 /**
- * Frame every root subject of `rootType` from a prebuilt {@link SubjectIndex}
- * into one JSON-LD node – the reusable core behind {@link frameByType}. Each
- * root subject’s own triples plus the one-hop nodes it references (e.g. nested
- * publisher/distribution resources) are framed one subject at a time, so beyond
- * the shared subject index only a single subgraph is held (whole-graph
- * `jsonld.frame()` is ~O(N²)). The frame carries no `@context`, so framed keys
- * are full predicate IRIs.
+ * Frame each of the given `roots` from a prebuilt {@link SubjectIndex} into one
+ * JSON-LD node. Each root subject’s own triples plus the one-hop nodes it
+ * references (e.g. nested publisher/distribution resources) are framed one
+ * subject at a time, so beyond the shared subject index only a single subgraph
+ * is held (whole-graph `jsonld.frame()` is ~O(N²)). The frame carries no
+ * `@context`, so framed keys are full predicate IRIs.
+ *
+ * The roots are supplied explicitly rather than discovered from `rdf:type`: the
+ * caller ({@link projectRoots}, from the pipeline selector) already holds them
+ * and passes them directly. A root absent from the index simply frames nothing.
  */
-export async function* frameSubjects(index, rootType) {
+export async function* frameSubjects(index, roots) {
     const { bySubject } = index;
-    // A type the index was not built for has no roots, so it frames nothing; the
-    // `projectType`/`projectGraph` callers only pass types they registered.
-    const roots = index.rootsByType.get(rootType) ?? [];
     for (const rootIri of roots) {
         const owned = bySubject.get(rootIri) ?? [];
         const referenced = owned
@@ -65,11 +54,12 @@ export async function* frameSubjects(index, rootType) {
             .flatMap((quad) => bySubject.get(quad.object.value) ?? []);
         const subgraph = [...owned, ...referenced];
         const expanded = await jsonld.fromRDF(subgraph);
-        // Frame for THIS specific root subject by `@id`, not just by root type. A
-        // one-hop reference can itself be of `rootType` (e.g. a terminology source
-        // that is also a separately registered dataset), so framing by type alone
-        // returns several root nodes and `[0]` could be the referenced one — which
-        // would emit it twice and drop this subject entirely.
+        // Frame for THIS specific root subject by its `@id`. The subgraph embeds the
+        // root’s one-hop references, and such a referent can itself be one of the
+        // requested `roots` (e.g. a terminology source that is also a separately
+        // registered dataset). Framing by `{ '@id': rootIri }` pins the output to
+        // this subject, so the referent is framed once in its own turn rather than
+        // surfacing here as a second `@graph` node that `[0]` might pick instead.
         const framed = await jsonld.frame(expanded, { '@id': rootIri }, FRAME_OPTIONS);
         const node = framed['@graph']?.[0];
         if (node !== undefined) {
@@ -77,13 +67,3 @@ export async function* frameSubjects(index, rootType) {
         }
     }
 }
-/**
- * Frame CONSTRUCT quads into one JSON-LD node per subject of `rootType`, for a
- * single root type. Consumes `quads` once (see {@link buildSubjectIndex}), so
- * it accepts any `Iterable` – a materialized array or a chained generator. For
- * a multi-type schema, {@link buildSubjectIndex} + {@link frameSubjects} share
- * one index across types rather than re-scanning per type.
- */
-export async function* frameByType(quads, rootType) {
-    yield* frameSubjects(buildSubjectIndex(quads, [rootType]), rootType);
-}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { projectGraph, irisOf, literalsOf, firstLiteralOf } from './project.js';
-export type { SearchDocument, TypedSearchDocument } from './project.js';
+export { projectRoots, irisOf, literalsOf, firstLiteralOf } from './project.js';
+export type { SearchDocument } from './project.js';
 export { defineSearchType, searchSchema, validateSearchType, assertValidSearchType, } from './schema.js';
 export type { FieldKind, SearchField, SearchFieldBase, TextField, KeywordField, ReferenceField, NumericField, BooleanField, SearchType, SearchTypeIssue, SearchSchema, FacetRange, } from './schema.js';
 export type { SearchQuery, Filter, Sort } from './query.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAChF,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAKxE,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,SAAS,EACT,WAAW,EACX,eAAe,EACf,SAAS,EACT,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,eAAe,EACf,YAAY,EACZ,UAAU,GACX,MAAM,aAAa,CAAC;AAIrB,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAI5D,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,cAAc,EACd,WAAW,EACX,cAAc,EACd,SAAS,EACT,WAAW,EACX,QAAQ,EACR,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAChF,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAKnD,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,SAAS,EACT,WAAW,EACX,eAAe,EACf,SAAS,EACT,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,eAAe,EACf,YAAY,EACZ,UAAU,GACX,MAAM,aAAa,CAAC;AAIrB,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAI5D,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,cAAc,EACd,WAAW,EACX,cAAc,EACd,SAAS,EACT,WAAW,EACX,QAAQ,EACR,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -6,8 +6,8 @@
 // Projection: RDF CONSTRUCT quads → flat search documents, driven by the
 // unified SearchField/SearchType model. The IR readers (irisOf, …) are here
 // because `derive` functions are written against them.
-export { projectGraph, irisOf, literalsOf, firstLiteralOf } from './project.js';
+export { projectRoots, irisOf, literalsOf, firstLiteralOf } from './project.js';
 // Unified field model: one declaration drives projection, engine collection
-// schema, query semantics and the GraphQL surface — a discriminated union by
+// schema, query semantics and the GraphQL surface – a discriminated union by
 // `kind`, validated again at runtime when the schema is built.
 export { defineSearchType, searchSchema, validateSearchType, assertValidSearchType, } from './schema.js';

package/dist/project.d.ts

@@ -5,16 +5,6 @@ import { type SearchSchema, type SearchType } from './schema.js';
 export type SearchDocument = {
     id: string;
 } & Record<string, unknown>;
-/**
- * A projected document tagged with the {@link SearchType} it was projected
- * from – one element of {@link projectGraph}’s mixed, whole-schema stream. The
- * tag is what lets a multi-collection writer route each document to the
- * collection for its type without re-deriving the type from the document.
- */
-export interface TypedSearchDocument {
-    readonly searchType: SearchType;
-    readonly document: SearchDocument;
-}
 /**
  * Project one framed JSON-LD node into a flat search document: apply each field
  * of the type in declaration order. A field with a `derive` function computes
@@ -25,20 +15,19 @@ export interface TypedSearchDocument {
  */
 export declare function projectDocument(node: FramedNode, searchType: SearchType): SearchDocument;
 /**
- * Frame `quads` for every root type in the schema and project each node with its
- * type’s declaration – the multi-shape pipeline. Yields each document tagged
- * with its {@link SearchType} ({@link TypedSearchDocument}), so a downstream
- * multi-collection writer can route it to that type’s collection; a
- * single-collection consumer just reads `.document`. Streams one document at a
- * time so memory stays flat. The IR maps to a declaration by type, so adding a
- * shape is adding a `SearchType` to the schema (no engine change).
+ * Project a single type over a known set of `roots` – the per-type, roots-given
+ * projection. The roots are supplied by the caller (the pipeline selector)
+ * rather than discovered from `rdf:type`, so `quads` need carry no type triples
+ * and the projection frames each distinct subject once. {@link assertTypeInSchema}
+ * guards that `searchType` belongs to `schema` – the port’s own membership check
+ * – so no schema is ever forged to scope a projection to one type. Yields a bare
+ * {@link SearchDocument}: pairing a document with its type is a routing concern,
+ * owned by the pipeline glue, not the projection.
  *
- * Consumes `quads` once (a single scan builds the shared subject index that
- * every type frames off), so it accepts any `Iterable` – a materialized array or
- * a chained generator merging several sources (`function* () { yield* a; yield* b; }`)
- * with no intermediate copy at the projection peak.
+ * Consumes `quads` once, so it accepts any `Iterable` – a batch’s materialized
+ * array or a chained generator merging several readers.
  */
-export declare function projectGraph(quads: Iterable<Quad>, schema: SearchSchema): AsyncIterable<TypedSearchDocument>;
+export declare function projectRoots(quads: Iterable<Quad>, roots: readonly string[], schema: SearchSchema, searchType: SearchType): AsyncIterable<SearchDocument>;
 export declare function literalsOf(node: FramedNode, path: string): string[];
 export declare function firstLiteralOf(node: FramedNode, path: string): string | undefined;
 export declare function irisOf(node: FramedNode, path: string): string[];

package/dist/project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAOL,KAAK,YAAY,EACjB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AAErB,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,UAAU,GACrB,cAAc,CAYhB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAuB,YAAY,CACjC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,EACrB,MAAM,EAAE,YAAY,GACnB,aAAa,CAAC,mBAAmB,CAAC,CAWpC;AAqJD,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAInE;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAI/D"}
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAQL,KAAK,YAAY,EACjB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AAErB,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEtE;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,UAAU,GACrB,cAAc,CAYhB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAuB,YAAY,CACjC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,EACrB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,UAAU,GACrB,aAAa,CAAC,cAAc,CAAC,CAU/B;AAqJD,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAInE;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAI/D"}

package/dist/project.js

@@ -1,6 +1,6 @@
 import { fold } from '@lde/text-normalization';
 import { buildSubjectIndex, frameSubjects, } from './frame-by-type.js';
-import { displayFieldName, isoToUnixSeconds, physicalFields, } from './schema.js';
+import { assertTypeInSchema, displayFieldName, isoToUnixSeconds, physicalFields, } from './schema.js';
 /**
  * Project one framed JSON-LD node into a flat search document: apply each field
  * of the type in declaration order. A field with a `derive` function computes
@@ -21,26 +21,27 @@ export function projectDocument(node, searchType) {
     return document;
 }
 /**
- * Frame `quads` for every root type in the schema and project each node with its
- * type’s declaration – the multi-shape pipeline. Yields each document tagged
- * with its {@link SearchType} ({@link TypedSearchDocument}), so a downstream
- * multi-collection writer can route it to that type’s collection; a
- * single-collection consumer just reads `.document`. Streams one document at a
- * time so memory stays flat. The IR maps to a declaration by type, so adding a
- * shape is adding a `SearchType` to the schema (no engine change).
+ * Project a single type over a known set of `roots` – the per-type, roots-given
+ * projection. The roots are supplied by the caller (the pipeline selector)
+ * rather than discovered from `rdf:type`, so `quads` need carry no type triples
+ * and the projection frames each distinct subject once. {@link assertTypeInSchema}
+ * guards that `searchType` belongs to `schema` – the port’s own membership check
+ * – so no schema is ever forged to scope a projection to one type. Yields a bare
+ * {@link SearchDocument}: pairing a document with its type is a routing concern,
+ * owned by the pipeline glue, not the projection.
  *
- * Consumes `quads` once (a single scan builds the shared subject index that
- * every type frames off), so it accepts any `Iterable` – a materialized array or
- * a chained generator merging several sources (`function* () { yield* a; yield* b; }`)
- * with no intermediate copy at the projection peak.
+ * Consumes `quads` once, so it accepts any `Iterable` – a batch’s materialized
+ * array or a chained generator merging several readers.
  */
-export async function* projectGraph(quads, schema) {
-    const types = [...schema.values()];
-    const index = buildSubjectIndex(quads, types.map((searchType) => searchType.class));
-    for (const searchType of types) {
-        for await (const node of frameSubjects(index, searchType.class)) {
-            yield { searchType, document: projectDocument(node, searchType) };
-        }
+export async function* projectRoots(quads, roots, schema, searchType) {
+    assertTypeInSchema(schema, searchType);
+    const index = buildSubjectIndex(quads);
+    // Distinct roots only. A selector may return an IRI more than once – a
+    // non-`DISTINCT` `SELECT` over a one-to-many join yields the same subject per
+    // matched row – and a repeated root would otherwise frame and emit a
+    // duplicate document under the same `id`.
+    for await (const node of frameSubjects(index, [...new Set(roots)])) {
+        yield projectDocument(node, searchType);
     }
 }
 function applyField(document, node, field) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Engine- and domain-agnostic core for RDF-backed search: a unified declarative field model (SearchField/SearchType/SearchSchema), a neutral query IR, the SearchEngine port with logical result types, and a streaming CONSTRUCT-to-document projection. Bakes in no engine, protocol, or domain.",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",
@@ -39,12 +39,12 @@
   "dependencies": {
     "@lde/text-normalization": "^0.1.1",
     "@rdfjs/types": "^2.0.1",
-    "@tpluscode/rdf-ns-builders": "^5.0.0",
     "inflection": "^3.0.2",
     "jsonld": "^9.0.0",
     "tslib": "^2.3.0"
   },
   "devDependencies": {
+    "@tpluscode/rdf-ns-builders": "^5.0.0",
     "@types/jsonld": "^1.5.15",
     "n3": "^2.1.1"
   },