@lde/search 0.8.1 → 0.10.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,8 +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),
-  validation, and every model/query/result type.
+  `searchSchema`, `projectRoots`, validation, and every model/query/result type.
 - **`@lde/search/adapter`** – plumbing for engine adapters and API surfaces:
   `physicalFields`, the field selectors, `assertValidQuery`, the filter
   operators and storage codecs.
@@ -78,8 +77,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
 
@@ -100,20 +100,19 @@ Two conventions hold across the whole family:
 ## Field model
 
 The mapping is data, not code. Each field declares its `kind`, the IR `path` to
-read (or a `derive` function for a **derived** field, computed from the framed
-node in declaration order – so it may read fields declared before it), and the
-capabilities it opts into. The physical field names a declaration fans out to
-(per-locale search/sort keys) come from
-`physicalFields`, the single convention projection, the collection definition and the
-query compiler all share.
+read (or a `derive` function for a **derived** field, computed from the document
+in declaration order – so it may read fields declared before it, never the
+graph), and the capabilities (**roles**) it opts into. `path` is therefore the
+complete statement of what the projection reads from the graph. A field that
+declares **no** role is an **internal field**: projected so a later `derive` can
+read it, then pruned before the writer and absent from the collection definition
+– not stored, not indexed, no RAM. The physical field names a declaration fans
+out to (per-locale search/sort keys) come from `physicalFields`, the single
+convention projection, the collection definition and the query compiler all
+share.
 
 ```ts
-import {
-  defineSearchType,
-  projectGraph,
-  irisOf,
-  searchSchema,
-} from '@lde/search';
+import { defineSearchType, projectRoots, searchSchema } from '@lde/search';
 
 const DATASET = defineSearchType({
   name: 'Dataset', // logical API name: names the GraphQL type, a REST path, …
@@ -140,24 +139,27 @@ const DATASET = defineSearchType({
     },
     // → size (int)
     { name: 'size', path: 'urn:dr:size', kind: 'integer', sortable: true },
-    // derived field (no path): computed from the framed node
+    // internal field (no role): projected as a reading device for the derive
+    // below, then pruned before the writer – absent from the collection too
+    { name: 'classes', path: 'urn:dr:class', kind: 'reference' },
+    // derived field (no path): computed from the document in declaration order,
+    // never from the graph – so `path` stays the whole statement of what is read
     {
       name: 'classCount',
       kind: 'integer',
       sortable: true,
-      derive: (node) => irisOf(node, 'urn:dr:class').length,
+      derive: (document) =>
+        (document.classes as string[] | undefined)?.length ?? 0,
     },
   ],
 });
 
-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 +221,39 @@ 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.
+Every predicate a value comes from is read through a field’s `path`; a `derive`
+computes only from the document projected so far, so `path` is the whole
+statement of what the projection reads. `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 +317,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/adapter.d.ts

@@ -6,7 +6,7 @@
  * deployment author declaring a schema and running searches needs none of
  * this; the main entry point carries that (small) authoring surface.
  */
-export { assertTypeInSchema, physicalFields, displayFieldName, displayFieldPattern, displayLangOf, searchableFields, facetableFields, filterableFields, sortableFields, outputFields, referenceFields, fieldNamed, labelFieldOf, isRangeFacet, isoToUnixSeconds, unixSecondsToIso, } from './schema.js';
+export { assertTypeInSchema, physicalFields, displayFieldName, displayFieldPattern, displayLangOf, searchableFields, facetableFields, filterableFields, sortableFields, outputFields, isInternalField, referenceFields, fieldNamed, labelFieldOf, isRangeFacet, isoToUnixSeconds, unixSecondsToIso, } from './schema.js';
 export type { PhysicalFields } from './schema.js';
 export { physicalNameTokens } from './physical-name.js';
 export { filterOperatorFor, filterOperator, validateQuery, assertValidQuery, pageForOffset, } from './query.js';

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,eAAe,EACf,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/adapter.js

@@ -6,6 +6,6 @@
  * deployment author declaring a schema and running searches needs none of
  * this; the main entry point carries that (small) authoring surface.
  */
