@volter/twin-algolia 0.1.0

package/dist/src/algolia-twin.js

@@ -0,0 +1,540 @@
+// 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 } from "./algolia-filter.js";
+import { rankRecords, buildSynonymGroups } from "./algolia-search.js";
+const SERVICE = 'algolia';
+export const ALGOLIA_RESOURCE_TYPES = ['index', 'record', 'synonym'];
+/** 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, _root) {
+    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) {
+    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) {
+    return 'api';
+}
+// ── error envelope (single-plane — simpler than pinecone's two-plane split, spec §3) ─────────
+function algoliaError(status, message) {
+    return { status, body: { message, status } };
+}
+function readOnlyRejection() {
+    return { status: 405, body: { message: 'twin is read-only; omit readOnly to accept writes', status: 405 } };
+}
+// ── body / helpers ────────────────────────────────────────────────────────────────────────────
+function parseBody(body) {
+    if (!body)
+        return undefined;
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseObjectBody(body) {
+    const v = parseBody(body);
+    return v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+}
+function nowIso(occurredAt) {
+    return occurredAt ?? new Date().toISOString();
+}
+// ── kernel subject ids (type-prefixed; D1) ──────────────────────────────────────────────────
+function indexKey(name) {
+    return `index:${name}`;
+}
+function recordKey(index, objectID) {
+    return `record:${index}::${objectID}`;
+}
+function synonymKey(index, id) {
+    return `synonym:${index}::${id}`;
+}
+function settingsKey(index) {
+    return `settings:${index}`;
+}
+function parseRecordSuffix(suffix) {
+    const parts = suffix.split('::');
+    if (parts.length !== 2)
+        return undefined;
+    return { index: parts[0], objectID: parts[1] };
+}
+function parseSynonymSuffix(suffix) {
+    const parts = suffix.split('::');
+    if (parts.length !== 2)
+        return undefined;
+    return { index: parts[0], id: parts[1] };
+}
+function rowsOfType(type, root) {
+    const prefix = `${type}:`;
+    return projectResources(SERVICE, root).filter((r) => r.type === type && r.id.startsWith(prefix) && r._deleted !== true);
+}
+function getRowById(type, subjectId, root) {
+    return projectResources(SERVICE, root).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, subjectId, root) {
+    return projectResources(SERVICE, root).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) {
+    const out = {};
+    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, subjectId, fields, operation, req) {
+    const { resource } = await applyTwinWrite(SERVICE, { operation, subjectType, subjectId, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
+    return resource;
+}
+/** 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, req) {
+    if (getRowById('index', indexKey(name), req.root))
+        return;
+    await applyWrite('index', indexKey(name), { name, createdAt: nowIso(req.occurredAt) }, 'index.touch', req);
+}
+function recordsIn(index, root) {
+    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 };
+    });
+}
+// 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) {
+    const { objectID: _drop, type, ...rest } = s;
+    return { ...rest, ...(type !== undefined ? { synonymType: type } : {}) };
+}
+function fromStoredSynonymFields(fields) {
+    const { synonymType, ...rest } = fields;
+    return { ...rest, ...(synonymType !== undefined ? { type: synonymType } : {}) };
+}
+function synonymsIn(index, root) {
+    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, root) {
+    const row = getRowById('settings', settingsKey(index), root);
+    return {
+        searchableAttributes: row?.searchableAttributes ?? [],
+        attributesForFaceting: row?.attributesForFaceting ?? [],
+        // 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 ?? ['typo', 'geo', 'words', 'filters', 'proximity', 'attribute', 'exact', 'custom'],
+        customRanking: row?.customRanking ?? [],
+    };
+}
+function parseCustomRanking(customRanking) {
+    const rules = [];
+    for (const raw of customRanking) {
+        const m = /^(asc|desc)\(([^)]+)\)$/.exec(raw.trim());
+        if (m)
+            rules.push({ direction: m[1], attribute: m[2] });
+    }
+    return rules;
+}
+function recordView(r) {
+    const parsed = parseRecordSuffix(r.id.slice('record:'.length));
+    return { ...publicFields(r), objectID: parsed.objectID };
+}
+// ── 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, occurredAt, salt) {
+    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, objectID, body, req) {
+    await ensureIndex(index, req);
+    const raw = getRawRowById('record', recordKey(index, objectID), req.root);
+    const { objectID: _drop, ...fields } = body;
+    const erase = {};
+    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, objectID, patch, req, createIfNotExists) {
+    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, objectID, req) {
+    await applyWrite('record', recordKey(index, objectID), { _deleted: true }, 'record.delete', req);
+}
+// ── route handler ────────────────────────────────────────────────────────────────────────────
+export async function handleAlgoliaTwinRequest(req) {
+    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) => 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 ?? '',
+            entries: recordsIn(r.name, 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 : [];
+        const occurredAt = nowIso(req.occurredAt);
+        const objectIDs = [];
+        for (let i = 0; i < requests.length; i++) {
+            const action = requests[i].action;
+            const recBody = requests[i].body ?? {};
+            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 : [];
+            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, body, req) {
+    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 ?? undefined;
+    const attributesToRetrieve = Array.isArray(body.attributesToRetrieve) ? body.attributesToRetrieve : undefined;
+    const requestedFacets = Array.isArray(body.facets) ? body.facets : undefined;
+    const allRecords = recordsIn(indexName, req.root);
+    const synonymGroups = buildSynonymGroups(synonymsIn(indexName, req.root));
+    const preFiltered = allRecords.filter((r) => matchesAlgoliaFilters(r, filters) && matchesFacetFilters(r, facetFilters));
+    const customRanking = parseCustomRanking(settings.customRanking);
+    const ranked = rankRecords(preFiltered, query, {
+        searchableAttributes: settings.searchableAttributes,
+        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) => {
+        if (!attributesToRetrieve || attributesToRetrieve.includes('*'))
+            return { ...record, objectID: record.objectID };
+        const out = { objectID: record.objectID };
+        for (const attr of attributesToRetrieve)
+            if (attr in record)
+                out[attr] = record[attr];
+        return out;
+    };
+    const facetAttrs = settings.attributesForFaceting.filter((a) => !requestedFacets || requestedFacets.includes('*') || requestedFacets.includes(a));
+    const responseBody = {
+        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 function 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/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,26 @@
+#!/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.js";
+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.js");
+    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');
+}

package/dist/src/index.d.ts

@@ -0,0 +1,13 @@
+export { handleAlgoliaTwinRequest, routeAlgoliaSurface, mintHost, recoverAppIdFromHost, algoliaTwinSnapshot, ALGOLIA_RESOURCE_TYPES, } from './algolia-twin.js';
+export type { AlgoliaRequest, AlgoliaResponse, AlgoliaSurface, AlgoliaResourceType, AlgoliaTwinSnapshot, } from './algolia-twin.js';
+export { createAlgoliaTwinFetch, createAlgoliaTwinServer, type AlgoliaTwinFetchOptions } from './algolia-server.js';
+export { mapIndex, mapRecord, pullAlgoliaIndexes, pullAlgoliaRecords, syncAlgoliaFromReal, } from './algolia-connector.js';
+export type { AlgoliaLikeClient, AlgoliaRealIndex, AlgoliaRealRecord, AlgoliaBudgetedOptions } from './algolia-connector.js';
+export { ALGOLIA_BUDGETED_METHODS, ALGOLIA_BUDGET_CEILING, ALGOLIA_BUDGET_MAX_RETRY_AFTER_S, ALGOLIA_BUDGET_WINDOW_MS, ALGOLIA_CALL_WEIGHTS, ALGOLIA_RATE_BUDGET, AlgoliaBudget, AlgoliaBudgetError, algoliaBudgetPath, algoliaCallWeight, algoliaClientBudget, guardAlgoliaClient, } from './algolia-budget.js';
+export type { AlgoliaBudgetErrorKind, AlgoliaBudgetOptions, AlgoliaBudgetReservation, AlgoliaBudgetSnapshot } from './algolia-budget.js';
+export { matchesAlgoliaFilters, matchesFacetFilters, computeFacetCounts } from './algolia-filter.js';
+export type { FacetFilters, FacetFilterClause } from './algolia-filter.js';
+export { tokenize, damerauLevenshtein, rankRecords, buildSynonymGroups } from './algolia-search.js';
+export type { SearchRecord, RankedHit, CustomRankingRule } from './algolia-search.js';
+import type { TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,62 @@
+// @volter/twin-algolia — the Algolia (algolia.com) hosted-search API twin, built on the shared
+// @volter/world-core kernel. Single-plane REST transport: every route lives under
+// `/1/indexes/{indexName}/...` (index list/delete/clear, record CRUD, REAL search — tokenize +
+// Damerau-Levenshtein typo tolerance + a faithful-subset ranking + REAL filter/facetFilters
+// evaluation + exact facet-count aggregation + customRanking tie-breaks + basic bidirectional
+// synonym expansion, settings get/set). Host-TOLERANT (not host-SPLIT, unlike pinecone): every
+// real Algolia host shape ({appId}.algolia.net / {appId}-dsn.algolia.net /
+// {appId}-N.algolianet.com) routes to the SAME single plane, since Algolia's REST paths already
+// carry the index name — no host-based dispatch is needed (see algolia-twin.ts's header). State
+// lives entirely in the kernel action log (no side-store). API-first vendor: no mirror, no UI
+// capabilities (ui-scope.json).
+//
+// THE SEARCH ENGINE (README ## Coverage has the full reasoning): this twin's search is a
+// faithful, deterministic SUBSET of the documented tie-break criteria, not a lesser stub;
+// widening it is `algolia.search.ranking_criteria_coverage` (todo). Writes apply synchronously
+// to one kernel root. Tokenization is deterministic ASCII/Unicode word-splitting today, with
+// stemming/plurals/CJK segmentation filed as `algolia.search.language_processing`. (Conformance/capability tooling lives in
+// @volter/world-tooling, a dev dependency — NOT shipped.)
+export { handleAlgoliaTwinRequest, routeAlgoliaSurface, mintHost, recoverAppIdFromHost, algoliaTwinSnapshot, ALGOLIA_RESOURCE_TYPES, } from "./algolia-twin.js";
+export { createAlgoliaTwinFetch, createAlgoliaTwinServer } from "./algolia-server.js";
+export { mapIndex, mapRecord, pullAlgoliaIndexes, pullAlgoliaRecords, syncAlgoliaFromReal, } from "./algolia-connector.js";
+// The client-side rate budget — the fail-closed backstop every live Algolia call goes through. The
+// MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives here is Algolia's
+// DECLARATION (window/ceiling/per-method weights) plus `guardAlgoliaClient`, the choke point the
+// connector entrypoints apply unconditionally. Exported so an operator can inspect spend
+// (`snapshot`) and a caller can catch `AlgoliaBudgetError` by type; there is deliberately no export
+// that disables the guard.
+export { ALGOLIA_BUDGETED_METHODS, ALGOLIA_BUDGET_CEILING, ALGOLIA_BUDGET_MAX_RETRY_AFTER_S, ALGOLIA_BUDGET_WINDOW_MS, ALGOLIA_CALL_WEIGHTS, ALGOLIA_RATE_BUDGET, AlgoliaBudget, AlgoliaBudgetError, algoliaBudgetPath, algoliaCallWeight, algoliaClientBudget, guardAlgoliaClient, } from "./algolia-budget.js";
+export { matchesAlgoliaFilters, matchesFacetFilters, computeFacetCounts } from "./algolia-filter.js";
+export { tokenize, damerauLevenshtein, rankRecords, buildSynonymGroups } from "./algolia-search.js";
+import { ALGOLIA_RATE_BUDGET as RATE_BUDGET } from "./algolia-budget.js";
+export const pack = {
+    vendor: 'algolia',
+    // The SAME object algolia-budget.ts declares at module load — one source of truth, so registering
+    // the pack and importing the connector can never arm two different ceilings.
+    rateBudget: RATE_BUDGET,
+    transport: 'rest',
+    archetype: 'crud',
+    bin: 'world-algolia',
+    resources: ['index', 'record', 'synonym', 'settings'],
+    specSource: 'algolia-conformance.ts (endpoint/resource inventory grounded LIVE against the installed algoliasearch SDK, driven end-to-end with a throwaway local server before this handler was written — see spec-sources.json)',
+    description: 'Algolia hosted-search twin — index list/delete/clear, record CRUD (add/replace/partial/delete/batch), REAL tokenize+typo+ranking search engine with REAL filter/facetFilters/facet-count evaluation, customRanking, basic synonym expansion, settings get/set, host-tolerant router. Kernel-backed. No mirror (API-first vendor).',
+    // Adoption, all in the pack's one home (descriptor-first back-migration, adding-a-twin.md §3, 2026-08-31; the bare
+    // `algolia` stem and the `algoliasearch` SDK name moved off the central maps unchanged). Stems:
+    // the bare ALGOLIA_* shape and the ALGOLIA_WRITE_* write-key half real apps split out.
+    adoption: {
+        // Algolia's own Python client - same distribution name as the npm one, different registry.
+        pypi: ['algoliasearch'],
+        sdks: ['algoliasearch'], envStems: ['ALGOLIA', 'ALGOLIAWRITE'],
+    },
+    // No `browserRouting`: unlike every other pack (which has ONE fixed absolute API host to strip
+    // for the zero-edit dev proxy — even supabase's per-PROJECT data API omits it in favor of its
+    // static management-API host), Algolia has NO fixed host at all — every real host is
+    // `{appId}.algolia.net`-shaped, with the caller's OWN appId baked directly into the domain. A
+    // literal `{appId}` placeholder is not a stripeable absolute host, so `browserRouting` is
+    // correctly omitted here rather than populated with a non-matching placeholder.
+    // INTERCEPTION RULING — hostsNone, the pack's own home for it: per-app-ID host scheme
+    // ({appId}.algolia.net / {appId}-dsn.algolia.net / {appId}-N.algolianet.com, see the pack
+    // README §Host tolerance) — no fixed host list to match; the host-tolerant twin is wired by
+    // explicit client host config.
+    hostsNone: "per-app-ID host scheme ({appId}.algolia.net / {appId}-dsn.algolia.net / {appId}-N.algolianet.com, see the pack README §Host tolerance) — no fixed host list to match; the host-tolerant twin is wired by explicit client host config",
+};