@volter/twin-algolia 0.1.0

package/src/algolia-capabilities.ts

@@ -0,0 +1,396 @@
+// Algolia capability manifest — the EXPECTED REAL-PRODUCT SURFACE (the target), authored
+// top-down from the real Algolia hosted-search API — grounded LIVE against the installed
+// `algoliasearch@4.27.0` npm package (fetched read-only via `npm pack`, then driven end-to-end
+// against a throwaway local Node http server BEFORE this handler/manifest was written — see
+// spec-sources.json for the full grounded-vs-doc-UNVERIFIED breakdown). This is the honest
+// denominator: most entries start as `todo` and coverage reads LOW until the twin truly reaches
+// 100% of the real API. `verify()` (required to count as `done`) is ground truth and drives the
+// KERNEL-BACKED handler on a FRESH temp root — never a spawned mock.
+//
+// v1 SLICE (honesty, per the build spec's S-sizing verdict — do NOT pad to M): index list/
+// delete/clear + record CRUD (add-auto-objectID/add-replace/get/partial/delete/batch) + a REAL
+// search engine (tokenize + Damerau-Levenshtein typo tolerance + filter/facetFilters evaluation +
+// exact facet-count aggregation + a faithful-subset ranking + customRanking tie-breaks) +
+// settings get/set + basic bidirectional synonym expansion + safety/state + connector are
+// modeled `done`. Query-suggestions, personalization, A/B testing, query rules, replicas,
+// insights, secured/HMAC API keys, geo search, dictionaries, advanced per-length typo tuning,
+// highlighting/snippeting, multi-index, and browse are left `todo` with vendor-shaped failure
+// (unmodeled route -> 404) — a deliberate v1 scope cut, not an oversight; see README `## Coverage`.
+//
+// THE SEARCH ENGINE IS A GENUINE STRONG DONE, NOT A STUB (the biggest structural difference from
+// this repo's generative twins, mirroring pinecone's query engine): tokenize + real Damerau-
+// Levenshtein typo matching + real filter/facetFilters evaluation + exact facet-count aggregation
+// + a faithful-subset ranking tie-break chain is deterministic, correct compute — not a
+// placeholder. Widening the ranking criteria and adding language processing are filed as todos.
+// See algolia-search.ts / algolia-filter.ts file headers + README.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { checkCapabilities, type CapabilityReport, type CapabilitySpec, verifyBoundary } from '@volter/world-tooling';
+import { handleAlgoliaTwinRequest, type AlgoliaResponse } from './algolia-twin.ts';
+import { checkAlgoliaConformance } from './algolia-conformance.ts';
+import { syncAlgoliaFromReal, type AlgoliaLikeClient } from './algolia-connector.ts';
+
+// (Algolia is an API-first vendor with no product UI worth mirroring — the Algolia dashboard is
+// a config/analytics console, not an agent navigation target (ui-scope.json) — so this pack
+// ships no mirror, and there are no UI capabilities.)
+
+// ── API verify: drive REAL requests against a fresh temp root, then assert exact values ───────
+type Step = { m: string; p: string; b?: unknown; host?: string; readOnly?: boolean };
+type Body = Record<string, any>;
+
+/** Run a sequence of real Algolia-twin requests against an isolated root; return all responses. */
+async function withRoot(steps: (h: (s: Step) => Promise<AlgoliaResponse>) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'algolia-cap-'));
+  const h = (s: Step) =>
+    handleAlgoliaTwinRequest({
+      method: s.m,
+      path: s.p,
+      body: s.b === undefined ? undefined : JSON.stringify(s.b),
+      root,
+      ...(s.host !== undefined ? { host: s.host } : {}),
+      ...(s.readOnly !== undefined ? { readOnly: s.readOnly } : {}),
+    });
+  try {
+    return await verifyBoundary('algolia.withRoot', () => steps(h));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+const ok = (r: AlgoliaResponse) => r.status >= 200 && r.status < 300;
+const field = (r: AlgoliaResponse, k: string) => (r.body as Body)?.[k];
+
+/** Add-or-replace one record via the direct PUT endpoint (the simplest ground path most `done`
+ *  verifies below build their fixtures with). */
+async function putRecord(h: (s: Step) => Promise<AlgoliaResponse>, index: string, objectID: string, fields: Body): Promise<Body> {
+  const r = await h({ m: 'PUT', p: `/1/indexes/${index}/${objectID}`, b: { ...fields, objectID } });
+  return r.body as Body;
+}
+
+const done = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier'], verify: CapabilitySpec['verify']): CapabilitySpec => ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier']): CapabilitySpec => ({ id, area, title, dimension, tier, expected: 'todo' });
+
+export const ALGOLIA_CAPABILITIES: CapabilitySpec[] = [
+  todo('algolia.search.ranking_criteria_coverage', 'search', "Fuller ranking: the remaining documented tie-break criteria and their weighting (geo, filters-as-criterion) on top of the typo/attribute/proximity/exact/custom chain this twin already computes", 'api', 'core'),
+  todo('algolia.search.language_processing', 'search', 'Language processing over the indexed text: stemming, plural-folding, CJK/Thai segmentation and language-aware normalization (tokenization is deterministic ASCII/Unicode word-boundary splitting today)', 'api', 'niche'),
+
+  // ── INDEXES ──────────────────────────────────────────────────────────────────────────────
+  done('algolia.indexes.list', 'indexes', 'GET /1/indexes lists every index that has ever received a write, incl. entries (record count)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'catalog', 'p1', { name: 'Widget' });
+      const r = await h({ m: 'GET', p: '/1/indexes' });
+      const items = field(r, 'items') as Body[];
+      const catalog = items.find((i) => i.name === 'catalog');
+      return ok(r) && !!catalog && catalog.entries === 1;
+    })),
+  done('algolia.indexes.delete', 'indexes', 'DELETE /1/indexes/:name removes the index AND every record in it', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'temp-index', 'p1', { name: 'X' });
+      const del = await h({ m: 'DELETE', p: '/1/indexes/temp-index' });
+      const list = await h({ m: 'GET', p: '/1/indexes' });
+      const gone = await h({ m: 'GET', p: '/1/indexes/temp-index/p1' });
+      return ok(del) && !(field(list, 'items') as Body[]).some((i) => i.name === 'temp-index') && gone.status === 404;
+    })),
+  done('algolia.indexes.clear', 'indexes', 'POST /1/indexes/:name/clear removes every record but the index itself survives', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'clearable', 'p1', { name: 'X' });
+      await putRecord(h, 'clearable', 'p2', { name: 'Y' });
+      const clear = await h({ m: 'POST', p: '/1/indexes/clearable/clear' });
+      const list = await h({ m: 'GET', p: '/1/indexes' });
+      const gone = await h({ m: 'GET', p: '/1/indexes/clearable/p1' });
+      return ok(clear) && (field(list, 'items') as Body[]).some((i) => i.name === 'clearable' && i.entries === 0) && gone.status === 404;
+    })),
+
+  // ── RECORDS ──────────────────────────────────────────────────────────────────────────────
+  done('algolia.records.add_auto_objectid', 'records', 'POST /1/indexes/:name (no objectID) mints a non-empty deterministic-per-call objectID; GET round-trips the stored fields', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/1/indexes/autogen', b: { name: 'Widget', price: 9 } });
+      const objectID = field(r, 'objectID') as string;
+      if (!ok(r) || typeof objectID !== 'string' || objectID.length === 0) return false;
+      const got = await h({ m: 'GET', p: `/1/indexes/autogen/${objectID}` });
+      return field(got, 'name') === 'Widget' && field(got, 'price') === 9;
+    })),
+  done('algolia.records.add_replace', 'records', 'PUT /1/indexes/:name/:objectID REPLACES the whole record (a stale field from the first write does not survive a replace)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'replace-idx', 'p1', { name: 'Old', stale: 'gone-after-replace' });
+      await putRecord(h, 'replace-idx', 'p1', { name: 'New' });
+      const got = await h({ m: 'GET', p: '/1/indexes/replace-idx/p1' });
+      return field(got, 'name') === 'New' && field(got, 'stale') === undefined;
+    })),
+  done('algolia.records.get', 'records', 'GET /1/indexes/:name/:objectID returns the exact stored fields', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'get-idx', 'p1', { name: 'Widget', tags: ['a', 'b'] });
+      const r = await h({ m: 'GET', p: '/1/indexes/get-idx/p1' });
+      return ok(r) && field(r, 'name') === 'Widget' && JSON.stringify(field(r, 'tags')) === JSON.stringify(['a', 'b']);
+    })),
+  done('algolia.records.get_unknown_404', 'records', 'GET an unknown objectID -> 404 {message,status} (⚠ message text doc-UNVERIFIED, modeled on the well-known convention)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'exists-idx', 'p1', { name: 'X' });
+      const r = await h({ m: 'GET', p: '/1/indexes/exists-idx/does-not-exist' });
+      return r.status === 404 && typeof field(r, 'message') === 'string' && field(r, 'status') === 404;
+    })),
+  done('algolia.records.partial_update', 'records', 'POST /1/indexes/:name/:objectID/partial MERGES fields (untouched fields survive); createIfNotExists=false on an unknown id -> 404 (⚠ merge semantics)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'partial-idx', 'p1', { name: 'Widget', price: 10 });
+      const patch = await h({ m: 'POST', p: '/1/indexes/partial-idx/p1/partial', b: { price: 20 } });
+      const got = await h({ m: 'GET', p: '/1/indexes/partial-idx/p1' });
+      const missing = await h({ m: 'POST', p: '/1/indexes/partial-idx/nope/partial?createIfNotExists=false', b: { price: 1 } });
+      return ok(patch) && field(got, 'price') === 20 && field(got, 'name') === 'Widget' && missing.status === 404;
+    })),
+  done('algolia.records.delete', 'records', 'DELETE /1/indexes/:name/:objectID removes it (idempotent — a second delete is still 200, not a fabricated 404)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'del-idx', 'p1', { name: 'X' });
+      const del = await h({ m: 'DELETE', p: '/1/indexes/del-idx/p1' });
+      const del2 = await h({ m: 'DELETE', p: '/1/indexes/del-idx/p1' });
+      const got = await h({ m: 'GET', p: '/1/indexes/del-idx/p1' });
+      return ok(del) && ok(del2) && got.status === 404;
+    })),
+  done('algolia.records.batch', 'records', 'POST /1/indexes/:name/batch runs HETEROGENEOUS actions (addObject/updateObject/partialUpdateObject/deleteObject) in one call, each taking effect (⚠ action grammar grounded LIVE against the real SDK)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'batch-idx', 'existing', { name: 'Old' });
+      const r = await h({
+        m: 'POST',
+        p: '/1/indexes/batch-idx/batch',
+        b: { requests: [
+          { action: 'addObject', body: { name: 'Auto' } },
+          { action: 'updateObject', body: { objectID: 'explicit', name: 'Explicit' } },
+          { action: 'partialUpdateObject', body: { objectID: 'existing', name: 'New' } },
+          { action: 'deleteObject', body: { objectID: 'explicit' } },
+        ] },
+      });
+      const objectIDs = field(r, 'objectIDs') as string[];
+      const explicitGone = await h({ m: 'GET', p: '/1/indexes/batch-idx/explicit' });
+      const existingUpdated = await h({ m: 'GET', p: '/1/indexes/batch-idx/existing' });
+      return ok(r) && objectIDs.length === 4 && explicitGone.status === 404 && field(existingUpdated, 'name') === 'New';
+    })),
+
+  // ── SEARCH (real tokenize + typo + filter + facet + ranking; the pack's signature strength) ─
+  done('algolia.search.basic_ranking', 'search', 'POST /1/indexes/:name/query matches records containing every query word and excludes non-matching records', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'basic-idx', 'a', { name: 'red widget' });
+      await putRecord(h, 'basic-idx', 'b', { name: 'blue gadget' });
+      const r = await h({ m: 'POST', p: '/1/indexes/basic-idx/query', b: { query: 'red widget' } });
+      const hits = field(r, 'hits') as Body[];
+      return ok(r) && field(r, 'nbHits') === 1 && hits[0]!.objectID === 'a';
+    })),
+  done('algolia.search.typo_tolerance', 'search', 'A 1-typo query matches ONLY the near-typo record, NOT an unrelated record — a return-all implementation reports the wrong nbHits', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'typo-idx', 'near', { name: 'widget' });
+      await putRecord(h, 'typo-idx', 'far', { name: 'gadget' }); // Damerau-Levenshtein('widgt','gadget') > 2, no match
+      const r = await h({ m: 'POST', p: '/1/indexes/typo-idx/query', b: { query: 'widgt' } });
+      const hits = field(r, 'hits') as Body[];
+      return ok(r) && field(r, 'nbHits') === 1 && hits[0]!.objectID === 'near';
+    })),
+  done('algolia.search.filters_numeric', 'filters', 'A numeric `filters` string EXCLUDES the textually-stronger match, changing which record wins hits[0] — a filter-ignoring implementation returns the wrong hits[0]', 'api', 'core', () =>
+    withRoot(async (h) => {
+      // 'near' is an EXACT text match (0 typos) but filtered OUT by price; 'far' matches via 1
+      // typo (weaker text match) but passes the filter — a filter-ignoring impl returns 'near'.
+      await putRecord(h, 'filternum-idx', 'near', { name: 'widget', price: 200 });
+      await putRecord(h, 'filternum-idx', 'far', { name: 'widgt', price: 50 });
+      const r = await h({ m: 'POST', p: '/1/indexes/filternum-idx/query', b: { query: 'widget', filters: 'price < 100' } });
+      const hits = field(r, 'hits') as Body[];
+      return ok(r) && hits.length === 1 && hits[0]!.objectID === 'far';
+    })),
+  done('algolia.search.facet_filters', 'facets', 'facetFilters (incl. an inner OR-array) selects only records with a matching facet value', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'facetfilt-idx', 'red', { name: 'widget', color: 'red' });
+      await putRecord(h, 'facetfilt-idx', 'blue', { name: 'widget', color: 'blue' });
+      await putRecord(h, 'facetfilt-idx', 'green', { name: 'widget', color: 'green' });
+      const single = await h({ m: 'POST', p: '/1/indexes/facetfilt-idx/query', b: { query: 'widget', facetFilters: ['color:red'] } });
+      const orGroup = await h({ m: 'POST', p: '/1/indexes/facetfilt-idx/query', b: { query: 'widget', facetFilters: [['color:red', 'color:blue']] } });
+      const ids = (r: AlgoliaResponse) => (field(r, 'hits') as Body[]).map((x) => x.objectID).sort();
+      return JSON.stringify(ids(single)) === JSON.stringify(['red']) && JSON.stringify(ids(orGroup)) === JSON.stringify(['blue', 'red']);
+    })),
+  done('algolia.search.facets_counts', 'facets', 'requesting `facets` returns EXACT counts per facet value over the matched+filtered hit set (not just a non-empty object)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'facetcount-idx', '1', { name: 'widget', color: 'red' });
+      await putRecord(h, 'facetcount-idx', '2', { name: 'widget', color: 'red' });
+      await putRecord(h, 'facetcount-idx', '3', { name: 'widget', color: 'blue' });
+      await h({ m: 'PUT', p: '/1/indexes/facetcount-idx/settings', b: { attributesForFaceting: ['color'] } });
+      const r = await h({ m: 'POST', p: '/1/indexes/facetcount-idx/query', b: { query: 'widget', facets: ['color'] } });
+      const facets = field(r, 'facets') as Body;
+      return ok(r) && facets.color.red === 2 && facets.color.blue === 1;
+    })),
+  done('algolia.search.attributes_to_retrieve', 'search', '`attributesToRetrieve` projects each hit to ONLY objectID + the requested fields; omitting it returns every field', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'attrret-idx', 'p1', { name: 'Widget', price: 10, description: 'a fine widget' });
+      const restricted = await h({ m: 'POST', p: '/1/indexes/attrret-idx/query', b: { query: 'widget', attributesToRetrieve: ['name'] } });
+      const full = await h({ m: 'POST', p: '/1/indexes/attrret-idx/query', b: { query: 'widget' } });
+      const rHit = (field(restricted, 'hits') as Body[])[0]!;
+      const fHit = (field(full, 'hits') as Body[])[0]!;
+      return rHit.name === 'Widget' && rHit.price === undefined && rHit.description === undefined && fHit.price === 10;
+    })),
+  done('algolia.search.pagination', 'pagination', 'page 0 and page 1 (hitsPerPage=1) return DIFFERENT single hits; nbPages reflects the real hit count', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'page-idx', 'a', { name: 'widget' });
+      await putRecord(h, 'page-idx', 'b', { name: 'widget' });
+      await putRecord(h, 'page-idx', 'c', { name: 'widget' });
+      const p0 = await h({ m: 'POST', p: '/1/indexes/page-idx/query', b: { query: 'widget', page: 0, hitsPerPage: 1 } });
+      const p1 = await h({ m: 'POST', p: '/1/indexes/page-idx/query', b: { query: 'widget', page: 1, hitsPerPage: 1 } });
+      const id0 = (field(p0, 'hits') as Body[])[0]!.objectID;
+      const id1 = (field(p1, 'hits') as Body[])[0]!.objectID;
+      return id0 !== id1 && field(p0, 'nbPages') === 3 && field(p0, 'nbHits') === 3;
+    })),
+  done('algolia.search.custom_ranking', 'search', 'customRanking flips the order of two TEXT-TIED records (same query relevance, differ only in the ranked numeric field) — an ignoring implementation returns them in the opposite/insertion order', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'customrank-idx', 'x', { name: 'widget', popularity: 1 });
+      await putRecord(h, 'customrank-idx', 'y', { name: 'widget', popularity: 9 });
+      await h({ m: 'PUT', p: '/1/indexes/customrank-idx/settings', b: { customRanking: ['desc(popularity)'] } });
+      const desc = await h({ m: 'POST', p: '/1/indexes/customrank-idx/query', b: { query: 'widget' } });
+      await h({ m: 'PUT', p: '/1/indexes/customrank-idx/settings', b: { customRanking: ['asc(popularity)'] } });
+      const asc = await h({ m: 'POST', p: '/1/indexes/customrank-idx/query', b: { query: 'widget' } });
+      const first = (r: AlgoliaResponse) => (field(r, 'hits') as Body[])[0]!.objectID;
+      return first(desc) === 'y' && first(asc) === 'x';
+    })),
+
+  // ── SETTINGS ─────────────────────────────────────────────────────────────────────────────
+  done('algolia.settings.get_set', 'settings', 'PUT /1/indexes/:name/settings MERGES onto existing settings (setting A does not erase a previously-set B); GET round-trips', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'settings-idx', 'p1', { name: 'x' });
+      await h({ m: 'PUT', p: '/1/indexes/settings-idx/settings', b: { searchableAttributes: ['name'] } });
+      await h({ m: 'PUT', p: '/1/indexes/settings-idx/settings', b: { customRanking: ['desc(popularity)'] } });
+      const r = await h({ m: 'GET', p: '/1/indexes/settings-idx/settings' });
+      return JSON.stringify(field(r, 'searchableAttributes')) === JSON.stringify(['name']) && JSON.stringify(field(r, 'customRanking')) === JSON.stringify(['desc(popularity)']);
+    })),
+  done('algolia.settings.searchable_attributes_affects_search', 'settings', 'Configuring searchableAttributes CHANGES the hit set for the identical query — data-coupling proof (a settings-ignoring implementation returns the same result either way)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'searchable-idx', 'p1', { title: 'other', body: 'widget' });
+      const before = await h({ m: 'POST', p: '/1/indexes/searchable-idx/query', b: { query: 'widget' } });
+      await h({ m: 'PUT', p: '/1/indexes/searchable-idx/settings', b: { searchableAttributes: ['title'] } });
+      const after = await h({ m: 'POST', p: '/1/indexes/searchable-idx/query', b: { query: 'widget' } });
+      return field(before, 'nbHits') === 1 && field(after, 'nbHits') === 0;
+    })),
+
+  // ── SYNONYMS ─────────────────────────────────────────────────────────────────────────────
+  done('algolia.synonyms.save_get', 'synonyms', 'POST /1/indexes/:name/synonyms/batch saves a synonym group; GET round-trips it (⚠ batch array-body grammar grounded LIVE against the real SDK)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'syn-idx', 'p1', { name: 'tv' });
+      const save = await h({ m: 'POST', p: '/1/indexes/syn-idx/synonyms/batch', b: [{ objectID: 'syn1', type: 'synonym', synonyms: ['tv', 'television'] }] });
+      const got = await h({ m: 'GET', p: '/1/indexes/syn-idx/synonyms/syn1' });
+      return ok(save) && JSON.stringify(field(got, 'synonyms')) === JSON.stringify(['tv', 'television']);
+    })),
+  done('algolia.synonyms.search_expansion', 'synonyms', 'A query matches ONLY via a configured synonym group; the SAME query on an index WITHOUT that synonym matches nothing — a control pair that kills both an empty-return AND a return-all implementation', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'synexp-idx', 'p1', { name: 'television' });
+      await h({ m: 'POST', p: '/1/indexes/synexp-idx/synonyms/batch', b: [{ objectID: 'syn1', type: 'synonym', synonyms: ['tv', 'television'] }] });
+      const withSynonym = await h({ m: 'POST', p: '/1/indexes/synexp-idx/query', b: { query: 'tv' } });
+
+      await putRecord(h, 'control-idx', 'p1', { name: 'television' }); // identical data, NO synonym configured
+      const control = await h({ m: 'POST', p: '/1/indexes/control-idx/query', b: { query: 'tv' } });
+
+      return field(withSynonym, 'nbHits') === 1 && field(control, 'nbHits') === 0;
+    })),
+
+  // ── AUTH / SAFETY / STATE ────────────────────────────────────────────────────────────────
+  done('algolia.auth.rejects_writes', 'auth', 'readOnly mode rejects a write (add record -> 405) but allows reads AND read-shaped POSTs (query)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await putRecord(h, 'ro-idx', 'p1', { name: 'x' });
+      const write = await h({ m: 'PUT', p: '/1/indexes/ro-idx/p2', readOnly: true, b: { name: 'blocked' } });
+      const readList = await h({ m: 'GET', p: '/1/indexes', readOnly: true });
+      const readQuery = await h({ m: 'POST', p: '/1/indexes/ro-idx/query', readOnly: true, b: { query: '' } });
+      return write.status === 405 && readList.status === 200 && readQuery.status === 200;
+    })),
+  done('algolia.unmodeled_route.404', 'safety', 'An unmodeled route returns Algolia\'s real error envelope (never a fabricated success)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/1/totally-unknown-resource' });
+      return r.status === 404 && typeof field(r, 'message') === 'string';
+    })),
+  done('algolia.state.kernel_persisted', 'state', 'State is kernel-folded — a record written in one call is visible, with correct values, in the next', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const created = await putRecord(h, 'persist-idx', 'persisted', { value: 42 });
+      // a dead twin returns {} — objectID must be a REAL non-empty string first, or the final
+      // comparison is vacuous.
+      if (typeof created.objectID !== 'string' || created.objectID.length === 0) return false;
+      const r = await h({ m: 'GET', p: '/1/indexes/persist-idx/persisted' });
+      return field(r, 'value') === 42;
+    })),
+
+  // ── CONFORMANCE / CONNECTOR ──────────────────────────────────────────────────────────────
+  done('algolia.conformance.snapshot', 'conformance', 'Conformance snapshot covers every resource type + the core write/search/settings/synonym endpoints', 'api', 'common', () => {
+    const report = checkAlgoliaConformance();
+    return report.ok && report.endpointsChecked >= 12 && report.resourceTypesChecked === 3;
+  }),
+  done('algolia.connector.sync.entrypoint', 'connector', 'syncAlgoliaFromReal folds indices + records into the twin, idempotent, read-through-handler', 'connector', 'core', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'algolia-conn-'));
+    try {
+      const client: AlgoliaLikeClient = {
+        listIndices: async () => ({ items: [{ name: 'real-index' }] }),
+        listRecords: async () => ({ records: [{ index: 'real-index', objectID: 'real-rec-1', fields: { name: 'Real' } }] }),
+      };
+      const first = await syncAlgoliaFromReal(client, { root, budgetOptions: { root } });
+      if (first.observed !== 2 || first.deltasAppended < 2) return false;
+      // a re-pull of identical state is a no-op (shadow-diff dedup) -> 0 deltas appended
+      const second = await syncAlgoliaFromReal(client, { root, budgetOptions: { root } });
+      if (second.deltasAppended !== 0) return false;
+      // the pulled data is now visible via the twin handler (real fold, not a count)
+      const list = await handleAlgoliaTwinRequest({ method: 'GET', path: '/1/indexes', root });
+      const got = await handleAlgoliaTwinRequest({ method: 'GET', path: '/1/indexes/real-index/real-rec-1', root });
+      return (list.body as Body).items.some((i: Body) => i.name === 'real-index') && (got.body as Body).name === 'Real';
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+  done('algolia.connector.empty_client', 'connector', 'syncAlgoliaFromReal with an empty client observes nothing', 'connector', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'algolia-conn-empty-'));
+    try {
+      const result = await syncAlgoliaFromReal({}, { root, budgetOptions: { root } });
+      return result.observed === 0 && result.deltasAppended === 0;
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+
+  // ── TODO: the rest of the Algolia v1 surface (honest denominator) ───────────────────────
+  todo('algolia.search.geo_search', 'search', 'aroundLatLng / insideBoundingBox / insidePolygon geo search', 'api', 'niche'),
+  todo('algolia.search.query_rules', 'search', 'Query Rules (condition -> consequence, e.g. pinning/boosting/filtering results for a matched query)', 'api', 'common'),
+  todo('algolia.search.optional_words', 'search', '`optionalWords` — words that may be dropped from the strict-AND match without excluding the record', 'api', 'common'),
+  todo('algolia.search.remove_words_if_no_results', 'search', '`removeWordsIfNoResults` progressive query-word relaxation when the strict match returns 0 hits', 'api', 'common'),
+  todo('algolia.search.advanced_typo_tuning', 'search', 'Per-word-length graduated typo tolerance (`minWordSizefor1Typo`/`minWordSizefor2Typos`) instead of this twin\'s uniform <=2', 'api', 'common'),
+  todo('algolia.search.distinct_dedup', 'search', '`distinct` — deduplicate hits sharing an attribute value, keeping only the top-ranked one per group', 'api', 'common'),
+  todo('algolia.search.highlighting', 'search', '`_highlightResult` — per-attribute matched-substring highlighting in each hit', 'api', 'common'),
+  todo('algolia.search.snippeting', 'search', '`_snippetResult` — a truncated, highlighted excerpt around the match', 'api', 'niche'),
+  todo('algolia.search.ranking_info', 'search', '`getRankingInfo` — per-hit exposed scoring breakdown (nbTypos/proximityDistance/etc) in the response', 'api', 'niche'),
+  todo('algolia.facets.disjunctive_facets', 'facets', 'Disjunctive facet counting (`disjunctiveFacets` — counts as if THIS facet\'s own filter were not applied)', 'api', 'common'),
+  todo('algolia.synonyms.one_way', 'synonyms', '`oneWaySynonym` — asymmetric synonym expansion (input -> synonyms, not the reverse)', 'api', 'common'),
+  todo('algolia.synonyms.placeholder', 'synonyms', '`placeholder` synonyms (token substitution, e.g. `<streetnumber>`)', 'api', 'niche'),
+  todo('algolia.synonyms.alt_correction', 'synonyms', '`altCorrection1`/`altCorrection2` typo-correction synonyms', 'api', 'niche'),
+  todo('algolia.synonyms.search_endpoint', 'synonyms', 'POST /1/indexes/:name/synonyms/search — paginated/query-filtered synonym search (today: only get-by-id)', 'api', 'niche'),
+  todo('algolia.records.delete_by_query', 'records', 'POST /1/indexes/:name/deleteByQuery — delete every record matching a filter/query in one call', 'api', 'common'),
+  todo('algolia.records.get_multiple', 'records', 'POST /1/indexes/*/objects — fetch several objectIDs across one or more indices in one call', 'api', 'common'),
+  todo('algolia.settings.replicas', 'settings', 'Index replicas (`replicas` setting) for pre-sorted/differently-ranked query variants', 'api', 'common'),
+  todo('algolia.settings.attributes_to_snippet', 'settings', '`attributesToSnippet` settings-level default (paired with search.snippeting)', 'api', 'niche'),
+  todo('algolia.facets.facet_value_search', 'facets', 'POST /1/indexes/:name/facets/:facetName/query — search WITHIN a facet\'s own values (facet-value autocomplete)', 'api', 'common'),
+  todo('algolia.facets.max_values_per_facet', 'facets', '`maxValuesPerFacet` cap on returned facet values per attribute', 'api', 'niche'),
+  todo('algolia.indexes.copy_move', 'indexes', 'POST /1/indexes/:name/operation — copy/move an entire index (incl. settings/synonyms/rules)', 'api', 'common'),
+  todo('algolia.indexes.wait_task', 'indexes', 'GET /1/indexes/:name/task/:taskID — poll a real async task to completion (today: taskID is a deterministic 0 stub)', 'api', 'common'),
+  todo('algolia.browse.all', 'browse', 'POST /1/indexes/:name/browse — full unranked export of every record in an index (page/cursor iteration)', 'api', 'core'),
+  todo('algolia.browse.cursor_pagination', 'browse', 'Real opaque `cursor` fidelity across successive browse calls', 'api', 'common'),
+  todo('algolia.multi_index.multiple_queries', 'multi_index', 'POST /1/indexes/*/queries — run several DIFFERENT-index queries in one round trip, incl. the `params` urlencoded-string request shape', 'api', 'common'),
+  todo('algolia.auth.api_keys_crud', 'auth', 'POST/GET/PUT/DELETE /1/keys — scoped API key management', 'api', 'common'),
+  todo('algolia.auth.secured_api_keys_generate', 'auth', 'HMAC-signed secured/virtual API keys (`generateSecuredApiKey`) for per-user filtered access', 'api', 'common'),
+  todo('algolia.search.query_suggestions', 'search', 'Query Suggestions index generation from search analytics', 'api', 'niche'),
+  todo('algolia.search.personalization', 'search', 'Personalization re-ranking from a user\'s click/conversion history', 'api', 'niche'),
+  todo('algolia.search.ab_testing', 'search', 'A/B test configuration + traffic split across two index variants', 'api', 'niche'),
+  todo('algolia.search.rules_save_batch', 'search', 'POST /1/indexes/:name/rules/batch — bulk Query Rules upsert', 'api', 'niche'),
+  todo('algolia.search.insights_events', 'search', 'POST /1/events — click/conversion/view event tracking (Insights API)', 'api', 'niche'),
+  todo('algolia.search.analytics_top_searches', 'search', 'GET /2/searches — top-searches / no-results analytics', 'api', 'niche'),
+  todo('algolia.search.dictionary_stopwords_plurals', 'search', 'Dictionary entries (stopwords/plurals/compounds) management', 'api', 'niche'),
+  todo('algolia.connector.push', 'connector', 'Push locally-created indices/records against the real API', 'connector', 'common'),
+  todo('algolia.connector.pull_synonyms', 'connector', 'Connector: pull synonyms from the real account', 'connector', 'common'),
+  todo('algolia.connector.fixtures_seed', 'connector', 'Seed indices/records from fixtures', 'connector', 'niche'),
+  todo('algolia.filters.parentheses', 'filters', 'Parenthesized `filters` precedence override (today: OR-of-AND-groups only, no parens)', 'api', 'common'),
+  todo('algolia.filters.tag_shorthand', 'filters', '`_tags`/`tag:` shorthand filter syntax', 'api', 'niche'),
+  todo('algolia.filters.geo', 'filters', 'Geo filters (`_geoloc` radius/bounding-box) inside the `filters` string', 'api', 'niche'),
+  todo('algolia.errors.wire_shape_confirmed', 'errors', 'Independently confirm the exact unknown-objectID/unknown-index error MESSAGE TEXT against a live account (currently doc-UNVERIFIED, modeled on the well-known convention — the live SDK pass confirmed the {message,status} SHAPE round-trips, not the exact wording)', 'api', 'common'),
+  todo('algolia.errors.rate_limiting', 'errors', '429 rate-limit error envelope + Retry-After semantics (twin never rate-limits)', 'api', 'niche'),
+];
+
+export const ALGOLIA_AREAS = [
+  'indexes', 'records', 'search', 'filters', 'facets', 'settings', 'synonyms', 'multi_index',
+  'browse', 'pagination', 'auth', 'errors', 'connector', 'conformance', 'safety', 'state',
+] as const;
+
+export async function algoliaCapabilities(): Promise<CapabilityReport> {
+  return checkCapabilities('algolia', ALGOLIA_CAPABILITIES);
+}