-export { assertTypeInSchema, physicalFields, displayFieldName, displayFieldPattern, displayLangOf, searchableFields, facetableFields, filterableFields, sortableFields, outputFields, referenceFields, fieldNamed, labelFieldOf, isRangeFacet, isoToUnixSeconds, unixSecondsToIso, } from './schema.js';
+export { assertTypeInSchema, physicalFields, displayFieldName, displayFieldPattern, displayLangOf, searchableFields, facetableFields, filterableFields, sortableFields, outputFields, isInternalField, referenceFields, fieldNamed, labelFieldOf, isRangeFacet, isoToUnixSeconds, unixSecondsToIso, } from './schema.js';
 export { physicalNameTokens } from './physical-name.js';
 export { filterOperatorFor, filterOperator, validateQuery, assertValidQuery, pageForOffset, } from './query.js';

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,29 +2,29 @@ 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 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
@@ -33,19 +33,9 @@ export declare function buildSubjectIndex(quads: Iterable<Quad>, rootTypes: Iter
  * 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`: a
- * caller with the roots already in hand ({@link projectRoots}, from the pipeline
- * selector) passes them directly; a whole-graph caller ({@link frameByType},
- * {@link projectGraph}) passes {@link SubjectIndex.rootsByType}. A root absent
- * from the index simply frames nothing.
+ * 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, roots: readonly 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>;
 //# 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;;;;;;;;;;;;;GAaG;AACH,wBAAuB,aAAa,CAClC,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,aAAa,CAAC,UAAU,CAAC,CA4B3B;AAED;;;;;;GAMG;AACH,wBAAuB,WAAW,CAChC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,EACrB,QAAQ,EAAE,MAAM,GACf,aAAa,CAAC,UAAU,CAAC,CAG3B"}
+{"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,16 +29,8 @@ 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 each of the given `roots` from a prebuilt {@link SubjectIndex} into one
@@ -51,11 +40,9 @@ export function buildSubjectIndex(quads, rootTypes) {
  * 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`: a
- * caller with the roots already in hand ({@link projectRoots}, from the pipeline
- * selector) passes them directly; a whole-graph caller ({@link frameByType},
- * {@link projectGraph}) passes {@link SubjectIndex.rootsByType}. A root absent
- * from the index simply frames nothing.
+ * 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, roots) {
     const { bySubject } = index;
@@ -67,11 +54,12 @@ export async function* frameSubjects(index, roots) {
             .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) {
@@ -79,14 +67,3 @@ export async function* frameSubjects(index, roots) {
         }
     }
 }
-/**
- * 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) {
-    const index = buildSubjectIndex(quads, [rootType]);
-    yield* frameSubjects(index, index.rootsByType.get(rootType) ?? []);
-}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { projectGraph, projectRoots, irisOf, literalsOf, firstLiteralOf, } from './project.js';
-export type { SearchDocument, TypedSearchDocument } from './project.js';
+export { projectRoots } 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,EACL,YAAY,EACZ,YAAY,EACZ,MAAM,EACN,UAAU,EACV,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,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,cAAc,CAAC;AAC5C,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

@@ -4,9 +4,9 @@
 // under `@lde/search/adapter`; the engine-port conformance suite under
 // `@lde/search/testing`.
 // 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, projectRoots, irisOf, literalsOf, firstLiteralOf, } from './project.js';
+// unified SearchField/SearchType model. A `derive` reads the projected document,
+// never the graph, so the IR readers stay internal to projection.
+export { projectRoots } from './project.js';
 // Unified field model: one declaration drives projection, engine collection
 // schema, query semantics and the GraphQL surface – a discriminated union by
 // `kind`, validated again at runtime when the schema is built.

package/dist/project.d.ts

@@ -5,56 +5,31 @@ 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
- * its value from the node and the document as populated so far (so a derived
- * field may read fields declared before it). The physical field names a field
- * fans out to come from {@link physicalFields}, the single source shared with
- * the engine collection definition and the query compiler.
+ * its value from the document as populated so far (so a derived field may read
+ * fields declared before it), never from the graph – `path` is the complete
+ * statement of what the projection reads. {@link isInternalField Internal
+ * fields} (those declaring no role) are populated so a later derive can read
+ * them, then pruned before the document is returned: they must reach neither a
+ * writer nor the collection definition. The physical field names a field fans
+ * out to come from {@link physicalFields}, the single source shared with the
+ * engine collection definition and the query compiler.
  */
 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).
- *
- * 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.
- */
-export declare function projectGraph(quads: Iterable<Quad>, schema: SearchSchema): AsyncIterable<TypedSearchDocument>;
 /**
  * Project a single type over a known set of `roots` – the per-type, roots-given
- * projection. Unlike {@link projectGraph}, 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}: tagging a
- * document with its type is a routing concern, owned by the pipeline glue, not
- * the projection.
+ * 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, so it accepts any `Iterable` – a batch’s materialized
  * array or a chained generator merging several readers.
  */
 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[];
 //# sourceMappingURL=project.d.ts.map

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,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;;;;;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,CAYpC;AAED;;;;;;;;;;;;;GAaG;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,CAW/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"}
+{"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,EASL,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;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,UAAU,GACrB,cAAc,CAoBhB;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"}

