@volter/twin-algolia 0.1.0

package/src/algolia-twin.ts

@@ -0,0 +1,563 @@
+// Algolia API twin REQUEST HANDLER — a v1 slice of the Algolia hosted-search surface, backed by
+// the event/action-log kernel (@volter/world-core). Contract:
+//   handleAlgoliaTwinRequest({ method, path, body, host?, appId?, root, readOnly }) ->
+//     { status, body, headers }
+//
+// SOURCE OF TRUTH (spec-sources.json has the full grounded-vs-doc-UNVERIFIED breakdown): every
+// route path and wire-body shape claimed `done` below was independently verified LIVE — a
+// throwaway Node http server standing in for this twin, driven by the ACTUAL installed
+// `algoliasearch@4.27.0` npm package (fetched read-only via `npm pack`, then exercised with a
+// real running client, never a guess from memory of the API) — BEFORE this handler was written,
+// mirroring the rigor pinecone-sdk.integration.test.ts's header describes. That live pass
+// surfaced a genuinely surprising, easy-to-miss fact a docs skim would not have caught: the v4
+// JS SDK's `saveObject`/`partialUpdateObject`/`deleteObject` convenience methods do NOT hit a
+// per-object `PUT`/`DELETE` endpoint at all — they ALL route through
+// `POST /1/indexes/{indexName}/batch` with a `{requests:[{action,body}]}` envelope (⚠5, the
+// batch action-name grammar: `addObject` for auto-objectID create, `updateObject` for add-or-
+// replace-with-explicit-id, `partialUpdateObject`/`partialUpdateObjectNoCreate` for the two
+// createIfNotExists states, `deleteObject`). This handler implements THAT grounded batch grammar
+// as the primary record-write path (required for `algolia-sdk.integration.test.ts`'s rung-4
+// parity — a fetch-fallback was NOT needed, see that file's header). The auth headers
+// (`x-algolia-application-id` / `x-algolia-api-key`) and the `{message,status}` error envelope
+// were also confirmed round-tripping correctly through the real SDK's own error type in the same
+// live pass. A handful of items the live pass didn't settle (the exact unknown-objectID/index
+// error MESSAGE text, the direct add/partial/delete-by-id endpoint response field names like
+// `createdAt`/`updatedAt`) are annotated doc-UNVERIFIED inline — modeled on the well-known,
+// widely-published Algolia convention rather than invented, per spec-sources.json.
+//
+// HOST-TOLERANT ROUTER (S-simplification, ⚠8): real Algolia's SDKs default to three host
+// SHAPES — `{appId}.algolia.net` (write), `{appId}-dsn.algolia.net` (read), and
+// `{appId}-1/2/3.algolianet.com` (fallback; all three grounded from the installed SDK's own
+// `@algolia/client-search` dist source, not guessed) — and split control over which plane a
+// request may land on. This twin does NOT physically split read/write/DSN planes (one kernel
+// root) — `routeAlgoliaSurface`
+// TOLERATES every one of those host shapes (and no host at all) and always resolves to the
+// single `'api'` surface; every request is then routed by PATH ALONE (which is already fully
+// self-describing in the real Algolia REST API — `/1/indexes/{indexName}/...` always carries the
+// index name in the path, unlike Pinecone's per-index data-plane host). `mintHost`/
+// `recoverAppIdFromHost` exist for host-shape round-trip proof (`auth.host_tolerant_routing`)
+// and as the twin's own verifies' fallback (an explicit `appId` field, mirroring pinecone's
+// `index` field fallback) — they carry no functional weight beyond that.
+//
+// State lives ENTIRELY in the kernel action log: writes go through `applyTwinWrite`, reads are
+// the projection (`projectResources`). No Map/array side-store. No real Algolia is ever
+// contacted. An index springs into existence on its first record write (real Algolia has no
+// explicit "create index" endpoint — this matches the real product, not a twin shortcut).
+//
+// Unmodeled route/op returns Algolia's real single-plane error envelope `{message,status}`
+// (never a fabricated success). `readOnly` rejects WRITES per-operation (not by HTTP verb:
+// `POST /query`/`POST /browse` are read-shaped POSTs and stay allowed in readOnly mode, mirroring
+// pinecone-twin.ts's / linear-state.ts's per-operation readOnly gating).
+import { createHash } from 'node:crypto';
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { matchesAlgoliaFilters, matchesFacetFilters, computeFacetCounts, type FacetFilters } from './algolia-filter.ts';
+import { rankRecords, buildSynonymGroups, type CustomRankingRule, type SearchRecord } from './algolia-search.ts';
+
+const SERVICE = 'algolia';
+
+export type AlgoliaRequest = {
+  method: string;
+  path: string;
+  body?: string;
+  headers?: Record<string, string>;
+  /** Effective request host (real Host header, or the SDK-integration-test's target host). Fed
+   *  through routeAlgoliaSurface/recoverAppIdFromHost purely for host-tolerance proof. */
+  host?: string;
+  /** Explicit appId override — the twin's OWN verifies use this directly (spec §6's documented
+   *  fallback, mirrors pinecone's `index` field) instead of round-tripping through a host. */
+  appId?: string;
+  occurredAt?: string;
+  root?: string;
+  readOnly?: boolean;
+};
+export type AlgoliaResponse = { status: number; body: unknown; headers?: Record<string, string> };
+
+export const ALGOLIA_RESOURCE_TYPES = ['index', 'record', 'synonym'] as const;
+export type AlgoliaResourceType = typeof ALGOLIA_RESOURCE_TYPES[number];
+
+// ── host-tolerant router (S-simplification — see file header) ──────────────────────────────
+export type AlgoliaSurface = 'api';
+
+/** Canonical WRITE-host form for an appId — real Algolia hosts literally embed the appId as a
+ *  losslessly-recoverable prefix (unlike pinecone's synthetic per-index hash host), so no hash
+ *  is needed; `root` is accepted for signature symmetry with pinecone's mintHost but does not
+ *  affect the output (documented, not a bug — there is nothing per-root to disambiguate: the
+ *  appId already IS the whole identity a host shape encodes). */
+export function mintHost(appId: string, _root?: string): string {
+  return `${appId}.algolia.net`;
+}
+
+/** Recover an appId from ANY of the three real host shapes (or a bare Host: port-suffixed
+ *  variant), tolerating whichever one a caller presents. Returns undefined for an unrecognized
+ *  shape. */
+export function recoverAppIdFromHost(host: string | undefined): string | undefined {
+  if (!host) return undefined;
+  const bare = host.replace(/^https?:\/\//, '').split(':')[0]!;
+  let m = bare.match(/^(.+)-dsn\.algolia\.net$/);
+  if (m) return m[1];
+  m = bare.match(/^(.+)\.algolia\.net$/);
+  if (m) return m[1];
+  m = bare.match(/^(.+)-\d+\.algolianet\.com$/);
+  if (m) return m[1];
+  return undefined;
+}
+
+/** Accepts EVERY real host shape (and no host at all) — always resolves to the single `'api'`
+ *  surface; actual dispatch is by PATH alone (see file header). */
+export function routeAlgoliaSurface(_req: { host?: string; path: string }): AlgoliaSurface {
+  return 'api';
+}
+
+// ── error envelope (single-plane — simpler than pinecone's two-plane split, spec §3) ─────────
+function algoliaError(status: number, message: string): AlgoliaResponse {
+  return { status, body: { message, status } };
+}
+function readOnlyRejection(): AlgoliaResponse {
+  return { status: 405, body: { message: 'twin is read-only; omit readOnly to accept writes', status: 405 } };
+}
+
+// ── body / helpers ────────────────────────────────────────────────────────────────────────────
+function parseBody(body?: string): unknown {
+  if (!body) return undefined;
+  try {
+    return JSON.parse(body);
+  } catch {
+    return undefined;
+  }
+}
+function parseObjectBody(body?: string): Record<string, unknown> {
+  const v = parseBody(body);
+  return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+}
+function nowIso(occurredAt?: string): string {
+  return occurredAt ?? new Date().toISOString();
+}
+
+// ── kernel subject ids (type-prefixed; D1) ──────────────────────────────────────────────────
+function indexKey(name: string): string {
+  return `index:${name}`;
+}
+function recordKey(index: string, objectID: string): string {
+  return `record:${index}::${objectID}`;
+}
+function synonymKey(index: string, id: string): string {
+  return `synonym:${index}::${id}`;
+}
+function settingsKey(index: string): string {
+  return `settings:${index}`;
+}
+function parseRecordSuffix(suffix: string): { index: string; objectID: string } | undefined {
+  const parts = suffix.split('::');
+  if (parts.length !== 2) return undefined;
+  return { index: parts[0]!, objectID: parts[1]! };
+}
+function parseSynonymSuffix(suffix: string): { index: string; id: string } | undefined {
+  const parts = suffix.split('::');
+  if (parts.length !== 2) return undefined;
+  return { index: parts[0]!, id: parts[1]! };
+}
+
+type Row = Record<string, unknown> & { type: string; id: string };
+
+function rowsOfType(type: string, root?: string): Row[] {
+  const prefix = `${type}:`;
+  return (projectResources(SERVICE, root) as Row[]).filter((r) => r.type === type && r.id.startsWith(prefix) && r._deleted !== true);
+}
+function getRowById(type: string, subjectId: string, root?: string): Row | undefined {
+  return (projectResources(SERVICE, root) as Row[]).find((r) => r.type === type && r.id === subjectId && r._deleted !== true);
+}
+/** Raw row lookup, WITHOUT filtering `_deleted` — used only to discover every field name the
+ *  kernel has ever merged for a subject (see `writeAddOrReplace`'s header note on why a true
+ *  "replace" needs this). */
+function getRawRowById(type: string, subjectId: string, root?: string): Row | undefined {
+  return (projectResources(SERVICE, root) as Row[]).find((r) => r.type === type && r.id === subjectId);
+}
+/** The kernel's action log is FIELD-MERGE, not whole-record-replace (`shadow.ts`'s `applyFields`
+ *  only ever ADDS/OVERWRITES the fields present in a given write — there is no way to remove a
+ *  field from the merged shadow except writing it as `null`, which every reader below strips back
+ *  out). `undefined` is silently skipped by the kernel (not a valid erase signal); `null` is a
+ *  genuine value the kernel stores and merges, so this pack repurposes it as the erase sentinel.
+ *  Also strips the kernel's OWN meta fields (`type`/`id`/`updatedAt` always ride along on every
+ *  `projectResources` row; `_deleted` is this pack's own soft-delete/undelete marker) — a caller-
+ *  supplied field literally named `updatedAt` would collide, an accepted, documented limitation
+ *  (mirrors every other pack's kernel-row convention; see pinecone-twin.ts's view functions,
+ *  which hand-pick fields for the same reason). */
+const INTERNAL_ROW_FIELDS = new Set(['type', 'id', 'updatedAt', '_deleted']);
+function publicFields(row: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(row)) {
+    if (INTERNAL_ROW_FIELDS.has(k) || v === null) continue;
+    out[k] = v;
+  }
+  return out;
+}
+async function applyWrite(subjectType: string, subjectId: string, fields: Record<string, unknown>, operation: string, req: AlgoliaRequest): Promise<Row> {
+  const { resource } = await applyTwinWrite(
+    SERVICE,
+    { operation, subjectType, subjectId, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } },
+    req.root,
+  );
+  return resource as Row;
+}
+
+/** Ensure `index:<name>` exists (real Algolia mints an index implicitly on first write — no
+ *  explicit create-index endpoint, matches the real product). */
+async function ensureIndex(name: string, req: AlgoliaRequest): Promise<void> {
+  if (getRowById('index', indexKey(name), req.root)) return;
+  await applyWrite('index', indexKey(name), { name, createdAt: nowIso(req.occurredAt) }, 'index.touch', req);
+}
+
+function recordsIn(index: string, root?: string): SearchRecord[] {
+  const prefix = `record:${index}::`;
+  return rowsOfType('record', root)
+    .filter((r) => r.id.startsWith(prefix))
+    .map((r) => {
+      const parsed = parseRecordSuffix(r.id.slice('record:'.length))!;
+      return { ...publicFields(r), objectID: parsed.objectID } as SearchRecord;
+    });
+}
+// Algolia's synonym schema has its OWN field literally called `type` (`"synonym"` |
+// `"oneWaySynonym"` | ...) — a genuine collision with the kernel's reserved row-meta field of
+// the SAME name (`projectResources`'s own `META` set silently drops any stored field named
+// `type`/`id`/`updatedAt` — see `publicFields`'s header note). Stored under `synonymType`
+// internally; renamed back to `type` on every read.
+function toStoredSynonymFields(s: Record<string, unknown>): Record<string, unknown> {
+  const { objectID: _drop, type, ...rest } = s;
+  return { ...rest, ...(type !== undefined ? { synonymType: type } : {}) };
+}
+function fromStoredSynonymFields(fields: Record<string, unknown>): Record<string, unknown> {
+  const { synonymType, ...rest } = fields;
+  return { ...rest, ...(synonymType !== undefined ? { type: synonymType } : {}) };
+}
+function synonymsIn(index: string, root?: string): Array<Record<string, unknown> & { objectID: string }> {
+  const prefix = `synonym:${index}::`;
+  return rowsOfType('synonym', root)
+    .filter((r) => r.id.startsWith(prefix))
+    .map((r) => {
+      const parsed = parseSynonymSuffix(r.id.slice('synonym:'.length))!;
+      return { ...fromStoredSynonymFields(publicFields(r)), objectID: parsed.id };
+    });
+}
+function readSettings(index: string, root?: string): Record<string, unknown> {
+  const row = getRowById('settings', settingsKey(index), root);
+  return {
+    searchableAttributes: (row?.searchableAttributes as string[] | undefined) ?? [],
+    attributesForFaceting: (row?.attributesForFaceting as string[] | undefined) ?? [],
+    // This default is the vendor's documented stock ranking-criteria list (returned faithfully so
+    // reads/round-trips match real Algolia); it is NOT the pack's modeled ranking subset —
+    // `rankRecords` (algolia-search.ts) ignores this array entirely and always ranks by its own
+    // faithful-subset criteria order, custom ranking excepted.
+    ranking: (row?.ranking as string[] | undefined) ?? ['typo', 'geo', 'words', 'filters', 'proximity', 'attribute', 'exact', 'custom'],
+    customRanking: (row?.customRanking as string[] | undefined) ?? [],
+  };
+}
+function parseCustomRanking(customRanking: readonly string[]): CustomRankingRule[] {
+  const rules: CustomRankingRule[] = [];
+  for (const raw of customRanking) {
+    const m = /^(asc|desc)\(([^)]+)\)$/.exec(raw.trim());
+    if (m) rules.push({ direction: m[1] as 'asc' | 'desc', attribute: m[2]! });
+  }
+  return rules;
+}
+
+function recordView(r: Row): SearchRecord {
+  const parsed = parseRecordSuffix(r.id.slice('record:'.length))!;
+  return { ...publicFields(r), objectID: parsed.objectID } as SearchRecord;
+}
+
+// ── record write primitives (shared by direct endpoints AND the /batch grammar, ⚠5) ─────────
+// R9 (serve-path determinism) AT THE RESOURCE LEVEL: the minted id is a function of the WRITE —
+// index + the world instant the request occurred at + the ordinal this record takes in the index —
+// and of NOTHING ELSE. It deliberately does NOT hash the world `root`: the root is a filesystem
+// path, so folding it in made the served objectID a function of WHERE the world happens to live,
+// and two identical worlds under different directories served different ids (found 2026-09-02 by
+// the R9 replay sweep, which reads a minted id back through `GET /1/indexes/:name/:objectID`).
+// `salt` is the count of records in the index BEFORE the insert, which is what keeps two adds
+// landing in the SAME millisecond distinct.
+function mintObjectId(index: string, occurredAt: string, salt: number): string {
+  return createHash('sha256').update(`algolia-twin-objectid:${index}:${occurredAt}:${salt}`).digest('hex').slice(0, 12);
+}
+
+/** Add-or-REPLACE the whole record: any field the PREVIOUS write set that is absent from the new
+ *  body is explicitly nulled out (the kernel's field-merge model has no other way to make a field
+ *  disappear — see `publicFields`'s header note). Looks at the RAW historical row (not the
+ *  filtered current one) so a replace after a delete-then-recreate still starts genuinely fresh. */
+async function writeAddOrReplace(index: string, objectID: string, body: Record<string, unknown>, req: AlgoliaRequest): Promise<void> {
+  await ensureIndex(index, req);
+  const raw = getRawRowById('record', recordKey(index, objectID), req.root);
+  const { objectID: _drop, ...fields } = body;
+  const erase: Record<string, unknown> = {};
+  if (raw) {
+    const { type: _t, id: _id, _deleted: _d, ...oldFields } = raw;
+    for (const k of Object.keys(oldFields)) if (!(k in fields)) erase[k] = null;
+  }
+  await applyWrite('record', recordKey(index, objectID), { ...erase, ...fields, _deleted: false }, 'record.add_replace', req);
+}
+async function writePartialUpdate(index: string, objectID: string, patch: Record<string, unknown>, req: AlgoliaRequest, createIfNotExists: boolean): Promise<'ok' | 'not_found'> {
+  const existing = getRowById('record', recordKey(index, objectID), req.root);
+  if (!existing && !createIfNotExists) return 'not_found';
+  await ensureIndex(index, req);
+  const { objectID: _drop, ...patchFields } = patch;
+  // A genuine MERGE, unlike writeAddOrReplace: the kernel's own field-merge (shadow.ts's
+  // applyFields) already does exactly this on top of whatever is currently stored, so writing
+  // just the patch (no manual `{...existing, ...patch}` pre-merge) is both correct and simpler;
+  // `_deleted: false` covers the createIfNotExists-on-a-previously-deleted-id edge case.
+  await applyWrite('record', recordKey(index, objectID), { ...patchFields, _deleted: false }, 'record.partial_update', req);
+  return 'ok';
+}
+async function writeDelete(index: string, objectID: string, req: AlgoliaRequest): Promise<void> {
+  await applyWrite('record', recordKey(index, objectID), { _deleted: true }, 'record.delete', req);
+}
+
+// ── route handler ────────────────────────────────────────────────────────────────────────────
+export async function handleAlgoliaTwinRequest(req: AlgoliaRequest): Promise<AlgoliaResponse> {
+  const method = req.method.toUpperCase();
+  const [rawPath, rawQuery] = req.path.split('?');
+  const path = (rawPath ?? '/').replace(/\/+$/, '') || '/';
+  const query = new URLSearchParams(rawQuery ?? '');
+  const seg = path.replace(/^\/+/, '').split('/').filter(Boolean);
+  const idAt = (i: number) => decodeURIComponent(seg[i] ?? '');
+  routeAlgoliaSurface({ host: req.host, path }); // host-tolerance is unconditional — see file header
+
+  if (path === '/' || seg.length === 0) {
+    return { status: 200, body: { service: 'algolia', object: 'twin' } };
+  }
+  if (seg[0] !== '1' || seg[1] !== 'indexes') {
+    return algoliaError(404, `Route not found: ${method} ${path}`);
+  }
+
+  // ── GET /1/indexes — list ────────────────────────────────────────────────────────────────
+  if (seg.length === 2 && method === 'GET') {
+    const items = rowsOfType('index', req.root).map((r) => ({
+      name: (r.name as string) ?? '',
+      entries: recordsIn(r.name as string, req.root).length,
+      createdAt: r.createdAt ?? nowIso(req.occurredAt),
+      updatedAt: r.createdAt ?? nowIso(req.occurredAt),
+    }));
+    return { status: 200, body: { items, nbPages: 1 } };
+  }
+
+  const indexName = idAt(2);
+
+  // ── DELETE /1/indexes/:name — delete index + its records/settings/synonyms ─────────────────
+  if (seg.length === 3 && method === 'DELETE') {
+    if (req.readOnly) return readOnlyRejection();
+    for (const r of recordsIn(indexName, req.root)) await writeDelete(indexName, r.objectID, req);
+    for (const s of synonymsIn(indexName, req.root)) await applyWrite('synonym', synonymKey(indexName, s.objectID), { _deleted: true }, 'synonym.delete', req);
+    await applyWrite('index', indexKey(indexName), { _deleted: true }, 'index.delete', req);
+    return { status: 200, body: { taskID: 0, deletedAt: nowIso(req.occurredAt) } };
+  }
+
+  // ── POST /1/indexes/:name — add object, auto objectID ───────────────────────────────────
+  if (seg.length === 3 && method === 'POST') {
+    if (req.readOnly) return readOnlyRejection();
+    const body = parseObjectBody(req.body);
+    const occurredAt = nowIso(req.occurredAt);
+    const objectID = typeof body.objectID === 'string' && body.objectID.length > 0 ? body.objectID : mintObjectId(indexName, occurredAt, recordsIn(indexName, req.root).length);
+    await writeAddOrReplace(indexName, objectID, { ...body, objectID }, req);
+    // Algolia's write endpoints conventionally return 200, not 201 (doc-UNVERIFIED — not
+    // strictly REST-resource-creation-shaped; modeled on the well-known convention).
+    return { status: 200, body: { objectID, taskID: 0, createdAt: occurredAt } };
+  }
+
+  // ── /1/indexes/:name/clear|batch|query|settings|synonyms ────────────────────────────────
+  const sub = seg.length >= 4 ? seg[3] : undefined;
+
+  if (seg.length === 4 && sub === 'clear' && method === 'POST') {
+    if (req.readOnly) return readOnlyRejection();
+    if (!getRowById('index', indexKey(indexName), req.root)) return algoliaError(404, `Index ${indexName} does not exist`);
+    for (const r of recordsIn(indexName, req.root)) await writeDelete(indexName, r.objectID, req);
+    return { status: 200, body: { taskID: 0, updatedAt: nowIso(req.occurredAt) } };
+  }
+
+  if (seg.length === 4 && sub === 'batch' && method === 'POST') {
+    if (req.readOnly) return readOnlyRejection();
+    const body = parseObjectBody(req.body);
+    const requests = Array.isArray(body.requests) ? (body.requests as Array<Record<string, unknown>>) : [];
+    const occurredAt = nowIso(req.occurredAt);
+    const objectIDs: string[] = [];
+    for (let i = 0; i < requests.length; i++) {
+      const action = requests[i]!.action as string;
+      const recBody = (requests[i]!.body as Record<string, unknown>) ?? {};
+      if (action === 'addObject') {
+        const objectID = typeof recBody.objectID === 'string' && recBody.objectID.length > 0 ? recBody.objectID : mintObjectId(indexName, occurredAt, recordsIn(indexName, req.root).length + i);
+        await writeAddOrReplace(indexName, objectID, { ...recBody, objectID }, req);
+        objectIDs.push(objectID);
+      } else if (action === 'updateObject') {
+        const objectID = typeof recBody.objectID === 'string' ? recBody.objectID : '';
+        if (!objectID) return algoliaError(400, 'updateObject requires an objectID in the request body');
+        await writeAddOrReplace(indexName, objectID, recBody, req);
+        objectIDs.push(objectID);
+      } else if (action === 'partialUpdateObject' || action === 'partialUpdateObjectNoCreate') {
+        const objectID = typeof recBody.objectID === 'string' ? recBody.objectID : '';
+        if (!objectID) return algoliaError(400, `${action} requires an objectID in the request body`);
+        const outcome = await writePartialUpdate(indexName, objectID, recBody, req, action === 'partialUpdateObject');
+        if (outcome === 'not_found') return algoliaError(404, `Object not found - Received createIfNotExist=false and object ${objectID} does not exist yet`);
+        objectIDs.push(objectID);
+      } else if (action === 'deleteObject') {
+        const objectID = typeof recBody.objectID === 'string' ? recBody.objectID : '';
+        if (!objectID) return algoliaError(400, 'deleteObject requires an objectID in the request body');
+        await writeDelete(indexName, objectID, req);
+        objectIDs.push(objectID);
+      } else {
+        return algoliaError(400, `Invalid batch action: ${String(action)}`);
+      }
+    }
+    return { status: 200, body: { objectIDs, taskID: 0 } };
+  }
+
+  if (seg.length === 4 && sub === 'query' && method === 'POST') {
+    return runSearch(indexName, parseObjectBody(req.body), req);
+  }
+
+  if (seg.length === 4 && sub === 'settings' && method === 'GET') {
+    return { status: 200, body: readSettings(indexName, req.root) };
+  }
+  if (seg.length === 4 && sub === 'settings' && method === 'PUT') {
+    if (req.readOnly) return readOnlyRejection();
+    const patch = parseObjectBody(req.body);
+    const existing = readSettings(indexName, req.root);
+    await applyWrite('settings', settingsKey(indexName), { ...existing, ...patch }, 'settings.set', req);
+    return { status: 200, body: { taskID: 0, updatedAt: nowIso(req.occurredAt) } };
+  }
+
+  // ── synonyms ──────────────────────────────────────────────────────────────────────────────
+  if (sub === 'synonyms') {
+    if (seg.length === 5 && seg[4] === 'batch' && method === 'POST') {
+      if (req.readOnly) return readOnlyRejection();
+      const arr = parseBody(req.body);
+      const synonyms = Array.isArray(arr) ? (arr as Array<Record<string, unknown>>) : [];
+      for (const s of synonyms) {
+        const objectID = typeof s.objectID === 'string' ? s.objectID : '';
+        if (!objectID) return algoliaError(400, 'each synonym requires an objectID');
+        await ensureIndex(indexName, req);
+        await applyWrite('synonym', synonymKey(indexName, objectID), toStoredSynonymFields(s), 'synonym.save', req);
+      }
+      return { status: 200, body: { updatedAt: nowIso(req.occurredAt), taskID: 0 } };
+    }
+    if (seg.length === 5 && method === 'GET') {
+      const objectID = idAt(4);
+      const row = getRowById('synonym', synonymKey(indexName, objectID), req.root);
+      if (!row) return algoliaError(404, `ObjectID does not exist`);
+      return { status: 200, body: { ...fromStoredSynonymFields(publicFields(row)), objectID } };
+    }
+    if (seg.length === 5 && method === 'DELETE') {
+      if (req.readOnly) return readOnlyRejection();
+      const objectID = idAt(4);
+      await applyWrite('synonym', synonymKey(indexName, objectID), { _deleted: true }, 'synonym.delete', req);
+      return { status: 200, body: { deletedAt: nowIso(req.occurredAt), taskID: 0 } };
+    }
+    return algoliaError(404, `Route not found: ${method} ${path}`);
+  }
+
+  // ── record direct endpoints: GET/PUT/DELETE /1/indexes/:name/:objectID (+ /partial) ───────
+  if (seg.length === 4) {
+    const objectID = idAt(3);
+    if (method === 'GET') {
+      const row = getRowById('record', recordKey(indexName, objectID), req.root);
+      if (!row) return algoliaError(404, `ObjectID does not exist`);
+      return { status: 200, body: recordView(row) };
+    }
+    if (method === 'PUT') {
+      if (req.readOnly) return readOnlyRejection();
+      const body = parseObjectBody(req.body);
+      await writeAddOrReplace(indexName, objectID, { ...body, objectID }, req);
+      return { status: 200, body: { objectID, taskID: 0, updatedAt: nowIso(req.occurredAt) } };
+    }
+    if (method === 'DELETE') {
+      if (req.readOnly) return readOnlyRejection();
+      // Delete is idempotent — deleting an already-absent objectID is still a 200, mirroring the
+      // real product (not a fabricated success: nothing false is claimed, the end state is
+      // genuinely "absent" either way).
+      await writeDelete(indexName, objectID, req);
+      return { status: 200, body: { deletedAt: nowIso(req.occurredAt), taskID: 0 } };
+    }
+  }
+  if (seg.length === 5 && seg[4] === 'partial' && method === 'POST') {
+    if (req.readOnly) return readOnlyRejection();
+    const objectID = idAt(3);
+    const body = parseObjectBody(req.body);
+    // Direct endpoint default: createIfNotExists defaults to TRUE when the query param is
+    // omitted (the well-known, widely-published REST-endpoint default — doc-UNVERIFIED not
+    // live-fetched, distinct from the JS SDK v4 client's own more-conservative default of
+    // `false`/NoCreate when its OWN option is omitted, confirmed live via probe — see file
+    // header and ⚠4/spec-sources.json).
+    const createIfNotExists = query.get('createIfNotExists') === 'false' ? false : true;
+    const outcome = await writePartialUpdate(indexName, objectID, body, req, createIfNotExists);
+    if (outcome === 'not_found') return algoliaError(404, `Object not found - Received createIfNotExist=false and object ${objectID} does not exist yet`);
+    return { status: 200, body: { objectID, taskID: 0, updatedAt: nowIso(req.occurredAt) } };
+  }
+
+  return algoliaError(404, `Route not found: ${method} ${path}`);
+}
+
+function runSearch(indexName: string, body: Record<string, unknown>, req: AlgoliaRequest): AlgoliaResponse {
+  const indexRow = getRowById('index', indexKey(indexName), req.root);
+  if (!indexRow) return algoliaError(404, `Index ${indexName} does not exist`);
+  const settings = readSettings(indexName, req.root);
+  const query = typeof body.query === 'string' ? body.query : '';
+  const page = typeof body.page === 'number' ? body.page : 0;
+  const hitsPerPage = typeof body.hitsPerPage === 'number' ? body.hitsPerPage : 20;
+  const filters = typeof body.filters === 'string' ? body.filters : undefined;
+  const facetFilters = (body.facetFilters as FacetFilters | undefined) ?? undefined;
+  const attributesToRetrieve = Array.isArray(body.attributesToRetrieve) ? (body.attributesToRetrieve as string[]) : undefined;
+  const requestedFacets = Array.isArray(body.facets) ? (body.facets as string[]) : undefined;
+
+  const allRecords = recordsIn(indexName, req.root);
+  const synonymGroups = buildSynonymGroups(synonymsIn(indexName, req.root) as Array<{ type?: string; synonyms?: string[] }>);
+  const preFiltered = allRecords.filter((r) => matchesAlgoliaFilters(r, filters) && matchesFacetFilters(r, facetFilters));
+
+  const customRanking = parseCustomRanking(settings.customRanking as string[]);
+  const ranked = rankRecords(preFiltered, query, {
+    searchableAttributes: settings.searchableAttributes as string[],
+    customRanking,
+    synonymGroups,
+  });
+
+  const nbHits = ranked.length;
+  const hitsPerPageEff = Math.max(1, hitsPerPage);
+  const nbPages = Math.max(1, Math.ceil(nbHits / hitsPerPageEff));
+  const pageHits = ranked.slice(page * hitsPerPageEff, page * hitsPerPageEff + hitsPerPageEff);
+
+  const project = (record: SearchRecord): Record<string, unknown> => {
+    if (!attributesToRetrieve || attributesToRetrieve.includes('*')) return { ...record, objectID: record.objectID };
+    const out: Record<string, unknown> = { objectID: record.objectID };
+    for (const attr of attributesToRetrieve) if (attr in record) out[attr] = record[attr];
+    return out;
+  };
+
+  const facetAttrs = (settings.attributesForFaceting as string[]).filter((a) => !requestedFacets || requestedFacets.includes('*') || requestedFacets.includes(a));
+  const responseBody: Record<string, unknown> = {
+    hits: pageHits.map((h) => project(h.record)),
+    nbHits,
+    page,
+    nbPages,
+    hitsPerPage: hitsPerPageEff,
+    processingTimeMS: 0,
+    query,
+    params: '',
+  };
+  if (requestedFacets && requestedFacets.length > 0) {
+    responseBody.facets = computeFacetCounts(preFiltered, facetAttrs);
+  }
+  return { status: 200, body: responseBody };
+}
+
+export type AlgoliaTwinSnapshot = {
+  resourceTypes: readonly AlgoliaResourceType[];
+  implementedEndpoints: readonly string[];
+};
+
+export function algoliaTwinSnapshot(): AlgoliaTwinSnapshot {
+  return {
+    resourceTypes: ALGOLIA_RESOURCE_TYPES,
+    implementedEndpoints: [
+      'GET /1/indexes', 'DELETE /1/indexes/:name', 'POST /1/indexes/:name', 'POST /1/indexes/:name/clear',
+      'POST /1/indexes/:name/batch', 'POST /1/indexes/:name/query',
+      'GET /1/indexes/:name/settings', 'PUT /1/indexes/:name/settings',
+      'POST /1/indexes/:name/synonyms/batch', 'GET /1/indexes/:name/synonyms/:objectID', 'DELETE /1/indexes/:name/synonyms/:objectID',
+      'GET /1/indexes/:name/:objectID', 'PUT /1/indexes/:name/:objectID', 'DELETE /1/indexes/:name/:objectID',
+      'POST /1/indexes/:name/:objectID/partial',
+    ],
+  };
+}

package/src/cli.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-algolia CLI: serve the KERNEL-BACKED Algolia API twin, or run conformance. State lives in
+// the @volter/world-core action log (no in-memory side-store). Conformance is dev-only + lazy-imported
+// so the bin runs without @volter/world-tooling (E2).
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createAlgoliaTwinServer } from './algolia-server.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', String(process.env.PORT ?? '0'))) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+
+if (cmd === 'serve' || cmd === undefined) {
+  const s = await createAlgoliaTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`algolia twin (hosted search: indices/records + real tokenize/typo/filter/facet/ranking search)${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  const { checkAlgoliaConformance } = await import('./algolia-conformance.ts');
+  const report = checkAlgoliaConformance();
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-algolia serve|conformance [--port N] [--root DIR] [--read-only]\n');
+}