package/src/algolia-conformance.ts

@@ -0,0 +1,38 @@
+// Algolia conformance (dev-only; lazy-imported by the CLI, NEVER from index.ts/runtime — E2).
+// Checks the twin's endpoint/resource inventory against the modeled Algolia surface. Like
+// pinecone/replicate/fal, this is a self-referential snapshot check (against the twin's own
+// declared inventory), not a systematic per-resource spec-diff — see docs/contributing/conformance.md's "2 spec"
+// column note.
+import { algoliaTwinSnapshot, ALGOLIA_RESOURCE_TYPES } from './algolia-twin.ts';
+
+export type AlgoliaConformanceReport = {
+  ok: boolean;
+  endpointsChecked: number;
+  resourceTypesChecked: number;
+  violations: string[];
+};
+
+export function checkAlgoliaConformance(): AlgoliaConformanceReport {
+  const snapshot = algoliaTwinSnapshot();
+  const violations: string[] = [];
+  const stemFor: Record<string, string> = {
+    index: '/1/indexes',
+    record: '/1/indexes/:name/:objectID',
+    synonym: '/1/indexes/:name/synonyms',
+  };
+  for (const type of ALGOLIA_RESOURCE_TYPES) {
+    const stem = stemFor[type];
+    if (!stem || !snapshot.implementedEndpoints.some((e) => e.includes(stem))) {
+      violations.push(`resource type '${type}' has no implemented endpoint`);
+    }
+  }
+  if (!snapshot.implementedEndpoints.some((e) => e === 'POST /1/indexes/:name/query')) violations.push('missing search endpoint');
+  if (!snapshot.implementedEndpoints.some((e) => e === 'POST /1/indexes/:name/batch')) violations.push('missing batch endpoint');
+  if (!snapshot.implementedEndpoints.some((e) => e === 'GET /1/indexes')) violations.push('missing index list endpoint');
+  return {
+    ok: violations.length === 0,
+    endpointsChecked: snapshot.implementedEndpoints.length,
+    resourceTypesChecked: snapshot.resourceTypes.length,
+    violations,
+  };
+}

