feat!: la lecture quitte le contrat, un index se lit comme un document

e2e/bridge.ts

@@ -26,6 +26,24 @@ export interface BrokenInboxOutcome {
   readonly appeared: readonly string[];
 }
 
+/**
+ * What one anchored SPARQL SELECT answered — or how it failed.
+ *
+ * The three fields are kept apart deliberately. "Nothing came back" and "the call failed"
+ * are different answers, and a shape that folded them together would let a failure read as
+ * an empty index — the defect class this repository keeps finding. `raw` carries the answer
+ * BEFORE anything here decodes it, so a decoder that is wrong about the result's shape
+ * cannot pass its own blindness off as a query that returned nothing.
+ */
+export interface SelectOutcome {
+  /** The message the query rejected with, or `null` when it returned. */
+  readonly failed: string | null;
+  /** Whatever came back, rendered as JSON — the answer before any decoding of it. */
+  readonly raw: string;
+  /** The SELECT's bindings, decoded to plain `variable → value` rows. */
+  readonly rows: ReadonlyArray<Readonly<Record<string, string>>>;
+}
+
 /**
  * The acts this application can perform — and ONLY acts an application can perform.
  *
@@ -74,6 +92,15 @@ export interface IndexingBridge {
 
   /** What a document literally holds, straight off `readUnion` — the write-form probe. */
   readRaw(doc: string): Promise<UnionSubject[]>;
+  /**
+   * Run a SPARQL SELECT anchored on a document, through `docs.sparqlQuery`.
+   *
+   * An index is claimed to be an ORDINARY document, which means an ordinary query must
+   * reach it. Nothing in `src/` ever issues one — this layer composes SPARQL only to
+   * write — so this is the one act here that no code of this package performs, and it is
+   * on the bridge because the claim had never been measured against a broker.
+   */
+  select(anchor: string, query: string): Promise<SelectOutcome>;
   /** This identity's public documents. How an owner discovers a document it did not keep. */
   listPublicDocs(): Promise<string[]>;