@volter/twin-pinecone 0.1.0

package/dist/src/pinecone-capabilities.js

@@ -0,0 +1,430 @@
+// Pinecone capability manifest — the EXPECTED REAL-PRODUCT SURFACE (the target), authored
+// top-down from the real Pinecone vector-database API — grounded against the installed
+// `@pinecone-database/pinecone` SDK's own generated TypeScript-fetch client (fetched read-only
+// via `npm pack` during this build — see spec-sources.json) for every route/field-name/status,
+// plus a handful of docs.pinecone.io reads for items the generated client doesn't settle
+// (annotated doc-UNVERIFIED inline where the docs didn't resolve them either). This is the
+// honest denominator: most entries start as `todo` and coverage reads LOW until the twin truly
+// reaches 100% of the real API. `verify()` (required to count as `done`) is ground truth and
+// drives the KERNEL-BACKED handler on a FRESH temp root — never a spawned mock.
+//
+// v1 SLICE (honesty, per the build spec): index/collection management + vector CRUD + REAL
+// brute-force similarity query (all 3 metrics) + REAL metadata filtering + namespaces +
+// describe_index_stats + host-split control/data-plane routing are modeled `done`. Sparse/hybrid
+// search, integrated inference/embedding, bulk import, backups/restore, pod-based scaling, full
+// collection-snapshot semantics, and gRPC-status-details error parity are left `todo` with
+// vendor-shaped failure (unmodeled route -> 404) — a deliberate v1 scope cut, not an oversight;
+// see README `## Coverage`.
+//
+// THE QUERY ENGINE IS A GENUINE STRONG DONE, NOT A STUB (the biggest structural difference from
+// this repo's generative twins): exact brute-force top-K over stored vector values is
+// deterministic, correct math — a faithful SUPERSET of Pinecone's real approximate-NN recall, not
+// a lesser placeholder. Integrated embedding (`createIndexForModel`, `/records/…`, `/embed`,
+// `/rerank`) is filed as todos. See pinecone-similarity.ts / pinecone-filter.ts headers + README.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { checkCapabilities, verifyBoundary } from '@volter/world-tooling';
+import { handlePineconeTwinRequest } from "./pinecone-twin.js";
+import { checkPineconeConformance } from "./pinecone-conformance.js";
+import { syncPineconeFromReal } from "./pinecone-connector.js";
+/** Run a sequence of real Pinecone-twin requests against an isolated root; return all responses. */
+async function withRoot(steps) {
+    const root = mkdtempSync(join(tmpdir(), 'pinecone-cap-'));
+    const h = (s) => handlePineconeTwinRequest({
+        method: s.m,
+        path: s.p,
+        body: s.b === undefined ? undefined : JSON.stringify(s.b),
+        root,
+        ...(s.index !== undefined ? { index: s.index } : {}),
+        ...(s.host !== undefined ? { host: s.host } : {}),
+        ...(s.readOnly !== undefined ? { readOnly: s.readOnly } : {}),
+    });
+    try {
+        return await verifyBoundary('pinecone.withRoot', () => steps(h));
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+const ok = (r) => r.status >= 200 && r.status < 300;
+const field = (r, k) => r.body?.[k];
+/** Create an index via the control plane; return its full response body (incl. `host`). */
+async function createIndex(h, name, dimension, metric = 'cosine') {
+    const r = await h({ m: 'POST', p: '/indexes', b: { name, dimension, metric, spec: { serverless: { cloud: 'aws', region: 'us-east-1' } } } });
+    return r.body;
+}
+const done = (id, area, title, dimension, tier, verify) => ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id, area, title, dimension, tier) => ({ id, area, title, dimension, tier, expected: 'todo' });
+export const PINECONE_CAPABILITIES = [
+    todo('pinecone.records.integrated_surface', 'vectors', 'Integrated-embedding surface: createIndexForModel and POST /records/{namespace}/upsert|search, embedding the supplied text into deterministic pseudo-vectors (POST /embed and /rerank are filed separately as pinecone.inference.*)', 'api', 'niche'),
+    // ── INDEXES (control plane) ─────────────────────────────────────────────────────────────
+    done('pinecone.indexes.create', 'indexes', 'POST /indexes creates an index -> 201 with dimension/metric/host/status.ready', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/indexes', b: { name: 'products', dimension: 4, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } } } });
+        return r.status === 201 && field(r, 'name') === 'products' && field(r, 'dimension') === 4 && field(r, 'metric') === 'cosine'
+            && typeof field(r, 'host') === 'string' && field(r, 'host').length > 0
+            && field(r, 'status')?.ready === true;
+    })),
+    done('pinecone.indexes.create_requires_name_dimension', 'indexes', 'POST /indexes without name or dimension -> 400 {error:{code,message},status}', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/indexes', b: { metric: 'cosine' } });
+        return r.status === 400 && typeof field(r, 'error')?.code === 'string' && field(r, 'status') === 400;
+    })),
+    done('pinecone.indexes.list', 'indexes', 'GET /indexes -> {indexes:[...]} incl. the created index', 'api', 'core', () => withRoot(async (h) => {
+        await createIndex(h, 'catalog', 3);
+        const r = await h({ m: 'GET', p: '/indexes' });
+        const names = field(r, 'indexes').map((i) => i.name);
+        return ok(r) && names.includes('catalog');
+    })),
+    done('pinecone.indexes.describe', 'indexes', 'GET /indexes/:name round-trips fields set at create', 'api', 'core', () => withRoot(async (h) => {
+        await createIndex(h, 'docs', 8, 'dotproduct');
+        const r = await h({ m: 'GET', p: '/indexes/docs' });
+        return ok(r) && field(r, 'name') === 'docs' && field(r, 'dimension') === 8 && field(r, 'metric') === 'dotproduct';
+    })),
+    done('pinecone.indexes.describe_missing_404', 'indexes', 'GET /indexes/:name for an unknown index -> 404 {error:{code,message}}', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/indexes/does-not-exist' });
+        return r.status === 404 && typeof field(r, 'error')?.message === 'string';
+    })),
+    done('pinecone.indexes.delete', 'indexes', 'DELETE /indexes/:name removes it (2xx), then describe -> 404', 'api', 'core', () => withRoot(async (h) => {
+        await createIndex(h, 'temp-index', 2);
+        const del = await h({ m: 'DELETE', p: '/indexes/temp-index' });
+        const get = await h({ m: 'GET', p: '/indexes/temp-index' });
+        return ok(del) && get.status === 404;
+    })),
+    done('pinecone.indexes.configure', 'indexes', 'PATCH /indexes/:name updates deletionProtection/tags; changing dimension is rejected (400)', 'api', 'common', () => withRoot(async (h) => {
+        await createIndex(h, 'configurable', 4);
+        const patch = await h({ m: 'PATCH', p: '/indexes/configurable', b: { deletion_protection: 'enabled', tags: { env: 'test' } } });
+        const dimAttempt = await h({ m: 'PATCH', p: '/indexes/configurable', b: { dimension: 99 } });
+        return ok(patch) && field(patch, 'deletion_protection') === 'enabled' && field(patch, 'tags')?.env === 'test' && dimAttempt.status === 400;
+    })),
+    done('pinecone.indexes.host_deterministic', 'indexes', 'The minted per-index host is stable across repeated describes for the same (index,root)', 'api', 'common', () => withRoot(async (h) => {
+        await createIndex(h, 'stable-host', 4);
+        const a = await h({ m: 'GET', p: '/indexes/stable-host' });
+        const b = await h({ m: 'GET', p: '/indexes/stable-host' });
+        const hostA = field(a, 'host');
+        return ok(a) && typeof hostA === 'string' && hostA.length > 0 && hostA === field(b, 'host') && hostA.includes('stable-host');
+    })),
+    // ── COLLECTIONS (control plane) ─────────────────────────────────────────────────────────
+    done('pinecone.collections.create', 'collections', 'POST /collections {name,source} snapshots an existing index\'s dimension -> 201 (missing source -> 400)', 'api', 'common', () => withRoot(async (h) => {
+        await createIndex(h, 'src-index', 6);
+        const r = await h({ m: 'POST', p: '/collections', b: { name: 'snap-1', source: 'src-index' } });
+        const missing = await h({ m: 'POST', p: '/collections', b: { name: 'snap-bad' } });
+        return r.status === 201 && field(r, 'name') === 'snap-1' && field(r, 'dimension') === 6 && missing.status === 400;
+    })),
+    done('pinecone.collections.list', 'collections', 'GET /collections -> {collections:[...]} incl. the created collection', 'api', 'niche', () => withRoot(async (h) => {
+        await createIndex(h, 'src-index-2', 4);
+        await h({ m: 'POST', p: '/collections', b: { name: 'listed-collection', source: 'src-index-2' } });
+        const r = await h({ m: 'GET', p: '/collections' });
+        return ok(r) && field(r, 'collections').some((c) => c.name === 'listed-collection');
+    })),
+    done('pinecone.collections.describe', 'collections', 'GET /collections/:name round-trips (404 negative)', 'api', 'niche', () => withRoot(async (h) => {
+        await createIndex(h, 'src-index-3', 4);
+        await h({ m: 'POST', p: '/collections', b: { name: 'described-collection', source: 'src-index-3' } });
+        const r = await h({ m: 'GET', p: '/collections/described-collection' });
+        const missing = await h({ m: 'GET', p: '/collections/does-not-exist' });
+        return ok(r) && field(r, 'name') === 'described-collection' && missing.status === 404;
+    })),
+    done('pinecone.collections.delete', 'collections', 'DELETE /collections/:name removes it (2xx), then describe -> 404', 'api', 'niche', () => withRoot(async (h) => {
+        await createIndex(h, 'src-index-4', 4);
+        await h({ m: 'POST', p: '/collections', b: { name: 'deletable-collection', source: 'src-index-4' } });
+        const del = await h({ m: 'DELETE', p: '/collections/deletable-collection' });
+        const get = await h({ m: 'GET', p: '/collections/deletable-collection' });
+        return ok(del) && get.status === 404;
+    })),
+    // ── VECTORS (data plane) ────────────────────────────────────────────────────────────────
+    done('pinecone.vectors.upsert', 'vectors', 'POST /vectors/upsert -> {upsertedCount}; fetch round-trips values+metadata', 'api', 'core', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'upsert-idx', 3);
+        const up = await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { vectors: [{ id: 'v1', values: [1, 2, 3], metadata: { color: 'red' } }, { id: 'v2', values: [4, 5, 6] }] } });
+        const fetched = await h({ index: idx.name, m: 'GET', p: '/vectors/fetch?ids=v1,v2' });
+        const vectors = field(fetched, 'vectors');
+        return field(up, 'upsertedCount') === 2 && JSON.stringify(vectors.v1.values) === JSON.stringify([1, 2, 3]) && vectors.v1.metadata.color === 'red' && JSON.stringify(vectors.v2.values) === JSON.stringify([4, 5, 6]);
+    })),
+    done('pinecone.vectors.upsert_dimension_mismatch', 'vectors', 'Upserting a vector whose values.length != index dimension -> 400 {code:3,message}', 'api', 'common', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'dim-idx', 5);
+        const r = await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { vectors: [{ id: 'bad', values: [1, 2] }] } });
+        return r.status === 400 && field(r, 'code') === 3 && typeof field(r, 'message') === 'string';
+    })),
+    done('pinecone.vectors.fetch', 'vectors', 'GET /vectors/fetch returns only the requested, existing ids with exact values', 'api', 'core', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'fetch-idx', 2);
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { vectors: [{ id: 'a', values: [1, 1] }, { id: 'b', values: [2, 2] }] } });
+        const r = await h({ index: idx.name, m: 'GET', p: '/vectors/fetch?ids=a' });
+        const vectors = field(r, 'vectors');
+        return ok(r) && Object.keys(vectors).length === 1 && JSON.stringify(vectors.a.values) === JSON.stringify([1, 1]);
+    })),
+    done('pinecone.vectors.fetch_unknown_empty', 'vectors', 'GET /vectors/fetch for unknown ids -> 200 {vectors:{}} (never a 404)', 'api', 'common', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'fetch-empty-idx', 2);
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { vectors: [{ id: 'exists', values: [1, 1] }] } });
+        const r = await h({ index: idx.name, m: 'GET', p: '/vectors/fetch?ids=nope-1,nope-2' });
+        return r.status === 200 && Object.keys(field(r, 'vectors')).length === 0;
+    })),
+    done('pinecone.vectors.update', 'vectors', 'POST /vectors/update merges setMetadata and replaces values on an existing vector', 'api', 'common', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'update-idx', 2);
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { vectors: [{ id: 'u1', values: [1, 1], metadata: { a: 1 } }] } });
+        await h({ index: idx.name, m: 'POST', p: '/vectors/update', b: { id: 'u1', values: [9, 9], setMetadata: { b: 2 } } });
+        const r = await h({ index: idx.name, m: 'GET', p: '/vectors/fetch?ids=u1' });
+        const v = field(r, 'vectors').u1;
+        return JSON.stringify(v.values) === JSON.stringify([9, 9]) && v.metadata.a === 1 && v.metadata.b === 2;
+    })),
+    done('pinecone.vectors.delete_by_ids', 'vectors', 'POST /vectors/delete {ids} removes exactly those ids', 'api', 'core', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'del-ids-idx', 2);
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { vectors: [{ id: 'keep', values: [1, 1] }, { id: 'gone', values: [2, 2] }] } });
+        await h({ index: idx.name, m: 'POST', p: '/vectors/delete', b: { ids: ['gone'] } });
+        const r = await h({ index: idx.name, m: 'GET', p: '/vectors/fetch?ids=keep,gone' });
+        const vectors = field(r, 'vectors');
+        return Object.keys(vectors).length === 1 && !!vectors.keep;
+    })),
+    done('pinecone.vectors.delete_all', 'vectors', 'POST /vectors/delete {deleteAll:true} clears ONLY the targeted namespace, not the whole index', 'api', 'common', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'del-all-idx', 2);
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { namespace: 'ns-a', vectors: [{ id: 'x', values: [1, 1] }] } });
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { namespace: 'ns-b', vectors: [{ id: 'y', values: [2, 2] }] } });
+        await h({ index: idx.name, m: 'POST', p: '/vectors/delete', b: { namespace: 'ns-a', deleteAll: true } });
+        const listA = await h({ index: idx.name, m: 'GET', p: '/vectors/list?namespace=ns-a' });
+        const listB = await h({ index: idx.name, m: 'GET', p: '/vectors/list?namespace=ns-b' });
+        return field(listA, 'vectors').length === 0 && field(listB, 'vectors').length === 1;
+    })),
+    done('pinecone.vectors.delete_by_filter', 'vectors', 'POST /vectors/delete {filter} removes only vectors whose metadata matches the REAL filter evaluator', 'api', 'common', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'del-filter-idx', 2);
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { vectors: [{ id: 'stale', values: [1, 1], metadata: { status: 'stale' } }, { id: 'fresh', values: [2, 2], metadata: { status: 'fresh' } }] } });
+        await h({ index: idx.name, m: 'POST', p: '/vectors/delete', b: { filter: { status: 'stale' } } });
+        const r = await h({ index: idx.name, m: 'GET', p: '/vectors/fetch?ids=stale,fresh' });
+        const vectors = field(r, 'vectors');
+        return Object.keys(vectors).length === 1 && !!vectors.fresh;
+    })),
+    done('pinecone.vectors.list', 'vectors', 'GET /vectors/list returns ids in the namespace, filterable by prefix', 'api', 'common', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'list-idx', 2);
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { vectors: [{ id: 'doc-1', values: [1, 1] }, { id: 'doc-2', values: [2, 2] }, { id: 'other-1', values: [3, 3] }] } });
+        const r = await h({ index: idx.name, m: 'GET', p: '/vectors/list?prefix=doc-' });
+        const ids = field(r, 'vectors').map((v) => v.id).sort();
+        return JSON.stringify(ids) === JSON.stringify(['doc-1', 'doc-2']);
+    })),
+    // ── QUERY (data plane — REAL similarity + REAL filter; the pack's signature strength) ────
+    done('pinecone.query.by_vector_cosine', 'query', 'POST /query with metric=cosine ranks a small-magnitude PERFECTLY-aligned vector above a larger-magnitude, less-aligned one', 'api', 'core', () => withRoot(async (h) => {
+        // Crafted so cosine and dotproduct DISAGREE on the winner (see query.metric_dotproduct):
+        // 'a'=[0.5,0] is perfectly aligned with Q=[1,0] (cosine=1.0) but has LOW dot product (0.5);
+        // 'b'=[2,1.9] is less aligned (cosine~=0.72) but has HIGH dot product (2.0). Under cosine,
+        // 'a' must win — a metric-ignoring (dotproduct-only) implementation would return 'b' first
+        // and this assertion would fail.
+        const idx = await createIndex(h, 'cosine-idx', 2, 'cosine');
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { vectors: [{ id: 'a', values: [0.5, 0] }, { id: 'b', values: [2, 1.9] }] } });
+        const r = await h({ index: idx.name, m: 'POST', p: '/query', b: { vector: [1, 0], topK: 2 } });
+        const matches = field(r, 'matches');
+        return ok(r) && matches.length === 2 && matches[0].id === 'a' && matches[0].score > matches[1].score;
+    })),
+    done('pinecone.query.by_id', 'query', 'POST /query with an id (instead of a vector) queries using that vector\'s own values and EXCLUDES it from the results (⚠ doc-UNVERIFIED convention)', 'api', 'common', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'by-id-idx', 2, 'cosine');
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { vectors: [{ id: 'origin', values: [1, 0] }, { id: 'neighbor', values: [1, 0.01] }] } });
+        const r = await h({ index: idx.name, m: 'POST', p: '/query', b: { id: 'origin', topK: 5 } });
+        const matches = field(r, 'matches');
+        return ok(r) && matches.length === 1 && matches[0].id === 'neighbor';
+    })),
+    done('pinecone.query.metric_dotproduct', 'query', 'POST /query with metric=dotproduct ranks the SAME crafted pair in the OPPOSITE order from cosine', 'api', 'core', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'dot-idx', 2, 'dotproduct');
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { vectors: [{ id: 'a', values: [0.5, 0] }, { id: 'b', values: [2, 1.9] }] } });
+        const r = await h({ index: idx.name, m: 'POST', p: '/query', b: { vector: [1, 0], topK: 2 } });
+        const matches = field(r, 'matches');
+        // 'b' wins on raw dot product (2.0 > 0.5) — the OPPOSITE winner from
+        // pinecone.query.by_vector_cosine's cosine ranking over the identical vector set. A metric-
+        // ignoring implementation (always ranking by cosine, or ignoring metric entirely) fails here.
+        return ok(r) && matches[0].id === 'b' && matches[0].score === 2;
+    })),
+    done('pinecone.query.metric_euclidean', 'query', 'POST /query with metric=euclidean sorts ASCENDING by squared L2 distance (lower = closer, ⚠ doc-UNVERIFIED exact wire score)', 'api', 'common', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'euclid-idx', 2, 'euclidean');
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { vectors: [{ id: 'near', values: [1, 0] }, { id: 'far', values: [3, 0] }] } });
+        const r = await h({ index: idx.name, m: 'POST', p: '/query', b: { vector: [0, 0], topK: 2 } });
+        const matches = field(r, 'matches');
+        return ok(r) && matches[0].id === 'near' && matches[0].score === 1 && matches[1].id === 'far' && matches[1].score === 9;
+    })),
+    done('pinecone.query.topk_deterministic', 'query', 'Two identical queries return identical top-K; a different topK returns a genuinely different result', 'api', 'core', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'topk-idx', 2, 'cosine');
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { vectors: [{ id: 'p', values: [1, 0] }, { id: 'q', values: [0.9, 0.1] }, { id: 'z', values: [-1, 0] }] } });
+        const call1 = await h({ index: idx.name, m: 'POST', p: '/query', b: { vector: [1, 0], topK: 1 } });
+        const call2 = await h({ index: idx.name, m: 'POST', p: '/query', b: { vector: [1, 0], topK: 1 } });
+        const call3 = await h({ index: idx.name, m: 'POST', p: '/query', b: { vector: [1, 0], topK: 2 } });
+        const m1 = field(call1, 'matches').map((m) => m.id);
+        const m2 = field(call2, 'matches').map((m) => m.id);
+        const m3 = field(call3, 'matches').map((m) => m.id);
+        return JSON.stringify(m1) === JSON.stringify(m2) && m1.length === 1 && m3.length === 2 && JSON.stringify(m1) !== JSON.stringify(m3);
+    })),
+    done('pinecone.query.include_flags', 'query', 'includeValues/includeMetadata default false; setting them true adds those fields to each match', 'api', 'common', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'include-idx', 2, 'cosine');
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { vectors: [{ id: 'v', values: [1, 0], metadata: { k: 'v' } }] } });
+        const bare = await h({ index: idx.name, m: 'POST', p: '/query', b: { vector: [1, 0], topK: 1 } });
+        const full = await h({ index: idx.name, m: 'POST', p: '/query', b: { vector: [1, 0], topK: 1, includeValues: true, includeMetadata: true } });
+        const bareMatch = field(bare, 'matches')[0];
+        const fullMatch = field(full, 'matches')[0];
+        return bareMatch.values === undefined && bareMatch.metadata === undefined && JSON.stringify(fullMatch.values) === JSON.stringify([1, 0]) && fullMatch.metadata.k === 'v';
+    })),
+    done('pinecone.query.filter_eq', 'query', 'A metadata filter EXCLUDES the otherwise-nearest vector, changing which match wins', 'api', 'core', () => withRoot(async (h) => {
+        // 'near' is the TRUE nearest neighbor to the query vector but is filtered out by metadata —
+        // a filter-ignoring implementation would return 'near' and this assertion fails.
+        const idx = await createIndex(h, 'filter-eq-idx', 2, 'cosine');
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { vectors: [{ id: 'near', values: [1, 0], metadata: { category: 'excluded' } }, { id: 'far', values: [0.1, 1], metadata: { category: 'included' } }] } });
+        const r = await h({ index: idx.name, m: 'POST', p: '/query', b: { vector: [1, 0], topK: 1, filter: { category: 'included' } } });
+        const matches = field(r, 'matches');
+        return ok(r) && matches.length === 1 && matches[0].id === 'far';
+    })),
+    done('pinecone.query.filter_operators', 'query', '$gt/$gte/$lt/$lte/$in/$nin each select the correct subset over numeric/enum metadata', 'api', 'common', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'filter-ops-idx', 2, 'cosine');
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { vectors: [
+                    { id: 'lo', values: [1, 0], metadata: { score: 1, tag: 'a' } },
+                    { id: 'mid', values: [1, 0], metadata: { score: 5, tag: 'b' } },
+                    { id: 'hi', values: [1, 0], metadata: { score: 10, tag: 'c' } },
+                ] } });
+        const gt = await h({ index: idx.name, m: 'POST', p: '/query', b: { vector: [1, 0], topK: 10, filter: { score: { $gt: 3 } } } });
+        const lte = await h({ index: idx.name, m: 'POST', p: '/query', b: { vector: [1, 0], topK: 10, filter: { score: { $lte: 5 } } } });
+        const inOp = await h({ index: idx.name, m: 'POST', p: '/query', b: { vector: [1, 0], topK: 10, filter: { tag: { $in: ['a', 'c'] } } } });
+        const nin = await h({ index: idx.name, m: 'POST', p: '/query', b: { vector: [1, 0], topK: 10, filter: { tag: { $nin: ['a', 'c'] } } } });
+        const ids = (r) => field(r, 'matches').map((m) => m.id).sort();
+        return JSON.stringify(ids(gt)) === JSON.stringify(['hi', 'mid']) && JSON.stringify(ids(lte)) === JSON.stringify(['lo', 'mid']) && JSON.stringify(ids(inOp)) === JSON.stringify(['hi', 'lo']) && JSON.stringify(ids(nin)) === JSON.stringify(['mid']);
+    })),
+    done('pinecone.query.filter_and_or', 'query', '$and requires every clause; $or requires at least one', 'api', 'common', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'filter-andor-idx', 2, 'cosine');
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { vectors: [
+                    { id: 'both', values: [1, 0], metadata: { category: 'x', score: 5 } },
+                    { id: 'cat-only', values: [1, 0], metadata: { category: 'x', score: 1 } },
+                    { id: 'score-only', values: [1, 0], metadata: { category: 'y', score: 9 } },
+                    { id: 'neither', values: [1, 0], metadata: { category: 'y', score: 1 } },
+                ] } });
+        const and = await h({ index: idx.name, m: 'POST', p: '/query', b: { vector: [1, 0], topK: 10, filter: { $and: [{ category: 'x' }, { score: { $gte: 5 } }] } } });
+        const or = await h({ index: idx.name, m: 'POST', p: '/query', b: { vector: [1, 0], topK: 10, filter: { $or: [{ category: 'x' }, { score: { $gte: 9 } }] } } });
+        const ids = (r) => field(r, 'matches').map((m) => m.id).sort();
+        return JSON.stringify(ids(and)) === JSON.stringify(['both']) && JSON.stringify(ids(or)) === JSON.stringify(['both', 'cat-only', 'score-only']);
+    })),
+    // ── NAMESPACES / STATS ──────────────────────────────────────────────────────────────────
+    done('pinecone.namespaces.isolation', 'namespaces', 'The same vector id in two namespaces holds independent values; fetch/list never leak across namespaces', 'api', 'core', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'ns-idx', 2);
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { namespace: 'tenant-a', vectors: [{ id: 'shared-id', values: [1, 1] }] } });
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { namespace: 'tenant-b', vectors: [{ id: 'shared-id', values: [2, 2] }] } });
+        const a = await h({ index: idx.name, m: 'GET', p: '/vectors/fetch?ids=shared-id&namespace=tenant-a' });
+        const b = await h({ index: idx.name, m: 'GET', p: '/vectors/fetch?ids=shared-id&namespace=tenant-b' });
+        const listA = await h({ index: idx.name, m: 'GET', p: '/vectors/list?namespace=tenant-a' });
+        const va = field(a, 'vectors')['shared-id'];
+        const vb = field(b, 'vectors')['shared-id'];
+        return JSON.stringify(va.values) === JSON.stringify([1, 1]) && JSON.stringify(vb.values) === JSON.stringify([2, 2]) && field(listA, 'vectors').length === 1;
+    })),
+    done('pinecone.stats.describe_index_stats', 'stats', 'POST /describe_index_stats aggregates per-namespace vectorCount + totalVectorCount + dimension', 'api', 'common', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'stats-idx', 3);
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { namespace: 'x', vectors: [{ id: '1', values: [1, 1, 1] }, { id: '2', values: [2, 2, 2] }] } });
+        await h({ index: idx.name, m: 'POST', p: '/vectors/upsert', b: { namespace: 'y', vectors: [{ id: '3', values: [3, 3, 3] }] } });
+        const r = await h({ index: idx.name, m: 'POST', p: '/describe_index_stats' });
+        const namespaces = field(r, 'namespaces');
+        return ok(r) && namespaces.x.vectorCount === 2 && namespaces.y.vectorCount === 1 && field(r, 'totalVectorCount') === 3 && field(r, 'dimension') === 3;
+    })),
+    // ── HOST-SPLIT ROUTER ────────────────────────────────────────────────────────────────────
+    done('pinecone.control_plane.host_split_routing', 'control_plane', 'A request with host=api.pinecone.io (or no host, /indexes|/collections path fallback) resolves to the control plane and its {error:{code,message},status} envelope', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/indexes/does-not-exist', host: 'api.pinecone.io' });
+        return r.status === 404 && typeof field(r, 'error')?.code === 'string' && field(r, 'status') === 404;
+    })),
+    done('pinecone.data_plane.host_split_routing', 'data_plane', 'A request Host matching a minted per-index host round-trips to that index\'s data plane WITHOUT any explicit index field', 'api', 'core', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'host-routed-idx', 2);
+        const mintedHost = idx.host;
+        if (!mintedHost)
+            return false;
+        const upsert = await h({ m: 'POST', p: '/vectors/upsert', host: mintedHost, b: { vectors: [{ id: 'v1', values: [1, 0] }] } });
+        const fetched = await h({ m: 'GET', p: '/vectors/fetch?ids=v1', host: mintedHost });
+        return ok(upsert) && ok(fetched) && !!field(fetched, 'vectors').v1;
+    })),
+    // ── SAFETY / HONESTY / STATE ─────────────────────────────────────────────────────────────
+    done('pinecone.read_only.rejects_writes', 'safety', 'readOnly mode rejects a write (create index -> 405) but allows reads AND read-shaped POSTs (query)', 'api', 'common', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'ro-idx', 2);
+        const write = await h({ m: 'POST', p: '/indexes', readOnly: true, b: { name: 'blocked', dimension: 2 } });
+        const readList = await h({ m: 'GET', p: '/indexes', readOnly: true });
+        const readQuery = await h({ index: idx.name, m: 'POST', p: '/query', readOnly: true, b: { vector: [1, 0], topK: 1 } });
+        return write.status === 405 && readList.status === 200 && readQuery.status === 200;
+    })),
+    done('pinecone.unmodeled_route.404', 'safety', 'An unmodeled control-plane route returns Pinecone\'s error envelope (never a fabricated success)', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/totally-unknown-resource', host: 'api.pinecone.io' });
+        return r.status === 404 && typeof field(r, 'error')?.message === 'string';
+    })),
+    done('pinecone.state.kernel_persisted', 'state', 'State is kernel-folded — a vector upserted in one call is visible, with correct values, in the next', 'api', 'core', () => withRoot(async (h) => {
+        const idx = await createIndex(h, 'persist-idx', 2);
+        const name = idx.name;
+        // a dead twin returns {} — the name must be a REAL non-empty string first, or the final
+        // comparison is vacuous.
+        if (typeof name !== 'string' || name.length === 0)
+            return false;
+        await h({ index: name, m: 'POST', p: '/vectors/upsert', b: { vectors: [{ id: 'persisted', values: [7, 8] }] } });
+        const r = await h({ index: name, m: 'GET', p: '/vectors/fetch?ids=persisted' });
+        return JSON.stringify(field(r, 'vectors').persisted?.values) === JSON.stringify([7, 8]);
+    })),
+    // ── CONFORMANCE / CONNECTOR ──────────────────────────────────────────────────────────────
+    done('pinecone.conformance.snapshot', 'conformance', 'Conformance snapshot covers every resource type + the core control/data-plane endpoints', 'api', 'common', () => {
+        const report = checkPineconeConformance();
+        return report.ok && report.endpointsChecked >= 15 && report.resourceTypesChecked === 3;
+    }),
+    done('pinecone.connector.sync.entrypoint', 'connector', 'syncPineconeFromReal folds indexes + vectors into the twin, idempotent, read-through-handler', 'connector', 'core', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'pinecone-conn-'));
+        try {
+            const client = {
+                listIndexes: async () => ({ indexes: [{ name: 'real-index', dimension: 3, metric: 'cosine' }] }),
+                listVectors: async () => ({ vectors: [{ index: 'real-index', namespace: '', id: 'real-vec-1', values: [1, 2, 3], metadata: { source: 'real' } }] }),
+            };
+            const first = await syncPineconeFromReal(client, { root, budgetOptions: { root } });
+            if (first.observed !== 2 || first.deltasAppended < 2)
+                return false;
+            // a re-pull of identical state is a no-op (shadow-diff dedup) -> 0 deltas appended
+            const second = await syncPineconeFromReal(client, { root, budgetOptions: { root } });
+            if (second.deltasAppended !== 0)
+                return false;
+            // the pulled data is now visible via the twin handler (real fold, not a count)
+            const described = await handlePineconeTwinRequest({ method: 'GET', path: '/indexes/real-index', host: 'api.pinecone.io', root });
+            const fetched = await handlePineconeTwinRequest({ method: 'GET', path: '/vectors/fetch?ids=real-vec-1', index: 'real-index', root });
+            return described.status === 200 && described.body.dimension === 3 && JSON.stringify(fetched.body.vectors['real-vec-1']?.values) === JSON.stringify([1, 2, 3]);
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    }),
+    done('pinecone.connector.empty_client', 'connector', 'syncPineconeFromReal with an empty client observes nothing', 'connector', 'common', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'pinecone-conn-empty-'));
+        try {
+            const result = await syncPineconeFromReal({}, { root, budgetOptions: { root } });
+            return result.observed === 0 && result.deltasAppended === 0;
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    }),
+    // ── TODO: the rest of the Pinecone v1 surface (honest denominator) ──────────────────────
+    todo('pinecone.vectors.upsert_sparse', 'vectors', 'Sparse vector values on upsert (hybrid-search sparse-dense records)', 'api', 'common'),
+    todo('pinecone.query.sparse_hybrid', 'query', 'Hybrid dense+sparse query scoring', 'api', 'common'),
+    todo('pinecone.query.rerank', 'query', 'Query-time result reranking against a rerank model', 'api', 'common'),
+    todo('pinecone.filters.exists', 'filters', '$exists metadata-filter operator', 'api', 'common'),
+    todo('pinecone.filters.deep_nested', 'filters', 'Deep dot-path / nested-object metadata filter addressing', 'api', 'common'),
+    todo('pinecone.filters.null_semantics', 'filters', 'Explicit null-value metadata comparison edge semantics', 'api', 'niche'),
+    todo('pinecone.indexes.configure_pods', 'indexes', 'PATCH /indexes/:name pod-based spec.pod.replicas/podType scaling', 'api', 'common'),
+    todo('pinecone.indexes.pod_types', 'indexes', 'The real pod-type catalog (p1/p2/s1 etc.) for pod-based indexes', 'api', 'niche'),
+    todo('pinecone.indexes.serverless_vs_pod', 'indexes', 'Full serverless-vs-pod spec validation/branching on create', 'api', 'common'),
+    todo('pinecone.indexes.deletion_protection_enforced', 'indexes', 'deletionProtection:"enabled" actually BLOCKS DELETE /indexes/:name (currently stored but not enforced)', 'api', 'common'),
+    todo('pinecone.backups.create_list_restore', 'indexes', 'POST /indexes/:name/backups + GET /backups + create-index-from-backup', 'api', 'common'),
+    todo('pinecone.collections.from_index_snapshot', 'collections', 'A collection genuinely snapshots the SOURCE index\'s vector data at create time (v1: metadata-only record)', 'api', 'common'),
+    todo('pinecone.collections.restore', 'collections', 'POST /backups/{id}/create-index-style restore-a-collection-into-an-index flow', 'api', 'common'),
+    todo('pinecone.bulk.import_start', 'vectors', 'POST /bulk/imports starts an async bulk import job from object storage', 'api', 'common'),
+    todo('pinecone.bulk.import_status', 'vectors', 'GET /bulk/imports/:id status polling', 'api', 'common'),
+    todo('pinecone.bulk.import_list_cancel', 'vectors', 'GET /bulk/imports (list) + DELETE /bulk/imports/:id (cancel)', 'api', 'niche'),
+    todo('pinecone.inference.embed', 'vectors', 'POST /embed — integrated embedding of raw text into vectors', 'api', 'common'),
+    todo('pinecone.inference.rerank', 'query', 'POST /rerank — integrated cross-encoder reranking of a result set', 'api', 'common'),
+    todo('pinecone.namespaces.list', 'namespaces', 'GET /namespaces — enumerate namespaces as their own resource (today: derived only via describe_index_stats)', 'api', 'common'),
+    todo('pinecone.namespaces.delete', 'namespaces', 'DELETE /namespaces/:name — delete an entire namespace as its own operation', 'api', 'common'),
+    todo('pinecone.vectors.list_pagination_token', 'pagination', 'Real opaque paginationToken cursor fidelity on GET /vectors/list (twin always returns null)', 'api', 'common'),
+    todo('pinecone.query.top_k_max_limit', 'query', 'Real topK upper-bound enforcement (10000 dense / 1000 with values, per the docs) -> 400 over the limit', 'api', 'niche'),
+    todo('pinecone.errors.grpc_status_details', 'errors', 'Full gRPC-gateway `details[]` payload parity on data-plane errors (twin always returns [])', 'api', 'common'),
+    todo('pinecone.errors.control_plane_shape', 'errors', 'Independently confirm the exact control-plane error envelope against a live account (currently doc-UNVERIFIED, modeled per the build spec)', 'api', 'common'),
+    todo('pinecone.auth.api_key_401_parity', 'auth', 'Missing/invalid Api-Key header -> 401 parity (twin fakes auth locally; every request is accepted)', 'api', 'niche'),
+    todo('pinecone.auth.project_scoping', 'auth', 'Multi-project / multi-org API-key scoping and cross-project 403s', 'api', 'niche'),
+    todo('pinecone.stats.index_fullness_real', 'stats', 'A non-zero, organically-computed indexFullness (today: always 0 — no real infrastructure)', 'api', 'niche'),
+    todo('pinecone.connector.push', 'connector', 'Push locally-created indexes/vectors against the real API', 'connector', 'common'),
+    todo('pinecone.connector.pull_collections', 'connector', 'Connector: pull collections from the real account', 'connector', 'common'),
+    todo('pinecone.fixtures.seed', 'connector', 'Seed indexes/vectors from fixtures', 'connector', 'niche'),
+    // ── NITs filed from the skeptic review of the commit-3 build (non-blocking; current behavior
+    //    stays as-is unchanged here — just tracked so a future pass makes a deliberate choice) ──
+    todo('pinecone.query.dimension_mismatch', 'query', 'squaredEuclideanDistance silently zero-pads mismatched-length query/candidate vectors instead of rejecting the query (pinecone-similarity.ts) — real Pinecone rejects a query vector whose length != index dimension; verify + fix or document as intentional leniency', 'api', 'niche'),
+    todo('pinecone.vectors.update_nonexistent', 'vectors', 'POST /vectors/update against a non-existent vector id returns 200 silently instead of a real vendor-shaped error/no-op signal — confirm real Pinecone behavior and match it', 'api', 'niche'),
+];
+export const PINECONE_AREAS = [
+    'indexes', 'collections', 'vectors', 'query', 'namespaces', 'filters', 'stats',
+    'control_plane', 'data_plane', 'auth', 'pagination', 'errors', 'connector', 'conformance',
+    'safety', 'state',
+];
+export async function pineconeCapabilities() {
+    return checkCapabilities('pinecone', PINECONE_CAPABILITIES);
+}

