From 2633e8d5e1c59779985fa4b0f146e91deb826bc5 Mon Sep 17 00:00:00 2001 From: David Snelling Date: Wed, 2 Sep 2026 09:10:44 -0700 Subject: [PATCH] docs(plugin): the planner door's hiddenIds contract is the answer, not the mechanism --- src/plugin.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/plugin.ts b/src/plugin.ts index fdad42f0..54d300bb 100644 --- a/src/plugin.ts +++ b/src/plugin.ts @@ -460,8 +460,10 @@ export interface MetadataIndexProvider { * @param params - The find params, already normalized by `find()` * (natural-language parsed, `connected` anchors resolved to canonical ids, * an empty `where` dropped). - * @param hiddenIds - Ids this read must not return; apply BEFORE paging so - * `limit` stays exact. + * @param hiddenIds - Ids this read must not return. The contract is the ANSWER, not the + * mechanism: a provider may subtract this set before paging, or derive the + * same exclusion from the params' visibility tiers itself — either way the + * page must equal the engine's own answer with none of these ids in it. * @param graphIndex - The active graph provider, for a `connected` plan. * @returns The page's ids plus the stage that emptied it, or `null`. */