@lde/search 0.9.0 → 0.11.0

package/README.md

@@ -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`, `projectRoots` (+ 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.
@@ -72,11 +71,22 @@ Exports are stratified by audience:
 The model has three levels, with analogues in SHACL ([one possible source](#why-a-declarative-model))
 and GraphQL (one of the surfaces):
 
-| Term           | What it is                                                                                                       | SHACL          | GraphQL     |
-| -------------- | ---------------------------------------------------------------------------------------------------------------- | -------------- | ----------- |
-| `SearchField`  | One queryable field: a `kind`, the IR `path` it projects from, and the capability flags it opts into             | property shape | field       |
-| `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      |
+| Term           | What it is                                                                                                                                                                                                                       | SHACL          | GraphQL     |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ----------- |
+| `SearchField`  | One queryable field: a `kind`, the IR `path` it projects from, and the capability flags it opts into                                                                                                                             | property shape | field       |
+| `SearchType`   | One type’s complete declaration: its logical API `name` and fields (incl. derived). A **Root Type** declares a `class` (indexed, keys the schema); a **Reference Type** declares none (reached only through an inline reference) | NodeShape      | object type |
+| `SearchSchema` | The whole search declaration: every Root Type, keyed by `class` IRI, plus the Reference Types – build one with `searchSchema(...types)`                                                                                          | shapes graph   | schema      |
+
+A `SearchType` is a **Root Type** or a **Reference Type**, told apart by one
+absence: a Root Type declares a `class`, so roots are selected for it and a
+writer opens a collection for it; a Reference Type declares none, so it is
+never selected, framed by type or indexed – its identity is its name, and its
+type comes from the edge that points at it. `searchSchema` partitions its
+arguments accordingly: Root Types key the class map (`schema.values()` yields
+only them, so no writer ever opens a collection for a Reference Type), Reference
+Types go into a name index an inline `ref.typeName` resolves against. The
+absence is load-bearing, and enforced at the type level – an indexed Reference
+Type fails to compile ([ADR 11](../../docs/decisions/0011-decouple-rdf-depth-from-the-api-surface.md)).
 
 `projectRoots` and the engine port each execute one `SearchType` at a time –
 projection over the roots the pipeline selector supplied for that type; the
@@ -101,20 +111,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,
-  projectRoots,
-  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, …
@@ -141,12 +150,17 @@ 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,
     },
   ],
 });
@@ -205,10 +219,29 @@ directly.
 | `date`               | `range` (inclusive)  | yes   | yes              | ISO 8601 string (surface)       |
 | `boolean`            | `is`                 | yes   | –                | boolean (absent = false)        |
 
-A `reference` carries `labelOnly` today (id + display label); the `idOnly` and
-`inline` strategies are forward declarations. References are object-shaped from
-day one so that `inline` can later **add** fields to a reference type without
-breaking clients.
+A `reference` carries one of two strategies today: `labelOnly` (id + display
+label, resolved at query time from a label source) and `inline` (the referent’s
+own projected fields, carried inline). `idOnly` stays a forward declaration.
+
+An **inline reference** resolves `ref.typeName` to a declared **Reference Type**
+and projects the referent through it – a nested `SearchDocument`, or an array
+for an `array` reference. Roles decide whether the nesting surfaces, so the same
+construct serves two jobs (see
+[ADR 11](../../docs/decisions/0011-decouple-rdf-depth-from-the-api-surface.md)):
+
+- a **reading device** declares no role, so it is an internal field: projected
+  so a later `derive` can select and flatten a value a `path` cannot address (a
+  qualified hop), then pruned before the writer – nothing nested reaches the
+  engine or the API;
+- an **API device** declares `output`, deliberately surfacing the nested
+  Reference Type.
+
+So RDF depth and API shape stay independent: inline as deep as the source
+demands, expose exactly the flat fields you want. Framing follows the inline
+reference graph to the depth the schema declares (`Dataset → Subset →
+Measurement` is two hops), and `searchSchema` rejects inline cycles – the one
+way that depth could be unbounded – so it stays a bounded property of the
+declaration.
 
 A reference resolves its label from a **label source**: `labelSource` names
 the `SearchType` whose collection holds the referenced entities. The named
@@ -225,8 +258,9 @@ 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
+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.
 

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, isInlineReference, referenceFields, referenceTypeNamed, inlineFramingDepth, 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,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,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, isInlineReference, referenceFields, referenceTypeNamed, inlineFramingDepth, 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

@@ -1,5 +1,5 @@
 import type { SearchQuery } from './query.js';