package/dist/src/pinecone-conformance.d.ts

@@ -0,0 +1,7 @@
+export type PineconeConformanceReport = {
+    ok: boolean;
+    endpointsChecked: number;
+    resourceTypesChecked: number;
+    violations: string[];
+};
+export declare function checkPineconeConformance(): PineconeConformanceReport;

package/dist/src/pinecone-conformance.js

@@ -0,0 +1,32 @@
+// Pinecone conformance (dev-only; lazy-imported by the CLI, NEVER from index.ts/runtime — E2).
+// Checks the twin's endpoint/resource inventory against the modeled Pinecone surface. Like
+// replicate/fal, this is a self-referential snapshot check (against the twin's own declared
+// inventory), not a systematic per-resource spec-diff — see docs/contributing/conformance.md's "2 spec" column note.
+import { pineconeTwinSnapshot, PINECONE_RESOURCE_TYPES } from "./pinecone-twin.js";
+export function checkPineconeConformance() {
+    const snapshot = pineconeTwinSnapshot();
+    const violations = [];
+    const stemFor = {
+        index: '/indexes',
+        collection: '/collections',
+        vector: '/vectors',
+    };
+    for (const type of PINECONE_RESOURCE_TYPES) {
+        const stem = stemFor[type];
+        if (!stem || !snapshot.implementedEndpoints.some((e) => e.includes(stem))) {
+            violations.push(`resource type '${type}' has no implemented endpoint`);
+        }
+    }
+    if (!snapshot.implementedEndpoints.some((e) => e === 'POST /query'))
+        violations.push('missing query endpoint');
+    if (!snapshot.implementedEndpoints.some((e) => e === 'POST /describe_index_stats'))
+        violations.push('missing describe_index_stats endpoint');
+    if (!snapshot.implementedEndpoints.some((e) => e === 'POST /indexes'))
+        violations.push('missing index create endpoint');
+    return {
+        ok: violations.length === 0,
+        endpointsChecked: snapshot.implementedEndpoints.length,
+        resourceTypesChecked: snapshot.resourceTypes.length,
+        violations,
+    };
+}

