@volter/twin-pinecone 0.1.0

package/dist/src/pinecone-twin.js

@@ -0,0 +1,491 @@
+// Pinecone API twin REQUEST HANDLER — a v1 slice of the Pinecone vector-database surface, backed
+// by the event/action-log kernel (@volter/world-core). Contract:
+//   handlePineconeTwinRequest({ method, path, body, host?, index?, root, readOnly }) ->
+//     { status, body, headers }
+//
+// SOURCE OF TRUTH: authored against the real, first-party `@pinecone-database/pinecone` npm
+// package's OWN generated TypeScript-fetch client (the SDK's `dist/pinecone-generated-ts-fetch/
+// db_control` and `db_data` model files were fetched — via `npm pack`, an allowed unauthenticated
+// read — and read directly during this build; see spec-sources.json) — every route path, JSON
+// field name (all camelCase on the wire: `topK`, `includeValues`, `includeMetadata`,
+// `sparseValues`, `upsertedCount`, ...), and the two-plane error-envelope split below is grounded
+// against that generated client, NOT guessed. A handful of items the generated client doesn't
+// settle (exact index create/delete status codes, euclidean's exact wire score, query-by-id
+// self-inclusion, control-plane error shape) were additionally checked against Pinecone's public
+// docs (docs.pinecone.io, unauthenticated GET) and are annotated doc-UNVERIFIED inline where the
+// docs didn't resolve them — see spec-sources.json's `pinecone` entry for the full grounded-vs-
+// doc-UNVERIFIED breakdown.
+//
+// HOST-SPLIT (control vs data plane), grounded from the SDK: `new Pinecone({ controllerHostUrl
+// })` targets the CONTROL plane (index/collection management — `/indexes`, `/collections`); a
+// per-index DATA plane host is minted at index-create time (`IndexModel.host`) and targeted via
+// `pc.index({ name, host })` (verified in the SDK's own `data/index.js`: an explicit `host`
+// bypasses the SDK's own `IndexHostSingleton.getHostUrl` describeIndex lookup entirely — the
+// literal doc-comment example is `const index = pc.index({ host: indexModel.host })`). This twin
+// mints a real (if synthetic-looking) per-index hostname (`mintHost`) and a single request router
+// (`routePineconeSurface`) decides control-vs-data purely from the effective request host (or, as
+// a path fallback, whether the path starts with `/indexes` or `/collections`) — see
+// pinecone-server.ts's header comment for how an unmodified SDK's requests, which the SDK's
+// `normalizeUrl` will always try to dial as a real DNS host, are routed to this ONE local
+// twin process without ever touching the real network (a `fetchApi` override, not DNS).
+//
+// State lives ENTIRELY in the kernel action log: writes go through `applyTwinWrite`, reads are
+// the projection (`projectResources`). There is NO Map/array side-store — the projection over the
+// append-only log is the single source of truth (D1). No real Pinecone is ever contacted.
+//
+// WHAT THIS TWIN DOES (D2): the query is REAL brute-force exact top-K (pinecone-similarity.ts), a
+// faithful SUPERSET of Pinecone's approximate-NN recall, not a lesser stub. Indexes are marked
+// `ready` instantly and `indexFullness` is always 0. The integrated-embedding surface
+// (`createIndexForModel`, `/records/.../upsert|search`) is filed as
+// `pinecone.records.integrated_surface`; callers supply their own vectors today.
+//
+// Unmodeled route/op returns Pinecone's real error envelope for that plane (D2 — never a
+// fabricated success). readOnly rejects WRITES with 405 — gated per-operation (not by HTTP verb:
+// `POST /query` and `POST /describe_index_stats` are read-shaped POSTs and must stay allowed in
+// readOnly mode, mirroring how this repo's POST-transport GraphQL packs gate readOnly per-
+// mutation rather than by HTTP method — see linear-state.ts).
+import { createHash } from 'node:crypto';
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { matchesFilter } from "./pinecone-filter.js";
+import { scoreVector, sortByScore } from "./pinecone-similarity.js";
+const SERVICE = 'pinecone';
+const DEFAULT_NAMESPACE = '';
+export const PINECONE_RESOURCE_TYPES = ['index', 'collection', 'vector'];
+// ── host-split router ──────────────────────────────────────────────────────────────────────
+const DATA_HOST_SUFFIX = '.svc.twin.pinecone.io';
+/** Deterministic per-INDEX synthetic data-plane host — stable across calls, never a real
+ *  resolvable DNS name (this twin is only ever reached via pinecone-server.ts's fetchApi-level
+ *  redirect, so real-network resolvability is never required — see file header).
+ *
+ *  R9 (serve-path determinism) AT THE RESOURCE LEVEL: the minted host is a function of the INDEX
+ *  NAME and of nothing else. It deliberately does NOT hash the world `root`: the root is a
+ *  filesystem PATH, so folding it in made `IndexModel.host` — a field every list/describe serves
+ *  and every SDK dials — a function of WHERE the world happens to live, and two identical worlds
+ *  under different directories served different hosts (found 2026-09-02 by the R9 replay sweep,
+ *  the algolia `mintObjectId` defect in its second form). Uniqueness per root was never the
+ *  property that mattered: a host only ever has to round-trip back to its index name through
+ *  `recoverIndexFromHost` within ONE world, and index names are already unique within one. */
+export function mintHost(indexName) {
+    const h = createHash('sha256').update(`pinecone-twin-host:${indexName}`).digest('hex').slice(0, 8);
+    return `${indexName}-${h}${DATA_HOST_SUFFIX}`;
+}
+/** Recover an index name from a minted data-plane host (strip scheme/port, then the known
+ *  suffix and trailing `-<hash8>`). Returns undefined for the control host or an unrecognized one. */
+export function recoverIndexFromHost(host) {
+    if (!host)
+        return undefined;
+    const bare = host.replace(/^https?:\/\//, '').split(':')[0];
+    if (!bare.endsWith(DATA_HOST_SUFFIX))
+        return undefined;
+    const stem = bare.slice(0, -DATA_HOST_SUFFIX.length);
+    const m = stem.match(/^(.*)-([0-9a-f]{8})$/);
+    return m ? m[1] : undefined;
+}
+/** Decide control- vs data-plane purely from the effective host (path is a fallback for the
+ *  twin's own verifies that don't bother setting a host at all). */
+export function routePineconeSurface(req) {
+    const host = req.host;
+    const path = req.path.split('?')[0] ?? '/';
+    if (host === 'api.pinecone.io' || (host !== undefined && host.startsWith('api.pinecone.io:')))
+        return 'control';
+    if (host !== undefined && recoverIndexFromHost(host))
+        return 'data';
+    // No host, or a host that doesn't parse as a minted data-plane host — fall back to a
+    // path-shaped guess: this is what lets the twin's own verifies (and the capability manifest's
+    // `withRoot` helper) drive data-plane routes purely via the explicit `index` field, with no host
+    // round-trip at all (spec §6's documented fallback), while `/indexes`/`/collections` still
+    // resolve as control even with no host set.
+    if (path.startsWith('/indexes') || path.startsWith('/collections') || path === '/')
+        return 'control';
+    return 'data';
+}
+// ── error envelopes (two-plane split, D2/⚠2) ─────────────────────────────────────────────────
+// DATA plane (gRPC-gateway): grounded verbatim against docs.pinecone.io's Query reference (fetched
+// during this build) — `{code:int, message:string, details:[{typeUrl,value}]}` — codes per the
+// gRPC-gateway convention: 3=INVALID_ARGUMENT->400, 5=NOT_FOUND->404, 6=ALREADY_EXISTS->409.
+function dataError(status, code, message) {
+    return { status, body: { code, message, details: [] } };
+}
+// CONTROL plane: doc-UNVERIFIED (the fetched docs.pinecone.io error-handling page 404'd during
+// this build's read-only pass) — modeled per the build spec's own grounding pass:
+// `{error:{code, message}, status}`, a DIFFERENT shape from the data plane. Filed as
+// `pinecone.errors.control_plane_shape` (todo) for full parity once independently confirmed.
+function controlError(status, code, message) {
+    return { status, body: { error: { code, message }, status } };
+}
+function readOnlyRejection() {
+    return { status: 405, body: { message: 'twin is read-only; omit readOnly to accept writes' } };
+}
+// ── body / helpers ────────────────────────────────────────────────────────────────────────────
+function parseBody(body) {
+    if (!body)
+        return {};
+    try {
+        const v = JSON.parse(body);
+        return v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+    }
+    catch {
+        return {};
+    }
+}
+function nowIso(occurredAt) {
+    return occurredAt ?? new Date().toISOString();
+}
+// ── kernel subject ids (type-prefixed; D1) ──────────────────────────────────────────────────
+function indexKey(name) {
+    return `index:${name}`;
+}
+function collectionKey(name) {
+    return `collection:${name}`;
+}
+function vectorKey(index, namespace, id) {
+    return `vector:${index}::${namespace}::${id}`;
+}
+function parseVectorSuffix(suffix) {
+    const parts = suffix.split('::');
+    if (parts.length !== 3)
+        return undefined;
+    return { index: parts[0], namespace: parts[1], id: parts[2] };
+}
+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);
+}
+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;
+}
+// ── object views (mirror the SDK's generated model field names exactly) ────────────────────────
+function indexView(r) {
+    // WIRE field names, grounded against the SDK's generated IndexModel (De)Serializer
+    // (pinecone-generated-ts-fetch/db_control/models/IndexModel.js): most fields are camelCase, but
+    // `deletion_protection` and `vector_type` are SNAKE_CASE on the wire — a genuine, easy-to-miss
+    // inconsistency within the control plane itself (the data plane is uniformly camelCase — see
+    // pinecone-similarity.ts/query wire shapes). Internal kernel row field names stay camelCase
+    // (this pack's own choice); only this view's OUTPUT keys must match the wire exactly.
+    return {
+        name: r.name,
+        dimension: r.dimension ?? null,
+        metric: r.metric,
+        host: r.host,
+        spec: r.spec,
+        status: { ready: r.ready ?? true, state: r.state ?? 'Ready' },
+        deletion_protection: r.deletionProtection ?? 'disabled',
+        tags: r.tags ?? {},
+        vector_type: r.vectorType ?? 'dense',
+    };
+}
+function collectionView(r) {
+    // WIRE: `vector_count` is snake_case (CollectionModel.js); everything else here is camelCase-
+    // identical to its single-word form.
+    return {
+        name: r.name,
+        size: r.size ?? 0,
+        status: r.status ?? 'Ready',
+        dimension: r.dimension ?? null,
+        vector_count: r.vectorCount ?? 0,
+        environment: r.environment ?? 'twin-local',
+    };
+}
+function vectorView(index, namespace, id, r) {
+    return { id, values: r.values ?? [], metadata: r.metadata ?? {} };
+}
+// ── route handler ────────────────────────────────────────────────────────────────────────────
+export async function handlePineconeTwinRequest(req) {
+    const method = req.method.toUpperCase();
+    const [rawPath, rawQuery] = req.path.split('?');
+    const path = (rawPath ?? '/').replace(/\/+$/, '') || '/';
+    const query = new URLSearchParams(rawQuery ?? '');
+    const body = parseBody(req.body);
+    const seg = path.replace(/^\/+/, '').split('/').filter(Boolean);
+    const idAt = (i) => decodeURIComponent(seg[i] ?? '');
+    const surface = routePineconeSurface({ host: req.host, path });
+    if (path === '/' || seg.length === 0) {
+        return { status: 200, body: { service: 'pinecone', object: 'twin' } };
+    }
+    // ══════════════════════════════ CONTROL PLANE (api.pinecone.io) ═══════════════════════════
+    if (surface === 'control') {
+        // ── indexes ──
+        if (seg[0] === 'indexes') {
+            if (seg.length === 1 && method === 'POST') {
+                if (req.readOnly)
+                    return readOnlyRejection();
+                const name = typeof body.name === 'string' ? body.name : undefined;
+                // The real CreateIndexRequest schema makes `dimension` optional (only omittable for a
+                // model-backed / integrated-embedding index — `createIndexForModel`, filed as
+                // `pinecone.records.integrated_surface`). Since this twin
+                // never infers a dimension from a model, it requires an explicit one on every create.
+                const dimension = typeof body.dimension === 'number' ? body.dimension : undefined;
+                if (!name || !dimension)
+                    return controlError(400, 'INVALID_ARGUMENT', 'name and dimension are required to create an index');
+                if (getRowById('index', indexKey(name), req.root))
+                    return controlError(409, 'ALREADY_EXISTS', `Resource ${name} already exists`);
+                const metric = typeof body.metric === 'string' ? body.metric : 'cosine';
+                // WIRE keys are snake_case here (CreateIndexRequestToJSON) — see indexView's header note.
+                const vectorType = typeof body.vector_type === 'string' ? body.vector_type : 'dense';
+                const spec = body.spec ?? { serverless: { cloud: 'aws', region: 'us-east-1' } };
+                const deletionProtection = typeof body.deletion_protection === 'string' ? body.deletion_protection : 'disabled';
+                const tags = body.tags ?? {};
+                const host = mintHost(name);
+                await applyWrite('index', indexKey(name), { name, dimension, metric, vectorType, spec, deletionProtection, tags, host, ready: true, state: 'Ready' }, 'index.create', req);
+                const row = getRowById('index', indexKey(name), req.root);
+                return { status: 201, body: indexView(row) };
+            }
+            if (seg.length === 1 && method === 'GET') {
+                return { status: 200, body: { indexes: rowsOfType('index', req.root).map(indexView) } };
+            }
+            if (seg.length === 2 && method === 'GET') {
+                const row = getRowById('index', indexKey(idAt(1)), req.root);
+                if (!row)
+                    return controlError(404, 'NOT_FOUND', `Index ${idAt(1)} not found`);
+                return { status: 200, body: indexView(row) };
+            }
+            if (seg.length === 2 && method === 'PATCH') {
+                if (req.readOnly)
+                    return readOnlyRejection();
+                const row = getRowById('index', indexKey(idAt(1)), req.root);
+                if (!row)
+                    return controlError(404, 'NOT_FOUND', `Index ${idAt(1)} not found`);
+                // Dimension is immutable post-create (real-API invariant); reject an attempt to change it.
+                if (typeof body.dimension === 'number' && body.dimension !== row.dimension) {
+                    return controlError(400, 'INVALID_ARGUMENT', 'dimension cannot be changed after index creation');
+                }
+                const fields = {};
+                // WIRE key is snake_case here (ConfigureIndexRequestToJSON) — see indexView's header note.
+                if (body.deletion_protection !== undefined)
+                    fields.deletionProtection = body.deletion_protection;
+                if (body.tags !== undefined)
+                    fields.tags = { ...(row.tags ?? {}), ...body.tags };
+                if (body.spec !== undefined)
+                    fields.spec = { ...(row.spec ?? {}), ...body.spec };
+                await applyWrite('index', indexKey(idAt(1)), fields, 'index.configure', req);
+                const updated = getRowById('index', indexKey(idAt(1)), req.root);
+                return { status: 200, body: indexView(updated) };
+            }
+            if (seg.length === 2 && method === 'DELETE') {
+                if (req.readOnly)
+                    return readOnlyRejection();
+                const row = getRowById('index', indexKey(idAt(1)), req.root);
+                if (!row)
+                    return controlError(404, 'NOT_FOUND', `Index ${idAt(1)} not found`);
+                await applyWrite('index', indexKey(idAt(1)), { _deleted: true }, 'index.delete', req);
+                // Real Pinecone index deletion is asynchronous; 202 Accepted is the conventional REST
+                // reading (doc-UNVERIFIED exact code — ⚠6, spec-sources.json) — this twin deletes
+                // synchronously so a follow-up describe/list reflects it immediately either way.
+                return { status: 202, body: null };
+            }
+        }
+        // ── collections ── (a collection is a named, curated snapshot of an existing index; full
+        // point-in-time snapshot semantics are `pinecone.collections.from_index_snapshot` (todo) —
+        // this v1 slice models create/list/describe/delete as kernel-tracked metadata records.)
+        if (seg[0] === 'collections') {
+            if (seg.length === 1 && method === 'POST') {
+                if (req.readOnly)
+                    return readOnlyRejection();
+                const name = typeof body.name === 'string' ? body.name : undefined;
+                const source = typeof body.source === 'string' ? body.source : undefined;
+                if (!name || !source)
+                    return controlError(400, 'INVALID_ARGUMENT', 'name and source (an existing index name) are required to create a collection');
+                const sourceIndex = getRowById('index', indexKey(source), req.root);
+                if (!sourceIndex)
+                    return controlError(404, 'NOT_FOUND', `Index ${source} not found`);
+                if (getRowById('collection', collectionKey(name), req.root))
+                    return controlError(409, 'ALREADY_EXISTS', `Resource ${name} already exists`);
+                await applyWrite('collection', collectionKey(name), { name, dimension: sourceIndex.dimension, vectorCount: 0, size: 0, status: 'Ready', environment: 'twin-local' }, 'collection.create', req);
+                const row = getRowById('collection', collectionKey(name), req.root);
+                return { status: 201, body: collectionView(row) };
+            }
+            if (seg.length === 1 && method === 'GET') {
+                return { status: 200, body: { collections: rowsOfType('collection', req.root).map(collectionView) } };
+            }
+            if (seg.length === 2 && method === 'GET') {
+                const row = getRowById('collection', collectionKey(idAt(1)), req.root);
+                if (!row)
+                    return controlError(404, 'NOT_FOUND', `Collection ${idAt(1)} not found`);
+                return { status: 200, body: collectionView(row) };
+            }
+            if (seg.length === 2 && method === 'DELETE') {
+                if (req.readOnly)
+                    return readOnlyRejection();
+                const row = getRowById('collection', collectionKey(idAt(1)), req.root);
+                if (!row)
+                    return controlError(404, 'NOT_FOUND', `Collection ${idAt(1)} not found`);
+                await applyWrite('collection', collectionKey(idAt(1)), { _deleted: true }, 'collection.delete', req);
+                return { status: 202, body: null };
+            }
+        }
+        return controlError(404, 'NOT_FOUND', `Unrecognized control-plane route: ${method} ${path}`);
+    }
+    // ════════════════════════════════ DATA PLANE (per-index minted host) ══════════════════════
+    const indexName = req.index ?? recoverIndexFromHost(req.host);
+    if (!indexName)
+        return dataError(404, 5, 'Could not resolve an index for this request host');
+    const indexRow = getRowById('index', indexKey(indexName), req.root);
+    if (!indexRow)
+        return dataError(404, 5, `Index ${indexName} not found`);
+    const dimension = typeof indexRow.dimension === 'number' ? indexRow.dimension : undefined;
+    const metric = indexRow.metric ?? 'cosine';
+    function vectorRowsIn(namespace) {
+        const prefix = `vector:${indexName}::${namespace}::`;
+        return rowsOfType('vector', req.root)
+            .filter((r) => r.id.startsWith(prefix))
+            .map((r) => {
+            const parsed = parseVectorSuffix(r.id.slice('vector:'.length));
+            return { id: parsed.id, values: r.values ?? [], metadata: r.metadata ?? {} };
+        });
+    }
+    if (seg[0] === 'vectors' && seg[1] === 'upsert' && seg.length === 2 && method === 'POST') {
+        if (req.readOnly)
+            return readOnlyRejection();
+        const vectors = Array.isArray(body.vectors) ? body.vectors : [];
+        const namespace = typeof body.namespace === 'string' ? body.namespace : DEFAULT_NAMESPACE;
+        for (const v of vectors) {
+            const values = Array.isArray(v.values) ? v.values : [];
+            if (dimension !== undefined && values.length !== dimension) {
+                return dataError(400, 3, `Vector dimension ${values.length} does not match the dimension of the index ${dimension}`);
+            }
+        }
+        for (const v of vectors) {
+            const id = String(v.id ?? '');
+            if (!id)
+                continue;
+            await applyWrite('vector', vectorKey(indexName, namespace, id), { values: v.values ?? [], metadata: v.metadata ?? {} }, 'vector.upsert', req);
+        }
+        return { status: 200, body: { upsertedCount: vectors.length } };
+    }
+    if (seg[0] === 'vectors' && seg[1] === 'fetch' && seg.length === 2 && method === 'GET') {
+        const ids = (query.get('ids') ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+        const namespace = query.get('namespace') ?? DEFAULT_NAMESPACE;
+        const vectors = {};
+        for (const id of ids) {
+            const row = getRowById('vector', vectorKey(indexName, namespace, id), req.root);
+            // Unknown ids are simply OMITTED from the map (not a 404) — the docs.pinecone.io fetch-data
+            // guide describes the response as "a map between the fetched ids and the fetched vectors"
+            // with no documented error path for a missing id; doc-UNVERIFIED but structurally the
+            // natural reading of a map-shaped response, not a fabricated success (⚠5).
+            if (row)
+                vectors[id] = vectorView(indexName, namespace, id, row);
+        }
+        return { status: 200, body: { vectors, namespace } };
+    }
+    if (seg[0] === 'vectors' && seg[1] === 'update' && seg.length === 2 && method === 'POST') {
+        if (req.readOnly)
+            return readOnlyRejection();
+        const id = String(body.id ?? '');
+        const namespace = typeof body.namespace === 'string' ? body.namespace : DEFAULT_NAMESPACE;
+        if (!id)
+            return dataError(400, 3, 'id is required');
+        const existing = getRowById('vector', vectorKey(indexName, namespace, id), req.root);
+        if (existing) {
+            const fields = {};
+            if (body.values !== undefined)
+                fields.values = body.values;
+            if (body.setMetadata !== undefined)
+                fields.metadata = { ...(existing.metadata ?? {}), ...body.setMetadata };
+            await applyWrite('vector', vectorKey(indexName, namespace, id), fields, 'vector.update', req);
+        }
+        return { status: 200, body: {} };
+    }
+    if (seg[0] === 'vectors' && seg[1] === 'delete' && seg.length === 2 && method === 'POST') {
+        if (req.readOnly)
+            return readOnlyRejection();
+        const namespace = typeof body.namespace === 'string' ? body.namespace : DEFAULT_NAMESPACE;
+        if (body.deleteAll === true) {
+            // deleteAll only clears the TARGETED namespace, never the whole index (⚠ vectors.delete_all).
+            for (const v of vectorRowsIn(namespace))
+                await applyWrite('vector', vectorKey(indexName, namespace, v.id), { _deleted: true }, 'vector.delete', req);
+        }
+        else if (Array.isArray(body.ids)) {
+            for (const id of body.ids)
+                await applyWrite('vector', vectorKey(indexName, namespace, id), { _deleted: true }, 'vector.delete', req);
+        }
+        else if (body.filter !== undefined) {
+            // Real metadata-filter-driven delete (⚠ vectors.delete_by_filter) — never a name/keyword match.
+            for (const v of vectorRowsIn(namespace)) {
+                if (matchesFilter(v.metadata, body.filter)) {
+                    await applyWrite('vector', vectorKey(indexName, namespace, v.id), { _deleted: true }, 'vector.delete', req);
+                }
+            }
+        }
+        return { status: 200, body: {} };
+    }
+    if (seg[0] === 'vectors' && seg[1] === 'list' && seg.length === 2 && method === 'GET') {
+        const namespace = query.get('namespace') ?? DEFAULT_NAMESPACE;
+        const prefix = query.get('prefix') ?? '';
+        const limit = Number(query.get('limit') ?? '100') || 100;
+        const items = vectorRowsIn(namespace).filter((v) => v.id.startsWith(prefix)).slice(0, limit);
+        return { status: 200, body: { vectors: items.map((v) => ({ id: v.id })), namespace, pagination: { next: null } } };
+    }
+    if (path === '/query' && method === 'POST') {
+        const namespace = typeof body.namespace === 'string' ? body.namespace : DEFAULT_NAMESPACE;
+        const topK = typeof body.topK === 'number' ? body.topK : 10;
+        const includeValues = body.includeValues === true;
+        const includeMetadata = body.includeMetadata === true;
+        const filter = body.filter;
+        let queryVector;
+        let selfId;
+        if (Array.isArray(body.vector)) {
+            queryVector = body.vector;
+        }
+        else if (typeof body.id === 'string') {
+            selfId = body.id;
+            const self = getRowById('vector', vectorKey(indexName, namespace, body.id), req.root);
+            queryVector = self ? (self.values ?? []) : undefined;
+        }
+        if (!queryVector)
+            return { status: 200, body: { matches: [], namespace } };
+        const candidates = vectorRowsIn(namespace)
+            .filter((v) => v.id !== selfId) // query-by-id EXCLUDES the query vector itself (⚠ query.by_id
+            // self-inclusion — not settled by the fetched docs; modeled on the common ANN convention
+            // that a nearest-neighbor search never returns the query point as its own neighbor;
+            // doc-UNVERIFIED, recorded in spec-sources.json).
+            .filter((v) => matchesFilter(v.metadata, filter))
+            .map((v) => ({ id: v.id, score: scoreVector(metric, queryVector, v.values), values: v.values, metadata: v.metadata }));
+        const ranked = sortByScore(metric, candidates).slice(0, Math.max(0, topK));
+        const matches = ranked.map((m) => ({
+            id: m.id,
+            score: m.score,
+            ...(includeValues ? { values: m.values } : {}),
+            ...(includeMetadata ? { metadata: m.metadata } : {}),
+        }));
+        return { status: 200, body: { matches, namespace } };
+    }
+    if (path === '/describe_index_stats' && method === 'POST') {
+        const allVectors = rowsOfType('vector', req.root).filter((r) => r.id.startsWith(`vector:${indexName}::`));
+        const namespaces = {};
+        for (const r of allVectors) {
+            const parsed = parseVectorSuffix(r.id.slice('vector:'.length));
+            if (!parsed)
+                continue;
+            namespaces[parsed.namespace] = { vectorCount: (namespaces[parsed.namespace]?.vectorCount ?? 0) + 1 };
+        }
+        return {
+            status: 200,
+            body: {
+                namespaces,
+                dimension: dimension ?? null,
+                // No real pod/serverless infrastructure is provisioned — indexFullness has no organic
+                // meaning here, so it is
+                // always 0 rather than a fabricated non-zero figure.
+                indexFullness: 0,
+                totalVectorCount: allVectors.length,
+            },
+        };
+    }
+    return dataError(404, 5, `Unrecognized data-plane route: ${method} ${path}`);
+}
+// Endpoint inventory used by the conformance snapshot.
+export function pineconeTwinSnapshot() {
+    return {
+        resourceTypes: PINECONE_RESOURCE_TYPES,
+        implementedEndpoints: [
+            'POST /indexes', 'GET /indexes', 'GET /indexes/:name', 'PATCH /indexes/:name', 'DELETE /indexes/:name',
+            'POST /collections', 'GET /collections', 'GET /collections/:name', 'DELETE /collections/:name',
+            'POST /vectors/upsert', 'GET /vectors/fetch', 'POST /vectors/update', 'POST /vectors/delete', 'GET /vectors/list',
+            'POST /query', 'POST /describe_index_stats',
+        ],
+    };
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@volter/twin-pinecone",
+  "version": "0.1.0",
+  "description": "Local Pinecone twin for the vector-database surface: index/collection management (control plane), vector upsert/fetch/update/delete, REAL brute-force cosine/dotproduct/euclidean similarity query with a REAL Mongo-style metadata-filter evaluator, namespaces, and host-split control/data-plane routing, built on @volter/world-core.",
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/pinecone"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/pinecone#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-pinecone": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "@pinecone-database/pinecone": "^8.0.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-pinecone CLI: serve the KERNEL-BACKED Pinecone 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 { createPineconeTwinServer } from './pinecone-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 createPineconeTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`pinecone twin (vector database: indexes/collections/vectors + real similarity query)${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  const { checkPineconeConformance } = await import('./pinecone-conformance.ts');
+  const report = checkPineconeConformance();
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-pinecone serve|conformance [--port N] [--root DIR] [--read-only]\n');
+}