-import type { SearchSchema, SearchType } from './schema.js';
+import type { RootType, RootTypeOf, 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.
@@ -34,7 +34,7 @@ export interface SearchEngine<Types extends readonly SearchType[] = readonly Sea
     /** 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>>>;
+    search<T extends RootTypeOf<Types>>(searchType: T, query: SearchQuery): Promise<SearchResult<FacetFieldsOf<T>, OutputFieldsOf<T>>>;
     /**
      * The batch entry point: answer several facet-only queries against one type
      * in a single engine round-trip (where the engine supports one, e.g.
@@ -52,7 +52,7 @@ export interface SearchEngine<Types extends readonly SearchType[] = readonly Sea
      * transport itself). The port contract holds for every query in the batch;
      * an empty `queries` resolves to `[]` without touching the engine.
      */
-    searchFacets<T extends Types[number]>(searchType: T, queries: readonly SearchQuery[]): Promise<readonly FacetsOutcome<FacetFieldsOf<T>>[]>;
+    searchFacets<T extends RootTypeOf<Types>>(searchType: T, queries: readonly SearchQuery[]): Promise<readonly FacetsOutcome<FacetFieldsOf<T>>[]>;
 }
 /**
  * One query’s outcome in a {@link SearchEngine.searchFacets} batch – its
@@ -84,7 +84,7 @@ export type FacetMap<FacetField extends string = string> = Readonly<Partial<Reco
  * `: SearchType` annotation degrades to `string` (its field names are not
  * statically known).
  */