package/src/algolia-connector.ts

@@ -0,0 +1,84 @@
+// Algolia CONNECTOR — the live-vendor pull path over an INJECTED client (the auth boundary; a
+// fake in tests, the real `algoliasearch` SDK in prod). The pack imports NO SDK and holds NO key
+// at runtime — only this file's *type* shapes describe what a real client call would return; the
+// actual SDK is a devDependency imported ONLY in *.test.ts (architecture.test.ts).
+//
+// PULL (real -> twin): fetch real indices + records via the injected client, map them to
+// SyncResource[], and fold them into the event log via `syncPull` (shadow-diff dedup, so a
+// re-pull of identical state is a no-op). Kernel subject ids are TYPE-PREFIXED to stay
+// collision-safe (mirrors algolia-twin.ts).
+//
+// Records are genuinely BROWSE-DRIVEN, the same honest shape pinecone's connector uses for
+// vectors (see pinecone-connector.ts's file header): a real production implementation loops
+// `client.listIndices()` then browses each index's objects (`index.browseObjects()`) and
+// flattens the result into exactly this connector's own pull-source shape — there is no single
+// cross-index "list every record" vendor endpoint, so `AlgoliaLikeClient.listRecords` is a
+// connector-owned aggregation shape (notes echoed in pull-audit.json). Synonyms are NOT pulled
+// (`algolia.connector.pull_synonyms`, todo).
+//
+// ── The client-side RATE BUDGET is not optional here ────────────────────────────────────────
+// Every entrypoint below GUARDS the injected client before touching it (`guardAlgoliaClient`, which
+// is idempotent — a caller who already wrapped is not double-charged, a caller who forgot is
+// protected anyway). Algolia publishes no scalar limit for search/browse/listIndices and explicitly
+// excludes `browse` from its QPS accounting, while `listRecords` here is a cross-index browse
+// aggregation that fans out; there is deliberately no option that turns the budget off. See
+// algolia-budget.ts.
+import { syncPull } from '@volter/world-core';
+import type { SyncResource } from '@volter/world-core';
+import { algoliaBudgetOf, guardAlgoliaClient, type AlgoliaBudgetedOptions } from './algolia-budget.ts';
+
+const SERVICE = 'algolia';
+
+export type { AlgoliaBudgetedOptions };
+
+export type AlgoliaRealIndex = { name: string };
+export type AlgoliaRealRecord = { index: string; objectID: string; fields?: Record<string, unknown> | null };
+
+// The injected client exposes the minimal subset the connector calls; a real Algolia-backed
+// implementation is structurally assignable (see file header for why `listRecords` is a
+// connector-owned aggregation shape, not a literal SDK method name).
+export interface AlgoliaLikeClient {
+  listIndices?: () => Promise<{ items: AlgoliaRealIndex[] }>;
+  listRecords?: () => Promise<{ records: AlgoliaRealRecord[] }>;
+}
+
+function indexKey(name: string): string {
+  return `index:${name}`;
+}
+function recordKey(index: string, objectID: string): string {
+  return `record:${index}::${objectID}`;
+}
+
+// ── PULL mappers (real Algolia object -> SyncResource) ─────────────────────────────────────
+export function mapIndex(m: AlgoliaRealIndex): SyncResource {
+  return { type: 'index', id: indexKey(m.name), fields: { name: m.name } };
+}
+export function mapRecord(r: AlgoliaRealRecord): SyncResource {
+  return { type: 'record', id: recordKey(r.index, r.objectID), fields: { ...(r.fields ?? {}) } };
+}
+
+export async function pullAlgoliaIndexes(rawClient: AlgoliaLikeClient, opts: AlgoliaBudgetedOptions = {}): Promise<SyncResource[]> {
+  const client = guardAlgoliaClient(rawClient, opts);
+  if (!client.listIndices) return [];
+  return (await client.listIndices()).items.map(mapIndex);
+}
+export async function pullAlgoliaRecords(rawClient: AlgoliaLikeClient, opts: AlgoliaBudgetedOptions = {}): Promise<SyncResource[]> {
+  const client = guardAlgoliaClient(rawClient, opts);
+  if (!client.listRecords) return [];
+  return (await client.listRecords()).records.map(mapRecord);
+}
+
+/**
+ * D7 entry point: pull from real Algolia (indices + records, via browse) and fold EVERY domain
+ * into the twin via ONE syncPull (shadow-diff dedup). Returns { observed, deltasAppended } — a
+ * re-pull of identical state appends ZERO deltas (observed stays, deltasAppended drops to 0).
+ */
+export async function syncAlgoliaFromReal(rawClient: AlgoliaLikeClient, opts: { root?: string; occurredAt?: string } & AlgoliaBudgetedOptions = {}): Promise<{ observed: number; deltasAppended: number }> {
+  // Guard ONCE here and hand the guarded client down: this is the entrypoint whose browse
+  // aggregation fans out, so it is the one that must be unable to run unbudgeted.
+  const client = guardAlgoliaClient(rawClient, algoliaBudgetOf(opts));
+  const occurredAt = opts.occurredAt ?? new Date().toISOString();
+  const resources: SyncResource[] = [...(await pullAlgoliaIndexes(client)), ...(await pullAlgoliaRecords(client))];
+  const result = syncPull({ service: SERVICE, resources, occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+  return { observed: result.observed, deltasAppended: result.deltasAppended };
+}