package/dist/project.js

@@ -1,13 +1,17 @@
 import { fold } from '@lde/text-normalization';
 import { buildSubjectIndex, frameSubjects, } from './frame-by-type.js';
-import { assertTypeInSchema, displayFieldName, isoToUnixSeconds, physicalFields, } from './schema.js';
+import { assertTypeInSchema, displayFieldName, isInternalField, 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
- * its value from the node and the document as populated so far (so a derived
- * field may read fields declared before it). The physical field names a field
- * fans out to come from {@link physicalFields}, the single source shared with
- * the engine collection definition and the query compiler.
+ * its value from the document as populated so far (so a derived field may read
+ * fields declared before it), never from the graph – `path` is the complete
+ * statement of what the projection reads. {@link isInternalField Internal
+ * fields} (those declaring no role) are populated so a later derive can read
+ * them, then pruned before the document is returned: they must reach neither a
+ * writer nor the collection definition. The physical field names a field fans
+ * out to come from {@link physicalFields}, the single source shared with the
+ * engine collection definition and the query compiler.
  */
 export function projectDocument(node, searchType) {
     const id = node['@id'];
@@ -18,61 +22,43 @@ export function projectDocument(node, searchType) {
     for (const field of searchType.fields) {
         applyField(document, node, field);
     }
-    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).
- *
- * 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.
- */
-export async function* projectGraph(quads, schema) {
-    const types = [...schema.values()];
-    const index = buildSubjectIndex(quads, types.map((searchType) => searchType.class));
-    for (const searchType of types) {
-        const roots = index.rootsByType.get(searchType.class) ?? [];
-        for await (const node of frameSubjects(index, roots)) {
-            yield { searchType, document: projectDocument(node, searchType) };
+    // Prune internal fields: they were projected only so the derives above could
+    // read them (a structural memo shared across every derive that needs the
+    // value), and must not reach the writer or the collection definition.
+    for (const field of searchType.fields) {
+        if (isInternalField(field)) {
+            delete document[field.name];
         }
     }
+    return document;
 }
 /**
  * Project a single type over a known set of `roots` – the per-type, roots-given
- * projection. Unlike {@link projectGraph}, 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}: tagging a
- * document with its type is a routing concern, owned by the pipeline glue, not
- * the projection.
+ * 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, so it accepts any `Iterable` – a batch’s materialized
  * array or a chained generator merging several readers.
  */
 export async function* projectRoots(quads, roots, schema, searchType) {
     assertTypeInSchema(schema, searchType);
-    const index = buildSubjectIndex(quads, []);
+    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`. (`projectGraph`’s roots come from
-    // `rootsByType`, which is inherently unique, so it never needs this.)
+    // 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) {
     if (field.derive !== undefined) {
-        const value = field.derive(node, document);
+        const value = field.derive(document);
         if (value !== undefined) {
             document[field.name] = value;
         }
@@ -172,15 +158,15 @@ function langValuesOf(node, path) {
         .map(toLangValue)
         .filter((value) => value !== undefined);
 }
-export function literalsOf(node, path) {
+function literalsOf(node, path) {
     return valuesOf(node, path)
         .map(literalString)
         .filter((value) => value !== undefined);
 }
-export function firstLiteralOf(node, path) {
+function firstLiteralOf(node, path) {
     return literalsOf(node, path)[0];
 }
-export function irisOf(node, path) {
+function irisOf(node, path) {
     return valuesOf(node, path)
         .map(iriString)
         .filter((value) => value !== undefined);

package/dist/schema.d.ts

@@ -1,4 +1,3 @@
-import type { FramedNode } from './frame-by-type.js';
 import type { SearchDocument } from './project.js';
 /**
  * The engine-neutral kind of a queryable field. It drives every downstream
@@ -32,9 +31,11 @@ export declare function filterOperatorFor(kind: FieldKind): FilterOperator | und
  * Capability flags (`searchable`/`filterable`/`facetable`/`sortable`/`output`)
  * are independent opt-ins: a field exposes exactly the roles it declares. A
  * field with a {@link SearchFieldBase.derive `derive`} function instead of a
- * `path` is a **derived field** – computed from the framed node rather than
- * projected from the IR – yet it still carries full query/schema/output
- * behavior (e.g. `status`, the compatibility booleans).
+ * `path` is a **derived field** – computed from the document projected so far
+ * rather than read from the graph – yet it still carries full query/schema/output
+ * behavior (e.g. `status`, the compatibility booleans). A field declaring **no**
+ * role at all is an {@link isInternalField **internal field**}: projected so a
+ * later derive can read it, then pruned before the writer.
  *
  * The physical field names a declaration fans out to (per-locale search/sort
  * keys) follow one convention, owned by
@@ -73,15 +74,17 @@ export interface SearchFieldBase {
     readonly sortable?: boolean;
     /**
      * Compute this field’s value instead of projecting it from a `path` – a
-     * status token, a compatibility boolean, a count over the framed node.
+     * status token, a compatibility boolean, a count over an earlier field.
      * Mutually exclusive with `path`. Runs in declaration order during
-     * projection, receiving the framed node and the document as populated so
-     * far, so a derived field may read fields declared before it (e.g. a
-     * `statusRank` reading the derived `status`). Return `undefined` to leave
-     * the field absent. The field still carries full query/schema/output
-     * behaviour like any other.
+     * projection, receiving **only** the document as populated so far – never the
+     * graph – so a derived field reads fields declared before it (e.g. a
+     * `statusRank` reading the derived `status`, or a count reading an
+     * {@link isInternalField internal} field). Return `undefined` to leave the
+     * field absent. The field still carries full query/schema/output behaviour
+     * like any other. Reading only the document is what keeps `path` the complete
+     * statement of what the projection reads from the graph.
      */
-    readonly derive?: (node: FramedNode, document: SearchDocument) => unknown;
+    readonly derive?: (document: SearchDocument) => unknown;
 }
 /** Full-text inclusion with a `query_by` weight (folded; per-locale for
  *  localized text). Presence is what makes a field searchable. */
@@ -374,6 +377,19 @@ export declare function filterableFields(searchType: SearchType): readonly Searc
 export declare function sortableFields(searchType: SearchType): readonly SearchField[];
 /** Fields that appear in the API output type, in declaration order. */
 export declare function outputFields(searchType: SearchType): readonly SearchField[];
+/**
+ * Whether a field declares **no** role – none of `output`, `searchable`,
+ * `filterable`, `facetable`, `sortable`. Such a field is an **internal field**:
+ * the projection populates it (so a later {@link SearchFieldBase.derive} can
+ * read it), then prunes it before the document reaches a writer, and the engine
+ * collection definition omits it entirely – not stored, not indexed, no RAM.
+ * Absence of a role declares that intent; there is no separate marker flag.
+ *
+ * The single predicate the projection and the collection definition share, so
+ * they cannot disagree on what is internal. See the Search context’s load-bearing
+ * line: *a field without a Role is an Internal Field.*
+ */
+export declare function isInternalField(field: SearchField): boolean;
 /** Fields of kind `reference` (IRI-valued, label-resolved), in declaration order. */
 export declare function referenceFields(searchType: SearchType): readonly ReferenceField[];
 /** Look up a field by its logical name. */

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,SAAS,GACT,SAAS,GACT,QAAQ,GACR,SAAS,GACT,MAAM,GACN,WAAW,CAAC;AAEhB;oEACoE;AACpE,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,OAAO,GAAG,IAAI,CAAC;AAcnD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,GAAG,cAAc,GAAG,SAAS,CAE7E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,WAAW,GACnB,SAAS,GACT,YAAY,GACZ,cAAc,GACd,YAAY,GACZ,YAAY,CAAC;AAEjB,qEAAqE;AACrE,MAAM,WAAW,eAAe;IAC9B;wCACoC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;+EAC2E;IAC3E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,oBAAoB;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB;;yCAEqC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,yBAAyB;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,iCAAiC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,cAAc,KAAK,OAAO,CAAC;CAC3E;AAED;kEACkE;AAClE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACnD;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,SAAU,SAAQ,eAAe,EAAE,UAAU;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC;CAC9B;AAED;gCACgC;AAChC,MAAM,WAAW,YAAa,SAAQ,eAAe,EAAE,UAAU;IAC/D,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,wEAAwE;IACxE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/C,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC;CAC9B;AAED,gFAAgF;AAChF,MAAM,WAAW,cAAe,SAAQ,eAAe,EAAE,UAAU;IACjE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,uCAAuC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/C,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC;IAC7B;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;0DAEsD;IACtD,QAAQ,CAAC,GAAG,CAAC,EAAE;QACb;;;;;qCAK6B;QAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B;;;;6EAIqE;QACrE,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;KACtD,CAAC;CACH;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CAC9C;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAa,SAAQ,eAAe,EAAE,cAAc;IACnE,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC7C,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,CAAC;CAC7B;AAED,0DAA0D;AAC1D,MAAM,WAAW,YAAa,SAAQ,eAAe;IACnD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB;;;;+CAI2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;2DACuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;CACzC;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,IAAI,SAAS,UAAU,EAC5D,UAAU,EAAE,IAAI,GACf,IAAI,CAEN;AAED;;;;;;GAMG;AACH;;;uCAGuC;AACvC,MAAM,CAAC,OAAO,CAAC,MAAM,iBAAiB,EAAE,OAAO,MAAM,CAAC;AAEtD,MAAM,WAAW,YAAY,CAC3B,KAAK,SAAS,SAAS,UAAU,EAAE,GAAG,SAAS,UAAU,EAAE,CAC3D,SAAQ,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,CAAC,iBAAiB,CAAC,EAAE,IAAI,CAAC;CACpC;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,KAAK,SAAS,SAAS,UAAU,EAAE,EACpE,GAAG,KAAK,EAAE,KAAK,GACd,YAAY,CAAC,KAAK,CAAC,CAuBrB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,GAAG,SAAS,CAQ1E;AAsCD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EACX,sBAAsB,GACtB,oBAAoB,GACpB,gBAAgB,GAChB,aAAa,GACb,iBAAiB,GACjB,uBAAuB,GACvB,qBAAqB,GACrB,0BAA0B,GAC1B,wBAAwB,GACxB,uBAAuB,GACvB,kBAAkB,GAClB,qBAAqB,GACrB,oBAAoB,CAAC;CAC1B;AA0BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,UAAU,GACrB,SAAS,eAAe,EAAE,CA+E5B;AAWD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,UAAU,GACrB,IAAI,CAUN;AAED;+EAC+E;AAC/E,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAQlE;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B;sEACkE;IAClE,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;4EACwE;IACxE,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAExE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,EAChB,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,SAAS,CAOpB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,UAAU,GACrB,SAAS,CAAC,WAAW,GAAG;IACzB,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD,CAAC,EAAE,CAOH;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAC7B,UAAU,EAAE,UAAU,GACrB,SAAS,WAAW,EAAE,CAExB;AAED,sDAAsD;AACtD,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,UAAU,GACrB,SAAS,WAAW,EAAE,CAExB;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,WAAW,EAAE,CAE7E;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,WAAW,EAAE,CAE3E;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAC7B,UAAU,EAAE,UAAU,GACrB,SAAS,cAAc,EAAE,CAE3B;AAED,2CAA2C;AAC3C,wBAAgB,UAAU,CACxB,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,MAAM,GACX,WAAW,GAAG,SAAS,CAEzB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,WAAW,GACjB,KAAK,IAAI,YAAY,GAAG;IAAE,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CAEzE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGhE;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,cAAc,CAgBjE"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/schema.js

@@ -317,6 +317,25 @@ export function sortableFields(searchType) {
 export function outputFields(searchType) {
     return searchType.fields.filter((field) => field.output === true);
 }
+/**
+ * Whether a field declares **no** role – none of `output`, `searchable`,
+ * `filterable`, `facetable`, `sortable`. Such a field is an **internal field**:
+ * the projection populates it (so a later {@link SearchFieldBase.derive} can
+ * read it), then prunes it before the document reaches a writer, and the engine
+ * collection definition omits it entirely – not stored, not indexed, no RAM.
+ * Absence of a role declares that intent; there is no separate marker flag.
+ *
+ * The single predicate the projection and the collection definition share, so
+ * they cannot disagree on what is internal. See the Search context’s load-bearing
+ * line: *a field without a Role is an Internal Field.*
+ */
+export function isInternalField(field) {
+    return (field.output !== true &&
+        field.searchable === undefined &&
+        field.filterable !== true &&
+        field.facetable !== true &&
+        field.sortable !== true);
+}
 /** Fields of kind `reference` (IRI-valued, label-resolved), in declaration order. */
 export function referenceFields(searchType) {
     return searchType.fields.filter((field) => field.kind === 'reference');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search",
-  "version": "0.8.1",
+  "version": "0.10.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"
   },