-export type FacetFieldsOf<Type extends SearchType> = SearchType extends Type ? string : Extract<Type['fields'][number], {
+export type FacetFieldsOf<Type extends SearchType> = RootType extends Type ? string : Extract<Type['fields'][number], {
     readonly facetable: true;
 }>['name'];
 /**
@@ -92,7 +92,7 @@ export type FacetFieldsOf<Type extends SearchType> = SearchType extends Type ? s
  * can hold. Like {@link FacetFieldsOf}, degrades to `string` for a widened
  * declaration.
  */
-export type OutputFieldsOf<Type extends SearchType> = SearchType extends Type ? string : Extract<Type['fields'][number], {
+export type OutputFieldsOf<Type extends SearchType> = RootType extends Type ? string : Extract<Type['fields'][number], {
     readonly output: true;
 }>['name'];
 /**

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EACV,QAAQ,EACR,UAAU,EACV,YAAY,EACZ,UAAU,EACX,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,YAAY,CAC3B,KAAK,SAAS,SAAS,UAAU,EAAE,GAAG,SAAS,UAAU,EAAE;IAE3D;uDACmD;IACnD,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IACrC,MAAM,CAAC,CAAC,SAAS,UAAU,CAAC,KAAK,CAAC,EAChC,UAAU,EAAE,CAAC,EACb,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,CAAC,SAAS,UAAU,CAAC,KAAK,CAAC,EACtC,UAAU,EAAE,CAAC,EACb,OAAO,EAAE,SAAS,WAAW,EAAE,GAC9B,OAAO,CAAC,SAAS,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;CACxD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,CAAC,UAAU,SAAS,MAAM,GAAG,MAAM,IACxD;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAA;CAAE,GACzC;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAEhC,+EAA+E;AAC/E,MAAM,WAAW,YAAY,CAC3B,UAAU,SAAS,MAAM,GAAG,MAAM,EAClC,WAAW,SAAS,MAAM,GAAG,MAAM;IAEnC,QAAQ,CAAC,IAAI,EAAE,SAAS,SAAS,CAAC,WAAW,CAAC,EAAE,CAAC;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;CACvC;AAED;;;GAGG;AACH,MAAM,MAAM,QAAQ,CAAC,UAAU,SAAS,MAAM,GAAG,MAAM,IAAI,QAAQ,CACjE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,WAAW,EAAE,CAAC,CAAC,CACpD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,CAAC,IAAI,SAAS,UAAU,IAAI,QAAQ,SAAS,IAAI,GACtE,MAAM,GACN,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE;IAAE,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;CAAE,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E;;;;GAIG;AACH,MAAM,MAAM,cAAc,CAAC,IAAI,SAAS,UAAU,IAAI,QAAQ,SAAS,IAAI,GACvE,MAAM,GACN,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;CAAE,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvE;;;;;;GAMG;AACH,MAAM,WAAW,SAAS,CAAC,WAAW,SAAS,MAAM,GAAG,MAAM;IAC5D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC,WAAW,CAAC,CAAC;CAChD;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,CAAC,WAAW,SAAS,MAAM,GAAG,MAAM,IAAI,QAAQ,CACxE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAC1C,CAAC;AAEF,6BAA6B;AAC7B,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,MAAM,GACN,OAAO,GACP,SAAS,MAAM,EAAE,GACjB,cAAc,GACd,SAAS,GACT,SAAS,SAAS,EAAE,CAAC;AAEzB;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB"}

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

@@ -27,15 +27,21 @@ export interface 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
- * 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.
+ * JSON-LD node. Each root subject’s own triples plus the nodes it references –
+ * to `depth` hops (e.g. nested publisher/distribution resources at one hop, an
+ * inline reference’s referents deeper) – 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.
+ *
+ * `depth` is the number of reference hops to embed; it defaults to one (the
+ * long-standing single-hop embed) and comes from the schema for a type with
+ * inline references (`inlineFramingDepth`). Bounded per batch, so the O(N²)
+ * framing cost applies to a batch of roots, not the graph (ADR 12).
  *
  * 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>;
+export declare function frameSubjects(index: SubjectIndex, roots: readonly string[], depth?: number): 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;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"}
+{"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;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAuB,aAAa,CAClC,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,KAAK,SAAI,GACR,aAAa,CAAC,UAAU,CAAC,CAqB3B"}

package/dist/frame-by-type.js

@@ -34,25 +34,26 @@ export function buildSubjectIndex(quads) {
 }
 /**
  * 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.
+ * JSON-LD node. Each root subject’s own triples plus the nodes it references –
+ * to `depth` hops (e.g. nested publisher/distribution resources at one hop, an
+ * inline reference’s referents deeper) – 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.
+ *
+ * `depth` is the number of reference hops to embed; it defaults to one (the
+ * long-standing single-hop embed) and comes from the schema for a type with
+ * inline references (`inlineFramingDepth`). Bounded per batch, so the O(N²)
+ * framing cost applies to a batch of roots, not the graph (ADR 12).
  *
  * 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) {
+export async function* frameSubjects(index, roots, depth = 1) {
     const { bySubject } = index;
     for (const rootIri of roots) {
-        const owned = bySubject.get(rootIri) ?? [];
-        const referenced = owned
-            .filter((quad) => quad.object.termType === 'NamedNode' ||
-            quad.object.termType === 'BlankNode')
-            .flatMap((quad) => bySubject.get(quad.object.value) ?? []);
-        const subgraph = [...owned, ...referenced];
+        const subgraph = collectSubgraph(bySubject, rootIri, depth);
         const expanded = await jsonld.fromRDF(subgraph);
         // 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
@@ -67,3 +68,36 @@ export async function* frameSubjects(index, roots) {
         }
     }
 }
+/**
+ * Collect a root subject’s triples plus those of every subject it references
+ * within `depth` hops, breadth-first. Each subject is visited once (so a
+ * reference cycle in the data terminates and no subject’s triples are
+ * duplicated); `jsonld.frame` embeds whatever the subgraph reaches. Bounded by
+ * `depth`, so only the reachable subgraph of one root is materialized at a time.
+ */
+function collectSubgraph(bySubject, rootIri, depth) {
+    const collected = [];
+    const visited = new Set();
+    let frontier = [rootIri];
+    for (let hop = 0; hop <= depth; hop++) {
+        const next = [];
+        for (const subject of frontier) {
+            if (visited.has(subject)) {
+                continue;
+            }
+            visited.add(subject);
+            const owned = bySubject.get(subject) ?? [];
+            collected.push(...owned);
+            if (hop < depth) {
+                for (const quad of owned) {
+                    if (quad.object.termType === 'NamedNode' ||
+                        quad.object.termType === 'BlankNode') {
+                        next.push(quad.object.value);
+                    }
+                }
+            }
+        }
+        frontier = next;
+    }
+    return collected;
+}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-export { projectRoots, irisOf, literalsOf, firstLiteralOf } 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 { FieldKind, SearchField, SearchFieldBase, TextField, KeywordField, ReferenceField, NumericField, BooleanField, SearchType, SearchTypeBase, RootType, ReferenceType, RootTypeOf, SearchTypeIssue, SearchSchema, FacetRange, } from './schema.js';
 export type { SearchQuery, Filter, Sort } from './query.js';
 export type { SearchEngine, SearchResult, SearchHit, ResultDocument, SearchValue, LocalizedValue, Reference, FacetBucket, FacetMap, FacetsOutcome, FacetFieldsOf, OutputFieldsOf, } from './engine.js';
 export type { FramedNode } from './frame-by-type.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,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"}
+{"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,cAAc,EACd,QAAQ,EACR,aAAa,EACb,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 { 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

@@ -1,6 +1,6 @@
 import type { Quad } from '@rdfjs/types';
 import { type FramedNode } from './frame-by-type.js';
-import { type SearchSchema, type SearchType } from './schema.js';
+import { type RootType, type SearchSchema, type SearchType } from './schema.js';
 /** A flat search document. `id` is the engine document key. */
 export type SearchDocument = {
     id: string;
@@ -8,12 +8,18 @@ export type 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
+ * 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. Pruning ({@link pruneInternalFields})
+ * recurses into the referents of surfaced inline references, so that invariant
+ * holds at every depth, not just the root. 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;
+export declare function projectDocument(node: FramedNode, searchType: SearchType, schema?: SearchSchema): SearchDocument;
 /**
  * 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)
@@ -27,8 +33,5 @@ export declare function projectDocument(node: FramedNode, searchType: SearchType
  * 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[];
+export declare function projectRoots(quads: Iterable<Quad>, roots: readonly string[], schema: SearchSchema, searchType: RootType): AsyncIterable<SearchDocument>;
 //# 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;;;;;;;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"}
+{"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,EAWL,KAAK,QAAQ,EAEb,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;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,UAAU,EACtB,MAAM,CAAC,EAAE,YAAY,GACpB,cAAc,CAIhB;AAiED;;;;;;;;;;;;GAYG;AACH,wBAAuB,YAAY,CACjC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,EACrB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,QAAQ,GACnB,aAAa,CAAC,cAAc,CAAC,CAW/B"}

package/dist/project.js

@@ -1,22 +1,73 @@
 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, inlineFramingDepth, isInternalField, isInlineReference, isoToUnixSeconds, physicalFields, referenceTypeNamed, } 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
+ * 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. Pruning ({@link pruneInternalFields})
+ * recurses into the referents of surfaced inline references, so that invariant
+ * holds at every depth, not just the root. 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) {
+export function projectDocument(node, searchType, schema) {
+    const document = projectFields(node, searchType, schema);
+    pruneInternalFields(document, searchType, schema);
+    return document;
+}
+/**
+ * Prune every internal field from a fully projected document, in place. Runs
+ * only after all projection – so every derive that might read an internal
+ * field, at any depth, has already run – which makes this single post-order
+ * pass safe. A no-role inline reference is itself internal, so it is deleted
+ * whole here; a surfaced (`output`) inline reference survives, but its own
+ * internal helper fields are pruned from the nested document. That keeps the
+ * *a field without a role reaches neither the engine nor the API* invariant
+ * true at every depth of the reference graph, not just at the root.
+ */
+function pruneInternalFields(document, searchType, schema) {
+    for (const field of searchType.fields) {
+        if (isInternalField(field)) {
+            delete document[field.name];
+            continue;
+        }
+        // A surfaced inline reference nests its referent(s) as SearchDocument(s);
+        // prune those too, by their reference type.
+        if (schema === undefined || field.kind !== 'reference') {
+            continue;
+        }
+        const ref = field.ref;
+        if (ref?.strategy !== 'inline') {
+            continue;
+        }
+        const referenceType = referenceTypeNamed(schema, ref.typeName);
+        const nested = document[field.name];
+        if (referenceType === undefined || nested === undefined) {
+            continue;
+        }
+        for (const referent of Array.isArray(nested) ? nested : [nested]) {
+            pruneInternalFields(referent, referenceType, schema);
+        }
+    }
+}
+/** Apply every field of `searchType` to a fresh document, without pruning – the
+ *  shared core of {@link projectDocument} and inline-referent projection.
+ *  Pruning is deferred to a single recursive pass ({@link pruneInternalFields})
+ *  once the whole nested structure is projected, so a derive at any depth can
+ *  still read an internal field before it is removed. */
+function projectFields(node, searchType, schema) {
     const id = node['@id'];
     if (typeof id !== 'string') {
-        throw new Error(`Cannot project a ${searchType.class} node without an @id: every search document needs a stable key, and an empty one would collide with other keyless nodes.`);
+        throw new Error(`Cannot project a “${searchType.name}” node without an @id: every search document needs a stable key, and an empty one would collide with other keyless nodes.`);
     }
     const document = { id };
     for (const field of searchType.fields) {
-        applyField(document, node, field);
+        applyField(document, node, field, schema);
     }
     return document;
 }
@@ -40,13 +91,14 @@ export async function* projectRoots(quads, roots, schema, searchType) {
     // 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);
+    const depth = inlineFramingDepth(schema, searchType);
+    for await (const node of frameSubjects(index, [...new Set(roots)], depth)) {
+        yield projectDocument(node, searchType, schema);
     }
 }
-function applyField(document, node, field) {
+function applyField(document, node, field, schema) {
     if (field.derive !== undefined) {
-        const value = field.derive(node, document);
+        const value = field.derive(document);
         if (value !== undefined) {
             document[field.name] = value;
         }
@@ -57,6 +109,16 @@ function applyField(document, node, field) {
         // Neither path nor derive: populated outside the projection, if at all.
         return;
     }
+    if (isInlineReference(field)) {
+        // An inline reference is a nested structure, not a bare IRI: it can only be
+        // projected with the schema that declares its reference type. Without one,
+        // project nothing rather than fall through and emit the referent IRIs under
+        // the field name (the wrong shape).
+        if (schema !== undefined) {
+            applyInlineReference(document, node, path, field, schema);
+        }
+        return;
+    }
     switch (field.kind) {
         case 'text':
             return applyText(document, langValuesOf(node, path), field);
@@ -141,20 +203,50 @@ function applyFacet(document, raw, field) {
         setArray(document, physicalFields(field).search[0], dedupe(values.map((value) => fold(value))));
     }
 }
+/**
+ * Project an inline reference: the referent node(s) embedded under `path` are
+ * each projected through the reference’s {@link ReferenceType} (its fields’
+ * paths relative to the referent node) and attached under the field’s name – a
+ * nested {@link SearchDocument} for a single reference, an array for an
+ * `array` one. The referent is projected in full – internal fields included –
+ * so the declaring type’s (or the reference type’s own) derives can read them;
+ * {@link pruneInternalFields} then removes the internal fields from a *surfaced*
+ * referent and deletes an internal inline reference whole. Recurses through
+ * `schema`, so an inline reference may itself carry further inline references to
+ * the schema’s declared depth. The referent type is guaranteed declared by
+ * {@link searchSchema}.
+ */
+function applyInlineReference(document, node, path, field, schema) {
+    // Resolves for a schema that declares the referent (always so for the schema a
+    // type is projected through); a type framed against a foreign schema that
+    // omits it simply contributes no nesting.
+    const referenceType = referenceTypeNamed(schema, field.ref.typeName);
+    if (referenceType === undefined) {
+        return;
+    }
+    const referents = valuesOf(node, path)
+        .filter(isObject)
+        .filter((referent) => typeof referent['@id'] === 'string')
+        .map((referent) => projectFields(referent, referenceType, schema));
+    if (referents.length === 0) {
+        return;
+    }
+    document[field.name] = field.array === true ? referents : referents[0];
+}
 function langValuesOf(node, path) {
     return valuesOf(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. */
@@ -191,26 +194,60 @@ export interface FacetRange {
     readonly min?: number;
     readonly max?: number;
 }
-/**
- * One root type’s complete search declaration: its logical API `name`, the
- * `class` IRI its documents are instances of (the RDF class), and the queryable
- * `fields` (including {@link SearchField.derive derived} ones). A SHACL
- * generator can emit one per NodeShape (`name`←`sh:name`/local name,
- * `class`←`sh:targetClass`, `fields`←its property shapes), but that is a source,
- * not a requirement.
- */
-export interface SearchType {
+/** The declaration members every {@link SearchType} shares. */
+export interface SearchTypeBase {
     /** Logical API name (PascalCase, e.g. `Dataset`) – names the type in the API
      *  surfaces (GraphQL type names, a REST path), the way each field’s
      *  {@link SearchField.name} names that field. Deliberately declared rather
      *  than derived from the `class` IRI, so re-modelling the vocabulary cannot
      *  silently rename the public contract. */
     readonly name: string;
+    readonly fields: readonly SearchField[];
+}
+/**
+ * A **Root Type**: a {@link SearchType} that is indexed. It declares a `class`,
+ * roots are selected for it, a Writer owns a collection for it, and the
+ * {@link SearchSchema} is keyed by it. A SHACL generator can emit one per
+ * NodeShape (`name`←`sh:name`/local name, `class`←`sh:targetClass`,
+ * `fields`←its property shapes), but that is a source, not a requirement.
+ */
+export interface RootType extends SearchTypeBase {
     /** The RDF class IRI its documents are instances of (`sh:targetClass`); the
-     *  key a {@link SearchSchema} maps this type under. */
+     *  key a {@link SearchSchema} maps this type under. Its presence is what makes
+     *  a type a Root Type – and so what gives it a collection. */
     readonly class: string;
-    readonly fields: readonly SearchField[];
 }
+/**
+ * A **Reference Type**: a {@link SearchType} reached only through an
+ * {@link ReferenceField.ref inline reference}. It declares **no `class`** –
+ * never selected, never framed by type, never indexed; its identity is its
+ * `name`, and its type comes from the edge that points at it, not from the node.
+ * The absence is load-bearing, not stylistic: a `class` would put it in the
+ * {@link SearchSchema} map and silently earn it a collection nobody asked for.
+ * The shape an inline reference carries – see
+ * [ADR 11](../../docs/decisions/0011-decouple-rdf-depth-from-the-api-surface.md).
+ */
+export interface ReferenceType extends SearchTypeBase {
+    /** A Reference Type declares no class; declaring one makes it a
+     *  {@link RootType}. Typed as `never` so the two shapes discriminate the way
+     *  {@link SearchField} discriminates by `kind`: an indexed Reference Type
+     *  fails to compile, not at run time. */
+    readonly class?: never;
+}
+/**
+ * One type’s complete search declaration: its logical API `name`, the queryable
+ * `fields` (including {@link SearchField.derive derived} ones), and – for a
+ * {@link RootType} – the RDF `class` its documents are instances of. Either a
+ * Root Type or a {@link ReferenceType}; the absence of a `class` tells them
+ * apart.
+ */
+export type SearchType = RootType | ReferenceType;
+/** The Root Types among a declared tuple – the ones a {@link SearchSchema}
+ *  keys and a Writer opens a collection for. Reference Types are excluded, so
+ *  no consumer that iterates `schema.values()` ever meets one. */
+export type RootTypeOf<Types extends readonly SearchType[]> = Extract<Types[number], {
+    readonly class: string;
+}>;
 /**
  * Declare a {@link SearchType}, capturing it as a literal: the `const` type
  * parameter preserves the field names and capability flags that the type-level
@@ -221,31 +258,67 @@ export interface SearchType {
  */
 export declare function defineSearchType<const Type extends SearchType>(searchType: Type): Type;
 /**
- * The complete search declaration of a deployment: every root {@link SearchType},
- * keyed by its `class` IRI. Build one with {@link searchSchema}, which captures
- * the declared types as a literal tuple (`Types`), so schema-bound consumers
- * (the engine port) can type their per-type behaviour off it. A plain
+ * The complete search declaration of a deployment: every {@link RootType},
+ * keyed by its `class` IRI, plus the {@link ReferenceType}s an inline reference
+ * resolves against. Build one with {@link searchSchema}, which captures the
+ * declared types as a literal tuple (`Types`), so schema-bound consumers (the
+ * engine port) can type their per-type behaviour off it. A plain
  * `: SearchSchema` annotation widens gracefully to `SearchType`.
+ *
+ * `values()` yields only Root Types – Reference Types are held apart in a name
+ * index ({@link referenceTypeNamed}), so a Writer that opens one collection per
+ * `values()` entry can never open one for a Reference Type.
  */
 /** Brand for {@link SearchSchema}: type-only, no runtime existence. Makes the
  *  schema NOMINAL – a hand-built `Map` is not assignable, so `searchSchema()`
  *  (which validates) is the only way to obtain one and downstream consumers
  *  need no defensive re-validation. */
 export declare const validSearchSchema: unique symbol;
-export interface SearchSchema<Types extends readonly SearchType[] = readonly SearchType[]> extends ReadonlyMap<string, Types[number]> {
+export interface SearchSchema<Types extends readonly SearchType[] = readonly SearchType[]> extends ReadonlyMap<string, RootTypeOf<Types>> {
     readonly [validSearchSchema]: true;
 }
 /**
- * Build a {@link SearchSchema} from root-type declarations, keyed by `class`.
+ * Build a {@link SearchSchema} from type declarations. Its arguments are
+ * **partitioned**: {@link RootType}s (those declaring a `class`) key the map –
+ * so a Writer opens exactly one collection per Root Type – and
+ * {@link ReferenceType}s (no `class`) go into a name index that an inline
+ * `ref.typeName` resolves against ({@link referenceTypeNamed}).
  *
  * Every declaration is validated ({@link assertValidSearchType}) – the
  * declaration-time counterpart of the port’s `assertValidQuery` – and the
- * schema-wide invariants are enforced: no two types may share a `class` IRI
- * (they would silently overwrite each other in the map) or a `name` (names
- * key the API surfaces). Throws on the first invalid declaration, so a bad
- * schema fails at startup, not per document at index time or per query.
+ * schema-wide invariants are enforced: no two Root Types may share a `class` IRI
+ * (they would silently overwrite each other in the map) and no two types may
+ * share a `name` (names key the API surfaces, across Root and Reference Types
+ * alike). Every inline reference must resolve to a declared Reference Type, and
+ * the inline reference graph must be acyclic – the only way its depth could be
+ * unbounded. Throws on the first invalid declaration, so a bad schema fails at
+ * startup, not per document at index time or per query.
  */
 export declare function searchSchema<const Types extends readonly SearchType[]>(...types: Types): SearchSchema<Types>;
+/**
+ * The {@link ReferenceType} an inline `ref.typeName` names, or `undefined` when
+ * the schema declares none by that name. The read side of the name index
+ * {@link searchSchema} partitions the Reference Types into – the projection
+ * resolves an inline reference’s referent shape through it.
+ */
+export declare function referenceTypeNamed(schema: SearchSchema, name: string): ReferenceType | undefined;
+/** Whether a field is an inline reference – a {@link ReferenceField} whose
+ *  `ref` carries its referent’s projected fields ({@link ReferenceType}). */
+export declare function isInlineReference(field: SearchField): field is ReferenceField & {
+    readonly ref: {
+        readonly typeName: string;
+        readonly strategy: 'inline';
+    };
+};
+/**
+ * The framing depth a Root Type needs: how many hops the inline reference graph
+ * reaches from it (`Dataset → Subset → Measurement` is two), floored at one so
+ * the existing single-hop embed for non-inline references is preserved. Depth is
+ * a property of the declaration, bounded because {@link searchSchema} rejects
+ * inline cycles – never a knob or a constant. Framing bounded per batch keeps
+ * memory bounded by the unit of work (ADR 12), not the graph.
+ */
+export declare function inlineFramingDepth(schema: SearchSchema, searchType: SearchType): number;
 /**
  * The text field a label source serves labels from – the ‘label’ convention
  * in one place: an `output` (something to reconstruct a label from),
@@ -301,7 +374,7 @@ export declare function validateSearchType(searchType: SearchType): readonly Sea
  * meet an index the deployment did not declare. Identity-based: the exact
  * declaration object must be in the schema, not a lookalike.
  */
-export declare function assertTypeInSchema(schema: SearchSchema, searchType: SearchType): void;
+export declare function assertTypeInSchema(schema: SearchSchema, searchType: RootType): void;
 /** Throw on a structurally invalid {@link SearchType} ({@link validateSearchType}),
  *  naming every issue. Called by {@link searchSchema} for each declaration. */
 export declare function assertValidSearchType(searchType: SearchType): void;
@@ -374,6 +447,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":"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"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/schema.js

@@ -28,32 +28,143 @@ export function defineSearchType(searchType) {
     return searchType;
 }
 /**
- * Build a {@link SearchSchema} from root-type declarations, keyed by `class`.
+ * The Reference Type name index each {@link SearchSchema} carries alongside its
+ * class-keyed root map, kept out of the map itself so no consumer iterating
+ * `values()` ever meets a Reference Type. Held in a `WeakMap` rather than a
+ * property, so the schema stays a plain branded `Map` and the index is read only
+ * through {@link referenceTypeNamed}.
+ */
+const referenceTypesBySchema = new WeakMap();
+/** Whether a declared type is a {@link RootType} (declares a `class`) rather
+ *  than a {@link ReferenceType}. */
+function isRootType(searchType) {
+    return searchType.class !== undefined;
+}
+/**
+ * Build a {@link SearchSchema} from type declarations. Its arguments are
+ * **partitioned**: {@link RootType}s (those declaring a `class`) key the map –
+ * so a Writer opens exactly one collection per Root Type – and
+ * {@link ReferenceType}s (no `class`) go into a name index that an inline
+ * `ref.typeName` resolves against ({@link referenceTypeNamed}).
  *
  * Every declaration is validated ({@link assertValidSearchType}) – the
  * declaration-time counterpart of the port’s `assertValidQuery` – and the
- * schema-wide invariants are enforced: no two types may share a `class` IRI
- * (they would silently overwrite each other in the map) or a `name` (names
- * key the API surfaces). Throws on the first invalid declaration, so a bad
- * schema fails at startup, not per document at index time or per query.
+ * schema-wide invariants are enforced: no two Root Types may share a `class` IRI
+ * (they would silently overwrite each other in the map) and no two types may
+ * share a `name` (names key the API surfaces, across Root and Reference Types
+ * alike). Every inline reference must resolve to a declared Reference Type, and
+ * the inline reference graph must be acyclic – the only way its depth could be
+ * unbounded. Throws on the first invalid declaration, so a bad schema fails at
+ * startup, not per document at index time or per query.
  */
 export function searchSchema(...types) {
     const typeIris = new Set();
     const names = new Set();
     for (const searchType of types) {
         assertValidSearchType(searchType);
-        if (typeIris.has(searchType.class)) {
-            throw new Error(`Duplicate search type IRI “${searchType.class}”; each SearchType must declare a distinct class.`);
+        if (isRootType(searchType)) {
+            if (typeIris.has(searchType.class)) {
+                throw new Error(`Duplicate search type IRI “${searchType.class}”; each Root Type must declare a distinct class.`);
+            }
+            typeIris.add(searchType.class);
         }
         if (names.has(searchType.name)) {
             throw new Error(`Duplicate search type name “${searchType.name}”; each SearchType must declare a distinct name.`);
         }
-        typeIris.add(searchType.class);
         names.add(searchType.name);
     }
+    const referenceTypes = new Map(types
+        .filter((searchType) => !isRootType(searchType))
+        .map((searchType) => [searchType.name, searchType]));
+    assertResolvableInlineReferences(types, referenceTypes);
     assertResolvableLabelSources(types);
     // The one blessed cast: only this validated constructor mints the brand.
-    return new Map(types.map((searchType) => [searchType.class, searchType]));
+    const schema = new Map(types
+        .filter(isRootType)
+        .map((searchType) => [searchType.class, searchType]));
+    referenceTypesBySchema.set(schema, referenceTypes);
+    return schema;
+}
+/**
+ * The {@link ReferenceType} an inline `ref.typeName` names, or `undefined` when
+ * the schema declares none by that name. The read side of the name index
+ * {@link searchSchema} partitions the Reference Types into – the projection
+ * resolves an inline reference’s referent shape through it.
+ */
+export function referenceTypeNamed(schema, name) {
+    return referenceTypesBySchema.get(schema)?.get(name);
+}
+/** Whether a field is an inline reference – a {@link ReferenceField} whose
+ *  `ref` carries its referent’s projected fields ({@link ReferenceType}). */
+export function isInlineReference(field) {
+    return field.kind === 'reference' && field.ref?.strategy === 'inline';
+}
+/**
+ * The framing depth a Root Type needs: how many hops the inline reference graph
+ * reaches from it (`Dataset → Subset → Measurement` is two), floored at one so
+ * the existing single-hop embed for non-inline references is preserved. Depth is
+ * a property of the declaration, bounded because {@link searchSchema} rejects
+ * inline cycles – never a knob or a constant. Framing bounded per batch keeps
+ * memory bounded by the unit of work (ADR 12), not the graph.
+ */
+export function inlineFramingDepth(schema, searchType) {
+    return Math.max(1, inlineChainLength(schema, searchType));
+}
+/** The longest inline reference chain reachable from `searchType`. The recursion
+ *  terminates because {@link searchSchema} rejects inline cycles; a reference the
+ *  given schema does not declare (e.g. a type framed against another schema)
+ *  contributes no depth. */
+function inlineChainLength(schema, searchType) {
+    let longest = 0;
+    for (const field of searchType.fields) {
+        if (!isInlineReference(field)) {
+            continue;
+        }
+        const referent = referenceTypeNamed(schema, field.ref.typeName);
+        if (referent === undefined) {
+            continue;
+        }
+        longest = Math.max(longest, 1 + inlineChainLength(schema, referent));
+    }
+    return longest;
+}
+/**
+ * Every inline `ref.typeName` must resolve to a **declared Reference Type**, and
+ * the inline reference graph must be acyclic. Unlike a `labelOnly` reference –
+ * whose `typeName` is just an API name – an inline reference carries its
+ * referent’s fields, so it must know their shape, and an inline cycle is the one
+ * way framing depth could be unbounded. Checked schema-wide, because a single
+ * declaration cannot see its siblings.
+ */
+function assertResolvableInlineReferences(types, referenceTypes) {
+    for (const searchType of types) {
+        for (const field of searchType.fields) {
+            if (!isInlineReference(field)) {
+                continue;
+            }
+            if (!referenceTypes.has(field.ref.typeName)) {
+                throw new Error(`Inline reference “${searchType.name}.${field.name}” names “${field.ref.typeName}”, which is not a declared reference type; declare a reference type (a SearchType with no class) with that name.`);
+            }
+        }
+    }
+    for (const referenceType of referenceTypes.values()) {
+        assertNoInlineCycle(referenceType, referenceTypes, new Set());
+    }
+}
+function assertNoInlineCycle(referenceType, referenceTypes, onPath) {
+    if (onPath.has(referenceType.name)) {
+        throw new Error(`Inline reference cycle through reference type “${referenceType.name}”; an inline reference graph must be acyclic, so its framing depth stays bounded.`);
+    }
+    const extended = new Set([...onPath, referenceType.name]);
+    for (const field of referenceType.fields) {
+        if (!isInlineReference(field)) {
+            continue;
+        }
+        // Resolvability is validated before any cycle check, so every inline
+        // `typeName` here names a declared reference type.
+        const referent = referenceTypes.get(field.ref.typeName);
+        assertNoInlineCycle(referent, referenceTypes, extended);
+    }
 }
 /**
  * The text field a label source serves labels from – the ‘label’ convention
@@ -317,6 +428,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/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAahD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,YAAY,GACzB,IAAI,CAsJN"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAShD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,YAAY,GACzB,IAAI,CAsJN"}

package/dist/testing.js

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { filterOperatorFor, } from './query.js';
-import { facetableFields, filterableFields, } from './schema.js';
+import { facetableFields, filterableFields } from './schema.js';
 /**
  * The executable {@link SearchEngine} port contract (import from
  * `@lde/search/testing`): a vitest suite every engine adapter runs against a

package/package.json

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