package/dist/src/pinecone-connector.d.ts

@@ -0,0 +1,45 @@
+import type { SyncResource } from '@volter/world-core';
+import { type PineconeBudgetedOptions } from './pinecone-budget.js';
+export type { PineconeBudgetedOptions };
+export type PineconeRealIndex = {
+    name: string;
+    dimension?: number | null;
+    metric?: string | null;
+    spec?: unknown;
+    deletionProtection?: string | null;
+    tags?: Record<string, string> | null;
+    vectorType?: string | null;
+};
+export type PineconeRealVector = {
+    index: string;
+    namespace?: string | null;
+    id: string;
+    values?: number[] | null;
+    metadata?: Record<string, unknown> | null;
+};
+export interface PineconeLikeClient {
+    listIndexes?: () => Promise<{
+        indexes: PineconeRealIndex[];
+    }>;
+    listVectors?: () => Promise<{
+        vectors: PineconeRealVector[];
+    }>;
+}
+export declare function mapIndex(m: PineconeRealIndex): SyncResource;
+export declare function mapVector(v: PineconeRealVector): SyncResource;
+export declare function pullPineconeIndexes(rawClient: PineconeLikeClient, opts?: {
+    root?: string;
+} & PineconeBudgetedOptions): Promise<SyncResource[]>;
+export declare function pullPineconeVectors(rawClient: PineconeLikeClient, opts?: PineconeBudgetedOptions): Promise<SyncResource[]>;
+/**
+ * D7 entry point: pull from real Pinecone (indexes + vectors) and fold EVERY domain into the twin
+ * via ONE syncPull (shadow-diff dedup). Returns { observed, deltasAppended } — a re-pull of
+ * identical state appends ZERO deltas (observed stays, deltasAppended drops to 0).
+ */
+export declare function syncPineconeFromReal(rawClient: PineconeLikeClient, opts?: {
+    root?: string;
+    occurredAt?: string;
+} & PineconeBudgetedOptions): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;