@volter/twin-pinecone 0.1.0

package/src/pinecone-twin.ts

@@ -0,0 +1,513 @@
+// 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, type PineconeFilter } from './pinecone-filter.ts';
+import { scoreVector, sortByScore, type PineconeMetric } from './pinecone-similarity.ts';
+
+const SERVICE = 'pinecone';
+const DEFAULT_NAMESPACE = '';
+
+export type PineconeRequest = {
+  method: string;
+  path: string;
+  body?: string;
+  headers?: Record<string, string>;
+  /** Effective request host (real Host header, or the SDK-integration-test's stashed original
+   *  target host — see pinecone-server.ts). Drives routePineconeSurface + data-plane index
+   *  recovery. */
+  host?: string;
+  /** Explicit data-plane index-name override — the twin's OWN verifies use this directly instead
+   *  of round-tripping a minted host through recoverIndexFromHost (spec §6's documented fallback). */
+  index?: string;
+  occurredAt?: string;
+  root?: string;
+  readOnly?: boolean;
+};
+export type PineconeResponse = { status: number; body: unknown; headers?: Record<string, string> };
+
+export const PINECONE_RESOURCE_TYPES = ['index', 'collection', 'vector'] as const;
+export type PineconeResourceType = typeof PINECONE_RESOURCE_TYPES[number];
+
+// ── 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: string): string {
+  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: string | undefined): string | undefined {
+  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;
+}
+
+export type PineconeSurface = 'control' | 'data';
+
+/** 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: { host?: string; path: string }): PineconeSurface {
+  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: number, code: number, message: string): PineconeResponse {
+  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: number, code: string, message: string): PineconeResponse {
+  return { status, body: { error: { code, message }, status } };
+}
+function readOnlyRejection(): PineconeResponse {
+  return { status: 405, body: { message: 'twin is read-only; omit readOnly to accept writes' } };
+}
+
+// ── body / helpers ────────────────────────────────────────────────────────────────────────────
+function parseBody(body?: string): Record<string, unknown> {
+  if (!body) return {};
+  try {
+    const v = JSON.parse(body);
+    return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+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 collectionKey(name: string): string {
+  return `collection:${name}`;
+}
+function vectorKey(index: string, namespace: string, id: string): string {
+  return `vector:${index}::${namespace}::${id}`;
+}
+function parseVectorSuffix(suffix: string): { index: string; namespace: string; id: string } | undefined {
+  const parts = suffix.split('::');
+  if (parts.length !== 3) return undefined;
+  return { index: parts[0]!, namespace: parts[1]!, id: parts[2]! };
+}
+
+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);
+}
+async function applyWrite(
+  subjectType: string,
+  subjectId: string,
+  fields: Record<string, unknown>,
+  operation: string,
+  req: PineconeRequest,
+): 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;
+}
+
+// ── object views (mirror the SDK's generated model field names exactly) ────────────────────────
+function indexView(r: Row): Record<string, unknown> {
+  // 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: Row): Record<string, unknown> {
+  // 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: string, namespace: string, id: string, r: Row): Record<string, unknown> {
+  return { id, values: r.values ?? [], metadata: r.metadata ?? {} };
+}
+
+// ── route handler ────────────────────────────────────────────────────────────────────────────
+export async function handlePineconeTwinRequest(req: PineconeRequest): Promise<PineconeResponse> {
+  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: number) => 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 as Record<string, string> | undefined) ?? {};
+        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: Record<string, unknown> = {};
+        // 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 as Record<string, unknown> | undefined ?? {}), ...(body.tags as Record<string, unknown>) };
+        if (body.spec !== undefined) fields.spec = { ...(row.spec as Record<string, unknown> | undefined ?? {}), ...(body.spec as Record<string, unknown>) };
+        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 as PineconeMetric | undefined) ?? 'cosine';
+
+  function vectorRowsIn(namespace: string): Array<{ id: string; values: number[]; metadata: Record<string, unknown> }> {
+    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 as number[]) ?? [], metadata: (r.metadata as Record<string, unknown>) ?? {} };
+      });
+  }
+
+  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 as Array<Record<string, unknown>>) : [];
+    const namespace = typeof body.namespace === 'string' ? body.namespace : DEFAULT_NAMESPACE;
+    for (const v of vectors) {
+      const values = Array.isArray(v.values) ? (v.values as number[]) : [];
+      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: Record<string, unknown> = {};
+    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: Record<string, unknown> = {};
+      if (body.values !== undefined) fields.values = body.values;
+      if (body.setMetadata !== undefined) fields.metadata = { ...(existing.metadata as Record<string, unknown> | undefined ?? {}), ...(body.setMetadata as Record<string, unknown>) };
+      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 as string[]) 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 as PineconeFilter)) {
+          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 as PineconeFilter | undefined;
+    let queryVector: number[] | undefined;
+    let selfId: string | undefined;
+    if (Array.isArray(body.vector)) {
+      queryVector = body.vector as number[];
+    } else if (typeof body.id === 'string') {
+      selfId = body.id;
+      const self = getRowById('vector', vectorKey(indexName, namespace, body.id), req.root);
+      queryVector = self ? ((self.values as number[]) ?? []) : 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: Record<string, { vectorCount: number }> = {};
+    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}`);
+}
+
+export type PineconeTwinSnapshot = {
+  resourceTypes: readonly PineconeResourceType[];
+  implementedEndpoints: readonly string[];
+};
+
+// Endpoint inventory used by the conformance snapshot.
+export function pineconeTwinSnapshot(): 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',
+    ],
+  };
+}