docs: l'engagement de la couche d'indexation, et ses deux déclarations

Le dépôt gagne sa doctrine et ses contrats, dans le régime bidirectionnel. Il publie son engagement — ce qu'un consommateur peut attendre de l'indexation — et déclare ce qu'il consomme lui-même, du polyfill et de ng-e2e-helpers. Les deux déclarations sont écrites depuis les appels réels, pas depuis ce que la surface offre : un usage non déclaré est la faute du consommateur en cas de rupture, et une surface offerte mais non déclarée reste librement modifiable. Version 1.0.0, pas 0.1.0 : sous semver, 0.x ne promet rien du tout, donc le majeur ne porte son signal qu'à partir de 1. Ce dépôt étant sur main, c'est une version pleine et non une pré-version.
2026-08-17 10:10:23 +02:00
parent f4050b95c0
commit aeb8c7d157
9 changed files with 341 additions and 1 deletions
@@ -0,0 +1,42 @@
+---
+type: overview
+summary: An index is an ordinary public document that only ever grows — what this repo publishes to applications, and what it consumes from NextGraph
+triggers:
+  keywords: [index, indexing, curate, curation, deposit, depositor, entry, descriptor, reference, only-grows]
+  paths:
+    - "src/**"
+    - "test/**"
+    - "e2e/**"
+    - "README.md"
+vocabulary:
+  - term: index
+    gloss: an ordinary public document that holds one entry per indexed object, plus its own field declaration
+    not: [catalogue, registry, listing]
+  - term: deposit
+    gloss: a bare object reference left in an index document's inbox — open to anyone, and never an instruction
+    not: [message, submission, request]
+  - term: curate
+    gloss: the owner resolving the references deposited on its index and adding what it can
+    not: [process, ingest, sync]
+  - term: entry
+    gloss: what an index holds for one indexed object — its NURI and its value for the index's field
+    not: [row, record, item]
+---
+
+# indexing — an index built on top of NextGraph, and the boundaries around it
+
+NextGraph has no indexing concept and will not grow one, so this is a construction **above** it, in its own repository, and the dependency runs one way only: this repo depends on `@ng-eventually/polyfill`, and the polyfill must never learn anything about indexing.
+
+An index is an **ordinary document** in its creator's public store. What makes it an index is that an application references its NURI in its own source. Anyone may hand it a reference by depositing into its inbox; its owner resolves those references itself and adds what it finds. **An index only ever grows** — no removal was ever built, and none is planned.
+
+## Roles at the repository boundary
+
+This repo is a **provider** of `indexing-layer`, which the Festipod application consumes, and a **consumer** of two engagements published by `ng-eventually-js`: `polyfill-surface` and `ng-e2e-helpers`. Each pair lives in its own interface folder: the engagement is pulled and never hand-edited, our declaration beside it is ours to keep current.
+
+Frictions are the main path for telling a provider what we need. They go in our `usage_` leaf, the signal goes out of band, and the entry is pruned once the engagement absorbs it.
+
+## Read first
+
+- `indexing-layer/contract_indexing-layer` — what an application may rely on from `@ng-helpers/indexing`.
+- `polyfill-surface/usage_ng-helpers` — the exact polyfill entries this layer stands on, and what it had to build for want of them.
+- `ng-e2e-helpers/usage_ng-helpers` — what our end-to-end suite calls, and the peer-dependency constraint it must respect.