npm - @wildo-ai/external-connectors-models - Versions diffs - 1.1.11 → 1.1.12 - Mend

@wildo-ai/external-connectors-models 1.1.11 → 1.1.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (109) hide show

package/dist/esm/protocols/embeddings.external-connectors-models.schemas.js CHANGED Viewed

@@ -44,21 +44,104 @@ export var EmbeddingsProvider_OperationKey;
     EmbeddingsProvider_OperationKey["EMBED_TEXTS"] = "embeddings.embedTexts";
 })(EmbeddingsProvider_OperationKey || (EmbeddingsProvider_OperationKey = {}));
 /**
- * WHY a text is being embedded — some models embed retrieval QUERIES differently from the
- * DOCUMENTS they search over (Voyage/Cohere `input_type`; instruction-prefixed models), so the
- * caller's intent must travel with the call rather than being inferred. OpenAI `text-embedding-3-*`
- * ignores the distinction; providers that honour it translate this value at their boundary.
+ * WHY a text is being embedded — the ROLE of the text in a retrieval. Some models embed retrieval
+ * QUERIES differently from the DOCUMENTS they search over, so the caller's intent must travel with
+ * the call rather than being inferred. The caller that knows sets it: the `rag:embedding-drain`
+ * worker embeds corpus chunks as {@link CORPUS}, retrieval embeds the search text as {@link QUERY}.
+ *
+ * It reaches the vendor through the provider's declared {@link EmbeddingsProvider_TextPurposeHandling}
+ * (#3427); the engine never names a vendor parameter. Measured 2026-11-06, the vendors split:
+ *  - Cohere's `input_type` is "Required for embedding models v3 and higher": `search_document` is
+ *    "Used for embeddings stored in a vector database for search use-cases", `search_query` "Used for
+ *    embeddings of search queries run against a vector DB to find relevant documents".
+ *    spec-cite: Cohere API reference, "Embed API (v2)" (https://docs.cohere.com/reference/embed, fetched 2026-11-06), `input_type`.
+ *  - Voyage's `input_type` takes `None` (default), `query` or `document`; for the last two it prepends
+ *    "Represent the query for retrieving supporting documents:" / "Represent the document for retrieval:",
+ *    and recommends specifying it for retrieval.
+ *    spec-cite: Voyage AI documentation, "Text Embeddings" (https://docs.voyageai.com/docs/embeddings, fetched 2026-11-06), `input_type`.
+ *  - OpenAI's embeddings request has no such parameter (`input`, `model`, `dimensions`,
+ *    `encoding_format`, `user`), nor does Amazon Titan Text Embeddings V2 (`inputText`, `dimensions`,
+ *    `normalize`, `embeddingTypes`): those providers declare that their vendor has no role.
  *
  * A named home (semantic-string-literals rule): `'corpus'`/`'query'` are a closed vocabulary,
  * and this enum is where their semantics live.
  */
 export var EmbeddingsProvider_TextPurpose;
 (function (EmbeddingsProvider_TextPurpose) {
-    /** The text IS retrievable content — a RAG chunk entering the corpus. */
+    /** The text IS retrievable content — a RAG chunk entering the corpus (Cohere `search_document`, Voyage `document`). */
     EmbeddingsProvider_TextPurpose["CORPUS"] = "corpus";
-    /** The text is a SEARCH query that will be matched against corpus vectors. */
+    /** The text is a SEARCH query that will be matched against corpus vectors (Cohere `search_query`, Voyage `query`). */
     EmbeddingsProvider_TextPurpose["QUERY"] = "query";
 })(EmbeddingsProvider_TextPurpose || (EmbeddingsProvider_TextPurpose = {}));
+/**
+ * HOW a provider carries {@link EmbeddingsProvider_TextPurpose} to its vendor — the kind of an embeddings arm's
+ * `textPurposeHandling` (#3427). The arm must declare one: a provider whose vendor distinguishes the roles maps each,
+ * and one whose vendor does not says so with its reason, so "this provider ignores the role" is a decision on record
+ * and never the silent default it was. (Until #3427 no provider could map it: the role reached the trace only, and
+ * Cohere's SDK, given nothing, sent `search_query` for the corpus too.)
+ */
+export var EmbeddingsProvider_TextPurposeHandlingKind;
+(function (EmbeddingsProvider_TextPurposeHandlingKind) {
+    /**
+     * The vendor's embedding API has no query/document parameter, so one vector space serves both roles and the engine
+     * sends nothing for it. Declared with the reason (the vendor's documented request parameters), never assumed.
+     */
+    EmbeddingsProvider_TextPurposeHandlingKind["VENDOR_HAS_NO_ROLE"] = "vendor-has-no-role";
+    /**
+     * The vendor distinguishes the roles, and its AI-SDK client reads the role from `providerOptions`: the arm declares,
+     * for EVERY purpose, the options the engine hands `embedMany` for a call of that purpose (Cohere:
+     * `{ cohere: { inputType: 'search_document' } }` for CORPUS). Data, not a function, so the engine stays
+     * provider-neutral and a registry module's declaration can be checked before any text leaves.
+     */
+    EmbeddingsProvider_TextPurposeHandlingKind["SDK_PROVIDER_OPTIONS"] = "sdk-provider-options";
+})(EmbeddingsProvider_TextPurposeHandlingKind || (EmbeddingsProvider_TextPurposeHandlingKind = {}));
+/**
+ * Why a provider's declared `textPurposeHandling` cannot be used, or `undefined` (#3427). A registry module is loaded at
+ * runtime, so nothing compiled its declaration; absence is a defect too, because an embeddings arm must state how the
+ * role reaches its vendor. A {@link EmbeddingsProvider_TextPurposeHandlingKind.SDK_PROVIDER_OPTIONS} declaration must
+ * map EVERY purpose to a non-empty `{ <sdk provider id>: { <option>: string | number | boolean } }`: a purpose left
+ * out would be embedded with the SDK's default, which is exactly the mismatch the declaration exists to prevent.
+ */
+export const describeEmbeddingsTextPurposeHandlingDefect = (handling) => {
+    if (typeof handling !== "object" || handling === null || Array.isArray(handling)) {
+        return "declares no `textPurposeHandling`: an embeddings arm must say how a text's role (corpus or query) reaches its vendor, or that the vendor has none";
+    }
+    const { kind, reason, providerOptionsByPurpose } = handling;
+    if (kind === EmbeddingsProvider_TextPurposeHandlingKind.VENDOR_HAS_NO_ROLE) {
+        return typeof reason === "string" && reason.trim().length > 0 ? undefined : "declares its vendor has no role without a `reason`";
+    }
+    if (kind !== EmbeddingsProvider_TextPurposeHandlingKind.SDK_PROVIDER_OPTIONS) {
+        return "declares an unknown `textPurposeHandling.kind`";
+    }
+    if (typeof providerOptionsByPurpose !== "object" || providerOptionsByPurpose === null || Array.isArray(providerOptionsByPurpose)) {
+        return "declares SDK provider options with no `providerOptionsByPurpose`";
+    }
+    for (const purpose of Object.values(EmbeddingsProvider_TextPurpose)) {
+        const options = providerOptionsByPurpose[purpose];
+        if (typeof options !== "object" || options === null || Array.isArray(options) || Object.keys(options).length === 0) {
+            return `maps no SDK provider options for the "${purpose}" purpose`;
+        }
+        for (const perProvider of Object.values(options)) {
+            if (typeof perProvider !== "object" || perProvider === null || Array.isArray(perProvider) || Object.keys(perProvider).length === 0) {
+                return `maps an empty or malformed SDK provider option set for the "${purpose}" purpose`;
+            }
+            if (!Object.values(perProvider).every((value) => ["string", "number", "boolean"].includes(typeof value))) {
+                return `maps a non-scalar SDK provider option for the "${purpose}" purpose`;
+            }
+        }
+    }
+    // One option set for every purpose is the original defect in a declaration's clothing (a copy-paste slip that sends
+    // the corpus as queries again): a vendor whose roles do not differ declares VENDOR_HAS_NO_ROLE instead.
+    const distinctOptionSets = new Set(Object.values(EmbeddingsProvider_TextPurpose).map((purpose) => canonicalJson(providerOptionsByPurpose[purpose])));
+    if (distinctOptionSets.size < Object.values(EmbeddingsProvider_TextPurpose).length) {
+        return "maps the same SDK provider options to more than one purpose: a vendor whose embedding request has no role declares `vendor-has-no-role`";
+    }
+    return undefined;
+};
+/** JSON with object keys sorted at every level, so two option sets compare by content rather than by key order. */
+const canonicalJson = (value) => JSON.stringify(value, (_key, nested) => typeof nested === "object" && nested !== null && !Array.isArray(nested)
+    ? Object.fromEntries(Object.entries(nested).sort(([left], [right]) => left.localeCompare(right)))
+    : nested);
 /**
  * @wildo_source:part:start saas.external-providers.embeddings.applicability facet:kind:api facet:audience:app-developer
  *

package/dist/esm/protocols/embeddings.external-connectors-models.schemas.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"embeddings.external-connectors-models.schemas.js","sourceRoot":"","sources":["../../../../src/protocols/embeddings.external-connectors-models.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\"\nimport {\n ExternalProvider_ExchangeProtocol_Kind,\n } from \"../core/commons.external-connectors-models.schemas\"\n\n//===============================================================\n// Embeddings Provider\n// --------\n// Text → vector embedding providers (OpenAI text-embedding-3, Voyage, Cohere embed, …).\n// Serves the RAG derived-data tier: the `rag:embedding-drain` worker embeds corpus chunks,\n// and retrieval (RAG plan Phase 5) embeds queries through the SAME provider seam so both\n// sides of a similarity search live in one vector space.\n//\n// Deliberately a SEPARATE protocol from `LLM_PROVIDER` (RAG plan DL2, the `IMAGE_PROVIDER`\n// precedent): its I/O is float vectors, its parameters (dimensions / batch size) share nothing\n// with LLM sampling, and — decisive — a sixth `LLMProvider_OperationKey` would fail SILENTLY\n// in every LLM consumer surface, while a new `runtimeContract.kind` fails COMPILATION at every\n// switch. It also fills its own `EngineCapability.AI_EMBEDDINGS` slot so an application can pick\n// Anthropic for chat and a different provider for embeddings.\n//===============================================================\n\n/*\n Concrete embedding-model ids the framework knows. Ids and dimensions are published provider\n * facts (OpenAI embeddings API); the runtime additionally verifies the MEASURED dimension of\n * every returned vector against the catalog row before anything is persisted, so a wrong row\n * here fails loudly instead of poisoning a vector store.\n /\nexport enum EmbeddingsProvider_Model {\n /* OpenAI's cost-efficient embedding model — 1536 dimensions. The industry-default RAG choice. /\n OPEN_AI_TEXT_EMBEDDING_3_SMALL = \"text-embedding-3-small\",\n /* OpenAI's highest-quality embedding model — 3072 dimensions. /\n OPEN_AI_TEXT_EMBEDDING_3_LARGE = \"text-embedding-3-large\",\n}\n\n/\n The embeddings operation vocabulary — deliberately DISJOINT from `LLMProvider_OperationKey`\n * and `ImageProvider_OperationKey` (each protocol kind owns its own operation enum, so a key's\n * membership decides its protocol without inspection).\n \n Import path: `@wildo-ai/external-connectors-models`.\n \n (`@wildo_source` anchoring + the teaching skill are RAG-plan Phase-7 work — the\n * capability-catalog rule's DoD is deferred there deliberately, not forgotten.)\n /\nexport enum EmbeddingsProvider_OperationKey {\n /* A batch of texts → one vector per text, in input order. /\n EMBED_TEXTS = \"embeddings.embedTexts\",\n}\n\n/\n WHY a text is being embedded — some models embed retrieval QUERIES differently from the\n * DOCUMENTS they search over (Voyage/Cohere `input_type`; instruction-prefixed models), so the\n * caller's intent must travel with the call rather than being inferred. OpenAI `text-embedding-3-`\n ignores the distinction; providers that honour it translate this value at their boundary.\n \n A named home (semantic-string-literals rule): `'corpus'`/`'query'` are a closed vocabulary,\n * and this enum is where their semantics live.\n /\nexport enum EmbeddingsProvider_TextPurpose {\n /* The text IS retrievable content — a RAG chunk entering the corpus. /\n CORPUS = \"corpus\",\n /* The text is a SEARCH query that will be matched against corpus vectors. /\n QUERY = \"query\",\n}\n\n/\n @wildo_source:part:start saas.external-providers.embeddings.applicability facet:kind:api facet:audience:app-developer\n \n WHAT an embedding is produced FOR — the durable axis of embedding-model selection\n * (model-selection-by-applicability rule: an author names a CLASS, never a concrete model id;\n * the framework resolves the id from the catalog + preference below).\n \n This is ALSO the persisted `embeddingClass` stamp on every RAG chunk row: the drain worker\n * stamps the class it embedded under, and the model-migration pass re-embeds any chunk whose\n * stamped class→model binding no longer matches the current resolution — so changing the\n * preference below IS the migration trigger, with no chunk-table DDL and no call-site edits.\n \n NOTE both corpus AND query embedding of one retrieval surface MUST resolve through the SAME\n * class — a similarity search across two models' vector spaces is meaningless. That is why the\n * class names the SURFACE (`RAG_DEFAULT`), not the side (`purpose` carries the side).\n /\nexport enum Embeddings_Applicability {\n /* The default RAG surface: `.ragSource()` corpus chunks and the retrieval queries over them. /\n RAG_DEFAULT = \"rag-default\",\n}\n/* @wildo_source:part:end saas.external-providers.embeddings.applicability /\n\n/\n One row per embedding model: everything the framework knows about a concrete id.\n * Mirrors `LLM_ModelCatalogEntry`'s shape at the size this axis needs today.\n /\nexport type Embeddings_ModelCatalogEntry = {\n /* The `ref` of the provider module that serves this id. /\n providerRef: string;\n /\n The model's published output dimension. Load-bearing twice: the drain worker VERIFIES every\n * returned vector against it before persisting (a wrong-dims write silently poisons ANN\n * indexes), and the pgvector HNSW expression index is created per this dimension.\n /\n dims: number;\n /* FRAMEWORK OPINION — which applicability classes this model may be resolved for. /\n applicabilities: readonly Embeddings_Applicability[];\n};\n\n/\n THE embedding-model catalog — the single per-model fact table (the `LLM_MODEL_CATALOG`\n * discipline: an EXHAUSTIVE `Record`, so a new `EmbeddingsProvider_Model` member without a row\n * is a compile error).\n /\nexport const EMBEDDINGS_MODEL_CATALOG: Record<EmbeddingsProvider_Model, Embeddings_ModelCatalogEntry> = {\n [EmbeddingsProvider_Model.OPEN_AI_TEXT_EMBEDDING_3_SMALL]: {\n providerRef: \"openai\",\n dims: 1536,\n applicabilities: [Embeddings_Applicability.RAG_DEFAULT],\n },\n [EmbeddingsProvider_Model.OPEN_AI_TEXT_EMBEDDING_3_LARGE]: {\n providerRef: \"openai\",\n dims: 3072,\n // Deliberately NOT auto-selected for RAG_DEFAULT: 2× the storage + ANN cost for a quality\n // delta most application corpora do not need. Selection is framework-owned: the public\n // resolver exposes no per-application preference override. Selecting this model would\n // require a framework applicability/preference change, with corpus migration implications.\n applicabilities: [],\n },\n};\n\n/\n The framework's DEFAULT answer to \"which embedding model serves this class\", ordered by\n * preference, highest first. THIS BINDING IS THE MIGRATION KEY (RAG plan §3.d): editing it\n * changes what `resolveEmbeddingsModelForApplicability` answers, which makes every chunk stamped\n * with the previous model a migration candidate the drain worker re-embeds — bounded per run,\n * converging over runs. No agent/worker definition changes.\n /\nexport const EMBEDDINGS_MODEL_APPLICABILITY_PREFERENCE: Record<Embeddings_Applicability, readonly EmbeddingsProvider_Model[]> = {\n [Embeddings_Applicability.RAG_DEFAULT]: [\n EmbeddingsProvider_Model.OPEN_AI_TEXT_EMBEDDING_3_SMALL,\n ],\n};\n\n/\n An embedding model a provider the engine does NOT ship declares it serves (#2516) — the embeddings mirror of\n * `LLM_ModelDeclaration`. The catalog is an exhaustive record over {@link EmbeddingsProvider_Model}, so a registry\n * vendor declares its models on its embeddings arm instead of adding a row.\n \n `dims` is as load-bearing here as on a catalog row: the drain worker verifies every returned vector against it, and the\n * per-dimension vector index is keyed by it. It must be the model's published output dimension.\n /\nexport type Embeddings_ModelDeclaration = {\n model: string;\n dims: number;\n applicabilities: readonly Embeddings_Applicability[];\n};\n\n/\n Why a provider's declared embedding models ({@link Embeddings_ModelDeclaration}) cannot be used, or `undefined`\n * (#2516). Absent is fine: an engine provider has none. A registry module is loaded at runtime, so nothing compiled its\n * `models`; `dims` in particular decides which vector index a chunk enters, so it must be a positive integer.\n /\nexport const describeEmbeddingsModelDeclarationsDefect = (models: unknown): string \| undefined => {\n if (models === undefined) return undefined;\n if (!Array.isArray(models)) return \"are not a list\";\n const applicabilities = new Set<unknown>(Object.values(Embeddings_Applicability));\n const seen = new Set<string>();\n for (const [index, declaration] of models.entries()) {\n if (typeof declaration !== \"object\" \|\| declaration === null \|\| Array.isArray(declaration)) return `have no \\`model\\` at position ${index}`;\n const { model, dims, applicabilities: declared } = declaration as Record<string, unknown>;\n if (typeof model !== \"string\" \|\| model.trim().length === 0) return `have no \\`model\\` at position ${index}`;\n if (seen.has(model)) return `declare \"${model}\" twice`;\n seen.add(model);\n if (typeof dims !== \"number\" \|\| !Number.isInteger(dims) \|\| dims <= 0) return `give \"${model}\" no positive integer \\`dims\\``;\n if (!Array.isArray(declared) \|\| !declared.every((member) => applicabilities.has(member))) return `give \"${model}\" unknown \\`applicabilities\\``;\n }\n return undefined;\n};\n\n/\n Whether the engine's embedding catalog knows this provider, which decides where its model facts come from (#2516): catalog\n * rows for an engine provider, the provider's own `models` declaration otherwise.\n /\nexport const isEmbeddingsCatalogProvider = (\n providerRef: string,\n catalog: Record<EmbeddingsProvider_Model, Embeddings_ModelCatalogEntry> = EMBEDDINGS_MODEL_CATALOG,\n): boolean => Object.values(catalog).some((entry) => entry.providerRef === providerRef);\n\n/* Why {@link resolveEmbeddingsModelForApplicability} could not answer — carried into a named CONFIGURATION error. /\nexport enum Embeddings_ModelResolutionFailure {\n /* The applicability has no candidate at all for this provider. /\n NO_CANDIDATE_FOR_PROVIDER = \"no_candidate_for_provider\",\n /* An engine provider (one the catalog knows) also declares models; its models are catalog rows, so it is refused. /\n CATALOG_PROVIDER_DECLARES_MODELS = \"catalog_provider_declares_models\",\n /* A declared model's `dims` is not a positive integer, so nothing could verify or index its vectors. /\n DECLARED_DIMS_INVALID = \"declared_dims_invalid\",\n}\n\nexport type Embeddings_ModelResolution =\n \| { resolved: true; model: string; dims: number }\n \| { resolved: false; failure: Embeddings_ModelResolutionFailure; consideredModels: readonly string[] };\n\n/\n Resolve an applicability class to ONE concrete embedding model for a given provider.\n \n Fails CLOSED and explains itself (the `resolveModelForApplicability` contract): a silent\n * fallback to some other model would fracture the vector space the class exists to keep whole.\n * The resolved `(class, model)` pair is what the RAG drain worker stamps on every chunk and what\n * its migration pass compares stamps against.\n \n Two sources, decided by whether the catalog knows the provider (as `resolveModelForApplicability`, #2516): an engine\n * provider resolves through the preference and catalog and is refused if it also declares models; any other provider\n * resolves from its `declaredModels`, the first declaring the applicability.\n /\nexport const resolveEmbeddingsModelForApplicability = (\n input: { applicability: Embeddings_Applicability; providerRef: string; declaredModels?: readonly Embeddings_ModelDeclaration[] },\n catalog: Record<EmbeddingsProvider_Model, Embeddings_ModelCatalogEntry> = EMBEDDINGS_MODEL_CATALOG,\n): Embeddings_ModelResolution => {\n const declared = input.declaredModels ?? [];\n const catalogKnowsProvider = isEmbeddingsCatalogProvider(input.providerRef, catalog);\n if (catalogKnowsProvider && declared.length > 0) {\n return { resolved: false, failure: Embeddings_ModelResolutionFailure.CATALOG_PROVIDER_DECLARES_MODELS, consideredModels: declared.map((entry) => entry.model) };\n }\n if (!catalogKnowsProvider) {\n const chosen = declared.find((entry) => entry.applicabilities.includes(input.applicability));\n if (chosen === undefined) {\n return { resolved: false, failure: Embeddings_ModelResolutionFailure.NO_CANDIDATE_FOR_PROVIDER, consideredModels: declared.map((entry) => entry.model) };\n }\n if (!Number.isInteger(chosen.dims) \|\| chosen.dims <= 0) {\n return { resolved: false, failure: Embeddings_ModelResolutionFailure.DECLARED_DIMS_INVALID, consideredModels: [chosen.model] };\n }\n return { resolved: true, model: chosen.model, dims: chosen.dims };\n }\n const candidates = EMBEDDINGS_MODEL_APPLICABILITY_PREFERENCE[input.applicability];\n const forProvider = candidates.filter((model) => {\n const entry = catalog[model];\n return entry.providerRef === input.providerRef && entry.applicabilities.includes(input.applicability);\n });\n if (forProvider.length === 0) {\n return { resolved: false, failure: Embeddings_ModelResolutionFailure.NO_CANDIDATE_FOR_PROVIDER, consideredModels: candidates };\n }\n const model = forProvider[0]!;\n return { resolved: true, model, dims: catalog[model].dims };\n};\n\n// ===============================================================\n// Embeddings Operations Context\n// ===============================================================\n\n/\n Usage of one embedding call. There is NO completion-token dimension — an embedding consumes\n * input tokens and produces vectors, so usage-completeness for an embedding trace is judged on\n * `inputTokens` alone (H4: an embedding trace must never be flagged token-incomplete for lacking\n * completion tokens it structurally cannot have).\n /\nexport const EmbeddingsProvider_UsageSchema = z.object({\n /* Provider-reported input tokens, when the model reports them (OpenAI does). /\n inputTokens: z.number().optional(),\n});\nexport type EmbeddingsProvider_Usage = z.infer<typeof EmbeddingsProvider_UsageSchema>;\n\nexport const EmbeddingsProvider_ExecutionTransportMetadataSchema = z.object({\n protocolKind: z.literal(ExternalProvider_ExchangeProtocol_Kind.EMBEDDINGS_PROVIDER),\n providerRef: z.string(),\n model: z.string().optional(),\n});\nexport type EmbeddingsProvider_ExecutionTransportMetadata = z.infer<typeof EmbeddingsProvider_ExecutionTransportMetadataSchema>;\n\n// ===============================================================\n// Embeddings I/O Schemas\n// ===============================================================\n\n/* Input of the {@link EmbeddingsProvider_OperationKey.EMBED_TEXTS} operation. /\nexport const EmbeddingsProvider_EmbedTextsInputSchema = z.object({\n /* The texts to embed — one vector is returned per text, in this order. /\n texts: z.array(z.string()).min(1),\n /* Why these texts are embedded — see {@link EmbeddingsProvider_TextPurpose}. /\n purpose: z.enum(EmbeddingsProvider_TextPurpose),\n});\nexport type EmbeddingsProvider_EmbedTextsInput = z.infer<typeof EmbeddingsProvider_EmbedTextsInputSchema>;\n\n/\n Output of {@link EmbeddingsProvider_OperationKey.EMBED_TEXTS}. `vectors[i]` embeds `texts[i]`.\n \n ⚠️ PRIVACY/OBSERVABILITY CONTRACT: raw vectors are a lossy ENCODING of the source text, not\n * telemetry — they must NEVER reach analytics events, traces, or logs at any verbosity. Consumers\n * summarize (`vectorCount`, `dims`) instead; the PostHog sink's embedding arm enforces this\n * defensively even against a mis-built trace.\n /\nexport const EmbeddingsProvider_EmbedTextsOutputSchema = z.object({\n vectors: z.array(z.array(z.number())),\n /* The concrete model that produced the vectors — the chunk rows' `embeddingModel` stamp. /\n model: z.string(),\n /* The (verified) dimension every returned vector carries — the `embeddingDims` stamp. */\n dims: z.number().int().positive(),\n usage: EmbeddingsProvider_UsageSchema,\n});\nexport type EmbeddingsProvider_EmbedTextsOutput = z.infer<typeof EmbeddingsProvider_EmbedTextsOutputSchema>;\n\n"]}
1	+ {"version":3,"file":"embeddings.external-connectors-models.schemas.js","sourceRoot":"","sources":["../../../src/protocols/embeddings.external-connectors-models.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EACL,sCAAsC,GACrC,MAAM,oDAAoD,CAAA;AAE7D,iEAAiE;AACjE,sBAAsB;AACtB,WAAW;AACX,wFAAwF;AACxF,2FAA2F;AAC3F,yFAAyF;AACzF,yDAAyD;AACzD,EAAE;AACF,2FAA2F;AAC3F,+FAA+F;AAC/F,6FAA6F;AAC7F,+FAA+F;AAC/F,iGAAiG;AACjG,8DAA8D;AAC9D,iEAAiE;AAEjE;;;;;GAKG;AACH,MAAM,CAAN,IAAY,wBAKX;AALD,WAAY,wBAAwB;IAClC,kGAAkG;IAClG,qFAAyD,CAAA;IACzD,kEAAkE;IAClE,qFAAyD,CAAA;AAC3D,CAAC,EALW,wBAAwB,KAAxB,wBAAwB,QAKnC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAN,IAAY,+BAGX;AAHD,WAAY,+BAA+B;IACzC,8DAA8D;IAC9D,wEAAqC,CAAA;AACvC,CAAC,EAHW,+BAA+B,KAA/B,+BAA+B,QAG1C;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAN,IAAY,8BAKX;AALD,WAAY,8BAA8B;IACxC,uHAAuH;IACvH,mDAAiB,CAAA;IACjB,sHAAsH;IACtH,iDAAe,CAAA;AACjB,CAAC,EALW,8BAA8B,KAA9B,8BAA8B,QAKzC;AAED;;;;;;GAMG;AACH,MAAM,CAAN,IAAY,0CAaX;AAbD,WAAY,0CAA0C;IACpD;;;OAGG;IACH,uFAAyC,CAAA;IACzC;;;;;OAKG;IACH,2FAA6C,CAAA;AAC/C,CAAC,EAbW,0CAA0C,KAA1C,0CAA0C,QAarD;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2CAA2C,GAAG,CAAC,QAAiB,EAAsB,EAAE;IACnG,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACjF,OAAO,mJAAmJ,CAAC;IAC7J,CAAC;IACD,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,wBAAwB,EAAE,GAAG,QAAmC,CAAC;IACvF,IAAI,IAAI,KAAK,0CAA0C,CAAC,kBAAkB,EAAE,CAAC;QAC3E,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,oDAAoD,CAAC;IACnI,CAAC;IACD,IAAI,IAAI,KAAK,0CAA0C,CAAC,oBAAoB,EAAE,CAAC;QAC7E,OAAO,gDAAgD,CAAC;IAC1D,CAAC;IACD,IAAI,OAAO,wBAAwB,KAAK,QAAQ,IAAI,wBAAwB,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,wBAAwB,CAAC,EAAE,CAAC;QACjI,OAAO,kEAAkE,CAAC;IAC5E,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,MAAM,CAAC,8BAA8B,CAAC,EAAE,CAAC;QACpE,MAAM,OAAO,GAAI,wBAAoD,CAAC,OAAO,CAAC,CAAC;QAC/E,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnH,OAAO,yCAAyC,OAAO,WAAW,CAAC;QACrE,CAAC;QACD,KAAK,MAAM,WAAW,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YACjD,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACnI,OAAO,+DAA+D,OAAO,WAAW,CAAC;YAC3F,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC;gBACzG,OAAO,kDAAkD,OAAO,WAAW,CAAC;YAC9E,CAAC;QACH,CAAC;IACH,CAAC;IACD,oHAAoH;IACpH,wGAAwG;IACxG,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAChC,MAAM,CAAC,MAAM,CAAC,8BAA8B,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,aAAa,CAAE,wBAAoD,CAAC,OAAO,CAAC,CAAC,CAAC,CAC9I,CAAC;IACF,IAAI,kBAAkB,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,8BAA8B,CAAC,CAAC,MAAM,EAAE,CAAC;QACnF,OAAO,yIAAyI,CAAC;IACnJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AAEF,mHAAmH;AACnH,MAAM,aAAa,GAAG,CAAC,KAAc,EAAU,EAAE,CAC/C,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAe,EAAE,EAAE,CAC9C,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;IACrE,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,MAAiC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5H,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhB;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAN,IAAY,wBAGX;AAHD,WAAY,wBAAwB;IAClC,iGAAiG;IACjG,uDAA2B,CAAA;AAC7B,CAAC,EAHW,wBAAwB,KAAxB,wBAAwB,QAGnC;AAoBD;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAmE;IACtG,CAAC,wBAAwB,CAAC,8BAA8B,CAAC,EAAE;QACzD,WAAW,EAAE,QAAQ;QACrB,IAAI,EAAE,IAAI;QACV,eAAe,EAAE,CAAC,wBAAwB,CAAC,WAAW,CAAC;KACxD;IACD,CAAC,wBAAwB,CAAC,8BAA8B,CAAC,EAAE;QACzD,WAAW,EAAE,QAAQ;QACrB,IAAI,EAAE,IAAI;QACV,0FAA0F;QAC1F,uFAAuF;QACvF,sFAAsF;QACtF,2FAA2F;QAC3F,eAAe,EAAE,EAAE;KACpB;CACF,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yCAAyC,GAA0E;IAC9H,CAAC,wBAAwB,CAAC,WAAW,CAAC,EAAE;QACtC,wBAAwB,CAAC,8BAA8B;KACxD;CACF,CAAC;AAgBF;;;;GAIG;AACH,MAAM,CAAC,MAAM,yCAAyC,GAAG,CAAC,MAAe,EAAsB,EAAE;IAC/F,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC3C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,gBAAgB,CAAC;IACpD,MAAM,eAAe,GAAG,IAAI,GAAG,CAAU,MAAM,CAAC,MAAM,CAAC,wBAAwB,CAAC,CAAC,CAAC;IAClF,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;QACpD,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC;YAAE,OAAO,iCAAiC,KAAK,EAAE,CAAC;QAC3I,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,QAAQ,EAAE,GAAG,WAAsC,CAAC;QAC1F,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,iCAAiC,KAAK,EAAE,CAAC;QAC5G,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,OAAO,YAAY,KAAK,SAAS,CAAC;QACvD,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC;YAAE,OAAO,SAAS,KAAK,gCAAgC,CAAC;QAC5H,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAAE,OAAO,SAAS,KAAK,+BAA+B,CAAC;IACjJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CACzC,WAAmB,EACnB,UAA0E,wBAAwB,EACzF,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,KAAK,WAAW,CAAC,CAAC;AAExF,sHAAsH;AACtH,MAAM,CAAN,IAAY,iCAOX;AAPD,WAAY,iCAAiC;IAC3C,mEAAmE;IACnE,4FAAuD,CAAA;IACvD,sHAAsH;IACtH,0GAAqE,CAAA;IACrE,yGAAyG;IACzG,oFAA+C,CAAA;AACjD,CAAC,EAPW,iCAAiC,KAAjC,iCAAiC,QAO5C;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,sCAAsC,GAAG,CACpD,KAAgI,EAChI,UAA0E,wBAAwB,EACtE,EAAE;IAC9B,MAAM,QAAQ,GAAG,KAAK,CAAC,cAAc,IAAI,EAAE,CAAC;IAC5C,MAAM,oBAAoB,GAAG,2BAA2B,CAAC,KAAK,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACrF,IAAI,oBAAoB,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,iCAAiC,CAAC,gCAAgC,EAAE,gBAAgB,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;IAClK,CAAC;IACD,IAAI,CAAC,oBAAoB,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,eAAe,CAAC,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC;QAC7F,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,iCAAiC,CAAC,yBAAyB,EAAE,gBAAgB,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3J,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC;YACvD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,iCAAiC,CAAC,qBAAqB,EAAE,gBAAgB,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QACjI,CAAC;QACD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;IACpE,CAAC;IACD,MAAM,UAAU,GAAG,yCAAyC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IAClF,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QAC9C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;QAC7B,OAAO,KAAK,CAAC,WAAW,KAAK,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,eAAe,CAAC,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IACxG,CAAC,CAAC,CAAC;IACH,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,iCAAiC,CAAC,yBAAyB,EAAE,gBAAgB,EAAE,UAAU,EAAE,CAAC;IACjI,CAAC;IACD,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,CAAE,CAAC;IAC9B,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;AAC9D,CAAC,CAAC;AAEF,kEAAkE;AAClE,gCAAgC;AAChC,kEAAkE;AAElE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC,MAAM,CAAC;IACrD,iFAAiF;IACjF,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACnC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,mDAAmD,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1E,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,sCAAsC,CAAC,mBAAmB,CAAC;IACnF,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC7B,CAAC,CAAC;AAGH,kEAAkE;AAClE,yBAAyB;AACzB,kEAAkE;AAElE,kFAAkF;AAClF,MAAM,CAAC,MAAM,wCAAwC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/D,2EAA2E;IAC3E,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,iFAAiF;IACjF,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,8BAA8B,CAAC;CAChD,CAAC,CAAC;AAGH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,yCAAyC,GAAG,CAAC,CAAC,MAAM,CAAC;IAChE,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IACrC,6FAA6F;IAC7F,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,0FAA0F;IAC1F,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACjC,KAAK,EAAE,8BAA8B;CACtC,CAAC,CAAC","sourcesContent":["import { z } from \"zod\"\nimport {\n ExternalProvider_ExchangeProtocol_Kind,\n } from \"../core/commons.external-connectors-models.schemas\"\n\n//===============================================================\n// Embeddings Provider\n// --------\n// Text → vector embedding providers (OpenAI text-embedding-3, Voyage, Cohere embed, …).\n// Serves the RAG derived-data tier: the `rag:embedding-drain` worker embeds corpus chunks,\n// and retrieval (RAG plan Phase 5) embeds queries through the SAME provider seam so both\n// sides of a similarity search live in one vector space.\n//\n// Deliberately a SEPARATE protocol from `LLM_PROVIDER` (RAG plan DL2, the `IMAGE_PROVIDER`\n// precedent): its I/O is float vectors, its parameters (dimensions / batch size) share nothing\n// with LLM sampling, and — decisive — a sixth `LLMProvider_OperationKey` would fail SILENTLY\n// in every LLM consumer surface, while a new `runtimeContract.kind` fails COMPILATION at every\n// switch. It also fills its own `EngineCapability.AI_EMBEDDINGS` slot so an application can pick\n// Anthropic for chat and a different provider for embeddings.\n//===============================================================\n\n/*\n Concrete embedding-model ids the framework knows. Ids and dimensions are published provider\n * facts (OpenAI embeddings API); the runtime additionally verifies the MEASURED dimension of\n * every returned vector against the catalog row before anything is persisted, so a wrong row\n * here fails loudly instead of poisoning a vector store.\n /\nexport enum EmbeddingsProvider_Model {\n /* OpenAI's cost-efficient embedding model — 1536 dimensions. The industry-default RAG choice. /\n OPEN_AI_TEXT_EMBEDDING_3_SMALL = \"text-embedding-3-small\",\n /* OpenAI's highest-quality embedding model — 3072 dimensions. /\n OPEN_AI_TEXT_EMBEDDING_3_LARGE = \"text-embedding-3-large\",\n}\n\n/\n The embeddings operation vocabulary — deliberately DISJOINT from `LLMProvider_OperationKey`\n * and `ImageProvider_OperationKey` (each protocol kind owns its own operation enum, so a key's\n * membership decides its protocol without inspection).\n \n Import path: `@wildo-ai/external-connectors-models`.\n \n (`@wildo_source` anchoring + the teaching skill are RAG-plan Phase-7 work — the\n * capability-catalog rule's DoD is deferred there deliberately, not forgotten.)\n /\nexport enum EmbeddingsProvider_OperationKey {\n /* A batch of texts → one vector per text, in input order. /\n EMBED_TEXTS = \"embeddings.embedTexts\",\n}\n\n/\n WHY a text is being embedded — the ROLE of the text in a retrieval. Some models embed retrieval\n * QUERIES differently from the DOCUMENTS they search over, so the caller's intent must travel with\n * the call rather than being inferred. The caller that knows sets it: the `rag:embedding-drain`\n * worker embeds corpus chunks as {@link CORPUS}, retrieval embeds the search text as {@link QUERY}.\n \n It reaches the vendor through the provider's declared {@link EmbeddingsProvider_TextPurposeHandling}\n * (#3427); the engine never names a vendor parameter. Measured 2026-11-06, the vendors split:\n * - Cohere's `input_type` is \"Required for embedding models v3 and higher\": `search_document` is\n * \"Used for embeddings stored in a vector database for search use-cases\", `search_query` \"Used for\n * embeddings of search queries run against a vector DB to find relevant documents\".\n * spec-cite: Cohere API reference, \"Embed API (v2)\" (https://docs.cohere.com/reference/embed, fetched 2026-11-06), `input_type`.\n * - Voyage's `input_type` takes `None` (default), `query` or `document`; for the last two it prepends\n * \"Represent the query for retrieving supporting documents:\" / \"Represent the document for retrieval:\",\n * and recommends specifying it for retrieval.\n * spec-cite: Voyage AI documentation, \"Text Embeddings\" (https://docs.voyageai.com/docs/embeddings, fetched 2026-11-06), `input_type`.\n * - OpenAI's embeddings request has no such parameter (`input`, `model`, `dimensions`,\n * `encoding_format`, `user`), nor does Amazon Titan Text Embeddings V2 (`inputText`, `dimensions`,\n * `normalize`, `embeddingTypes`): those providers declare that their vendor has no role.\n \n A named home (semantic-string-literals rule): `'corpus'`/`'query'` are a closed vocabulary,\n * and this enum is where their semantics live.\n /\nexport enum EmbeddingsProvider_TextPurpose {\n /* The text IS retrievable content — a RAG chunk entering the corpus (Cohere `search_document`, Voyage `document`). /\n CORPUS = \"corpus\",\n /* The text is a SEARCH query that will be matched against corpus vectors (Cohere `search_query`, Voyage `query`). /\n QUERY = \"query\",\n}\n\n/\n HOW a provider carries {@link EmbeddingsProvider_TextPurpose} to its vendor — the kind of an embeddings arm's\n * `textPurposeHandling` (#3427). The arm must declare one: a provider whose vendor distinguishes the roles maps each,\n * and one whose vendor does not says so with its reason, so \"this provider ignores the role\" is a decision on record\n * and never the silent default it was. (Until #3427 no provider could map it: the role reached the trace only, and\n * Cohere's SDK, given nothing, sent `search_query` for the corpus too.)\n /\nexport enum EmbeddingsProvider_TextPurposeHandlingKind {\n /\n The vendor's embedding API has no query/document parameter, so one vector space serves both roles and the engine\n * sends nothing for it. Declared with the reason (the vendor's documented request parameters), never assumed.\n /\n VENDOR_HAS_NO_ROLE = \"vendor-has-no-role\",\n /\n The vendor distinguishes the roles, and its AI-SDK client reads the role from `providerOptions`: the arm declares,\n * for EVERY purpose, the options the engine hands `embedMany` for a call of that purpose (Cohere:\n * `{ cohere: { inputType: 'search_document' } }` for CORPUS). Data, not a function, so the engine stays\n * provider-neutral and a registry module's declaration can be checked before any text leaves.\n /\n SDK_PROVIDER_OPTIONS = \"sdk-provider-options\",\n}\n\n/\n Why a provider's declared `textPurposeHandling` cannot be used, or `undefined` (#3427). A registry module is loaded at\n * runtime, so nothing compiled its declaration; absence is a defect too, because an embeddings arm must state how the\n * role reaches its vendor. A {@link EmbeddingsProvider_TextPurposeHandlingKind.SDK_PROVIDER_OPTIONS} declaration must\n * map EVERY purpose to a non-empty `{ <sdk provider id>: { <option>: string \| number \| boolean } }`: a purpose left\n * out would be embedded with the SDK's default, which is exactly the mismatch the declaration exists to prevent.\n /\nexport const describeEmbeddingsTextPurposeHandlingDefect = (handling: unknown): string \| undefined => {\n if (typeof handling !== \"object\" \|\| handling === null \|\| Array.isArray(handling)) {\n return \"declares no `textPurposeHandling`: an embeddings arm must say how a text's role (corpus or query) reaches its vendor, or that the vendor has none\";\n }\n const { kind, reason, providerOptionsByPurpose } = handling as Record<string, unknown>;\n if (kind === EmbeddingsProvider_TextPurposeHandlingKind.VENDOR_HAS_NO_ROLE) {\n return typeof reason === \"string\" && reason.trim().length > 0 ? undefined : \"declares its vendor has no role without a `reason`\";\n }\n if (kind !== EmbeddingsProvider_TextPurposeHandlingKind.SDK_PROVIDER_OPTIONS) {\n return \"declares an unknown `textPurposeHandling.kind`\";\n }\n if (typeof providerOptionsByPurpose !== \"object\" \|\| providerOptionsByPurpose === null \|\| Array.isArray(providerOptionsByPurpose)) {\n return \"declares SDK provider options with no `providerOptionsByPurpose`\";\n }\n for (const purpose of Object.values(EmbeddingsProvider_TextPurpose)) {\n const options = (providerOptionsByPurpose as Record<string, unknown>)[purpose];\n if (typeof options !== \"object\" \|\| options === null \|\| Array.isArray(options) \|\| Object.keys(options).length === 0) {\n return `maps no SDK provider options for the \"${purpose}\" purpose`;\n }\n for (const perProvider of Object.values(options)) {\n if (typeof perProvider !== \"object\" \|\| perProvider === null \|\| Array.isArray(perProvider) \|\| Object.keys(perProvider).length === 0) {\n return `maps an empty or malformed SDK provider option set for the \"${purpose}\" purpose`;\n }\n if (!Object.values(perProvider).every((value) => [\"string\", \"number\", \"boolean\"].includes(typeof value))) {\n return `maps a non-scalar SDK provider option for the \"${purpose}\" purpose`;\n }\n }\n }\n // One option set for every purpose is the original defect in a declaration's clothing (a copy-paste slip that sends\n // the corpus as queries again): a vendor whose roles do not differ declares VENDOR_HAS_NO_ROLE instead.\n const distinctOptionSets = new Set(\n Object.values(EmbeddingsProvider_TextPurpose).map((purpose) => canonicalJson((providerOptionsByPurpose as Record<string, unknown>)[purpose])),\n );\n if (distinctOptionSets.size < Object.values(EmbeddingsProvider_TextPurpose).length) {\n return \"maps the same SDK provider options to more than one purpose: a vendor whose embedding request has no role declares `vendor-has-no-role`\";\n }\n return undefined;\n};\n\n/* JSON with object keys sorted at every level, so two option sets compare by content rather than by key order. /\nconst canonicalJson = (value: unknown): string =>\n JSON.stringify(value, (_key, nested: unknown) =>\n typeof nested === \"object\" && nested !== null && !Array.isArray(nested)\n ? Object.fromEntries(Object.entries(nested as Record<string, unknown>).sort(([left], [right]) => left.localeCompare(right)))\n : nested);\n\n/\n @wildo_source:part:start saas.external-providers.embeddings.applicability facet:kind:api facet:audience:app-developer\n \n WHAT an embedding is produced FOR — the durable axis of embedding-model selection\n * (model-selection-by-applicability rule: an author names a CLASS, never a concrete model id;\n * the framework resolves the id from the catalog + preference below).\n \n This is ALSO the persisted `embeddingClass` stamp on every RAG chunk row: the drain worker\n * stamps the class it embedded under, and the model-migration pass re-embeds any chunk whose\n * stamped class→model binding no longer matches the current resolution — so changing the\n * preference below IS the migration trigger, with no chunk-table DDL and no call-site edits.\n \n NOTE both corpus AND query embedding of one retrieval surface MUST resolve through the SAME\n * class — a similarity search across two models' vector spaces is meaningless. That is why the\n * class names the SURFACE (`RAG_DEFAULT`), not the side (`purpose` carries the side).\n /\nexport enum Embeddings_Applicability {\n /* The default RAG surface: `.ragSource()` corpus chunks and the retrieval queries over them. /\n RAG_DEFAULT = \"rag-default\",\n}\n/* @wildo_source:part:end saas.external-providers.embeddings.applicability /\n\n/\n One row per embedding model: everything the framework knows about a concrete id.\n * Mirrors `LLM_ModelCatalogEntry`'s shape at the size this axis needs today.\n /\nexport type Embeddings_ModelCatalogEntry = {\n /* The `ref` of the provider module that serves this id. /\n providerRef: string;\n /\n The model's published output dimension. Load-bearing twice: the drain worker VERIFIES every\n * returned vector against it before persisting (a wrong-dims write silently poisons ANN\n * indexes), and the pgvector HNSW expression index is created per this dimension.\n /\n dims: number;\n /* FRAMEWORK OPINION — which applicability classes this model may be resolved for. /\n applicabilities: readonly Embeddings_Applicability[];\n};\n\n/\n THE embedding-model catalog — the single per-model fact table (the `LLM_MODEL_CATALOG`\n * discipline: an EXHAUSTIVE `Record`, so a new `EmbeddingsProvider_Model` member without a row\n * is a compile error).\n /\nexport const EMBEDDINGS_MODEL_CATALOG: Record<EmbeddingsProvider_Model, Embeddings_ModelCatalogEntry> = {\n [EmbeddingsProvider_Model.OPEN_AI_TEXT_EMBEDDING_3_SMALL]: {\n providerRef: \"openai\",\n dims: 1536,\n applicabilities: [Embeddings_Applicability.RAG_DEFAULT],\n },\n [EmbeddingsProvider_Model.OPEN_AI_TEXT_EMBEDDING_3_LARGE]: {\n providerRef: \"openai\",\n dims: 3072,\n // Deliberately NOT auto-selected for RAG_DEFAULT: 2× the storage + ANN cost for a quality\n // delta most application corpora do not need. Selection is framework-owned: the public\n // resolver exposes no per-application preference override. Selecting this model would\n // require a framework applicability/preference change, with corpus migration implications.\n applicabilities: [],\n },\n};\n\n/\n The framework's DEFAULT answer to \"which embedding model serves this class\", ordered by\n * preference, highest first. THIS BINDING IS THE MIGRATION KEY (RAG plan §3.d): editing it\n * changes what `resolveEmbeddingsModelForApplicability` answers, which makes every chunk stamped\n * with the previous model a migration candidate the drain worker re-embeds — bounded per run,\n * converging over runs. No agent/worker definition changes.\n /\nexport const EMBEDDINGS_MODEL_APPLICABILITY_PREFERENCE: Record<Embeddings_Applicability, readonly EmbeddingsProvider_Model[]> = {\n [Embeddings_Applicability.RAG_DEFAULT]: [\n EmbeddingsProvider_Model.OPEN_AI_TEXT_EMBEDDING_3_SMALL,\n ],\n};\n\n/\n An embedding model a provider the engine does NOT ship declares it serves (#2516) — the embeddings mirror of\n * `LLM_ModelDeclaration`. The catalog is an exhaustive record over {@link EmbeddingsProvider_Model}, so a registry\n * vendor declares its models on its embeddings arm instead of adding a row.\n \n `dims` is as load-bearing here as on a catalog row: the drain worker verifies every returned vector against it, and the\n * per-dimension vector index is keyed by it. It must be the model's published output dimension.\n /\nexport type Embeddings_ModelDeclaration = {\n model: string;\n dims: number;\n applicabilities: readonly Embeddings_Applicability[];\n};\n\n/\n Why a provider's declared embedding models ({@link Embeddings_ModelDeclaration}) cannot be used, or `undefined`\n * (#2516). Absent is fine: an engine provider has none. A registry module is loaded at runtime, so nothing compiled its\n * `models`; `dims` in particular decides which vector index a chunk enters, so it must be a positive integer.\n /\nexport const describeEmbeddingsModelDeclarationsDefect = (models: unknown): string \| undefined => {\n if (models === undefined) return undefined;\n if (!Array.isArray(models)) return \"are not a list\";\n const applicabilities = new Set<unknown>(Object.values(Embeddings_Applicability));\n const seen = new Set<string>();\n for (const [index, declaration] of models.entries()) {\n if (typeof declaration !== \"object\" \|\| declaration === null \|\| Array.isArray(declaration)) return `have no \\`model\\` at position ${index}`;\n const { model, dims, applicabilities: declared } = declaration as Record<string, unknown>;\n if (typeof model !== \"string\" \|\| model.trim().length === 0) return `have no \\`model\\` at position ${index}`;\n if (seen.has(model)) return `declare \"${model}\" twice`;\n seen.add(model);\n if (typeof dims !== \"number\" \|\| !Number.isInteger(dims) \|\| dims <= 0) return `give \"${model}\" no positive integer \\`dims\\``;\n if (!Array.isArray(declared) \|\| !declared.every((member) => applicabilities.has(member))) return `give \"${model}\" unknown \\`applicabilities\\``;\n }\n return undefined;\n};\n\n/\n Whether the engine's embedding catalog knows this provider, which decides where its model facts come from (#2516): catalog\n * rows for an engine provider, the provider's own `models` declaration otherwise.\n /\nexport const isEmbeddingsCatalogProvider = (\n providerRef: string,\n catalog: Record<EmbeddingsProvider_Model, Embeddings_ModelCatalogEntry> = EMBEDDINGS_MODEL_CATALOG,\n): boolean => Object.values(catalog).some((entry) => entry.providerRef === providerRef);\n\n/* Why {@link resolveEmbeddingsModelForApplicability} could not answer — carried into a named CONFIGURATION error. /\nexport enum Embeddings_ModelResolutionFailure {\n /* The applicability has no candidate at all for this provider. /\n NO_CANDIDATE_FOR_PROVIDER = \"no_candidate_for_provider\",\n /* An engine provider (one the catalog knows) also declares models; its models are catalog rows, so it is refused. /\n CATALOG_PROVIDER_DECLARES_MODELS = \"catalog_provider_declares_models\",\n /* A declared model's `dims` is not a positive integer, so nothing could verify or index its vectors. /\n DECLARED_DIMS_INVALID = \"declared_dims_invalid\",\n}\n\nexport type Embeddings_ModelResolution =\n \| { resolved: true; model: string; dims: number }\n \| { resolved: false; failure: Embeddings_ModelResolutionFailure; consideredModels: readonly string[] };\n\n/\n Resolve an applicability class to ONE concrete embedding model for a given provider.\n \n Fails CLOSED and explains itself (the `resolveModelForApplicability` contract): a silent\n * fallback to some other model would fracture the vector space the class exists to keep whole.\n * The resolved `(class, model)` pair is what the RAG drain worker stamps on every chunk and what\n * its migration pass compares stamps against.\n \n Two sources, decided by whether the catalog knows the provider (as `resolveModelForApplicability`, #2516): an engine\n * provider resolves through the preference and catalog and is refused if it also declares models; any other provider\n * resolves from its `declaredModels`, the first declaring the applicability.\n /\nexport const resolveEmbeddingsModelForApplicability = (\n input: { applicability: Embeddings_Applicability; providerRef: string; declaredModels?: readonly Embeddings_ModelDeclaration[] },\n catalog: Record<EmbeddingsProvider_Model, Embeddings_ModelCatalogEntry> = EMBEDDINGS_MODEL_CATALOG,\n): Embeddings_ModelResolution => {\n const declared = input.declaredModels ?? [];\n const catalogKnowsProvider = isEmbeddingsCatalogProvider(input.providerRef, catalog);\n if (catalogKnowsProvider && declared.length > 0) {\n return { resolved: false, failure: Embeddings_ModelResolutionFailure.CATALOG_PROVIDER_DECLARES_MODELS, consideredModels: declared.map((entry) => entry.model) };\n }\n if (!catalogKnowsProvider) {\n const chosen = declared.find((entry) => entry.applicabilities.includes(input.applicability));\n if (chosen === undefined) {\n return { resolved: false, failure: Embeddings_ModelResolutionFailure.NO_CANDIDATE_FOR_PROVIDER, consideredModels: declared.map((entry) => entry.model) };\n }\n if (!Number.isInteger(chosen.dims) \|\| chosen.dims <= 0) {\n return { resolved: false, failure: Embeddings_ModelResolutionFailure.DECLARED_DIMS_INVALID, consideredModels: [chosen.model] };\n }\n return { resolved: true, model: chosen.model, dims: chosen.dims };\n }\n const candidates = EMBEDDINGS_MODEL_APPLICABILITY_PREFERENCE[input.applicability];\n const forProvider = candidates.filter((model) => {\n const entry = catalog[model];\n return entry.providerRef === input.providerRef && entry.applicabilities.includes(input.applicability);\n });\n if (forProvider.length === 0) {\n return { resolved: false, failure: Embeddings_ModelResolutionFailure.NO_CANDIDATE_FOR_PROVIDER, consideredModels: candidates };\n }\n const model = forProvider[0]!;\n return { resolved: true, model, dims: catalog[model].dims };\n};\n\n// ===============================================================\n// Embeddings Operations Context\n// ===============================================================\n\n/\n Usage of one embedding call. There is NO completion-token dimension — an embedding consumes\n * input tokens and produces vectors, so usage-completeness for an embedding trace is judged on\n * `inputTokens` alone (H4: an embedding trace must never be flagged token-incomplete for lacking\n * completion tokens it structurally cannot have).\n /\nexport const EmbeddingsProvider_UsageSchema = z.object({\n /* Provider-reported input tokens, when the model reports them (OpenAI does). /\n inputTokens: z.number().optional(),\n});\nexport type EmbeddingsProvider_Usage = z.infer<typeof EmbeddingsProvider_UsageSchema>;\n\nexport const EmbeddingsProvider_ExecutionTransportMetadataSchema = z.object({\n protocolKind: z.literal(ExternalProvider_ExchangeProtocol_Kind.EMBEDDINGS_PROVIDER),\n providerRef: z.string(),\n model: z.string().optional(),\n});\nexport type EmbeddingsProvider_ExecutionTransportMetadata = z.infer<typeof EmbeddingsProvider_ExecutionTransportMetadataSchema>;\n\n// ===============================================================\n// Embeddings I/O Schemas\n// ===============================================================\n\n/* Input of the {@link EmbeddingsProvider_OperationKey.EMBED_TEXTS} operation. /\nexport const EmbeddingsProvider_EmbedTextsInputSchema = z.object({\n /* The texts to embed — one vector is returned per text, in this order. /\n texts: z.array(z.string()).min(1),\n /* Why these texts are embedded — see {@link EmbeddingsProvider_TextPurpose}. /\n purpose: z.enum(EmbeddingsProvider_TextPurpose),\n});\nexport type EmbeddingsProvider_EmbedTextsInput = z.infer<typeof EmbeddingsProvider_EmbedTextsInputSchema>;\n\n/\n Output of {@link EmbeddingsProvider_OperationKey.EMBED_TEXTS}. `vectors[i]` embeds `texts[i]`.\n \n ⚠️ PRIVACY/OBSERVABILITY CONTRACT: raw vectors are a lossy ENCODING of the source text, not\n * telemetry — they must NEVER reach analytics events, traces, or logs at any verbosity. Consumers\n * summarize (`vectorCount`, `dims`) instead; the PostHog sink's embedding arm enforces this\n * defensively even against a mis-built trace.\n /\nexport const EmbeddingsProvider_EmbedTextsOutputSchema = z.object({\n vectors: z.array(z.array(z.number())),\n /* The concrete model that produced the vectors — the chunk rows' `embeddingModel` stamp. /\n model: z.string(),\n /* The (verified) dimension every returned vector carries — the `embeddingDims` stamp. */\n dims: z.number().int().positive(),\n usage: EmbeddingsProvider_UsageSchema,\n});\nexport type EmbeddingsProvider_EmbedTextsOutput = z.infer<typeof EmbeddingsProvider_EmbedTextsOutputSchema>;\n\n"]}

package/dist/esm/protocols/file-storage.standard-interface.d.ts CHANGED Viewed

@@ -70,7 +70,13 @@ export declare enum ProviderFileStorageFailureKind {
     /** The reference cannot be a file here (a folder, a vendor-native document with no bytes, a malformed id). */
     INVALID_REFERENCE = "INVALID_REFERENCE",
     /** The vendor failed or could not be reached. */
-    VENDOR_FAILURE = "VENDOR_FAILURE"
+    VENDOR_FAILURE = "VENDOR_FAILURE",
+    /**
+     * The vendor's hash of the stored file differs from the hash of the bytes the adapter sent (#2965). The adapter removes
+     * its copy at the vendor before throwing and says in the message whether that worked: a mismatched copy is the
+     * adapter's own upload, never the owner's document. The engine refuses it as `FileIntegrityErrorCode.CONTENT_CHECKSUM_MISMATCH`.
+     */
+    CONTENT_CHECKSUM_MISMATCH = "CONTENT_CHECKSUM_MISMATCH"
 }
 /**
  * The failure an adapter throws. Anything else an adapter throws is treated as `VENDOR_FAILURE`, so a
@@ -118,7 +124,8 @@ export interface ProviderFileStorageUploadRequest {
     readonly body: AsyncIterable<Uint8Array>;
     /**
      * SHA-256 of `body`, lowercase hex, when the engine computed it before uploading (#2900). An adapter whose vendor
-     * reports a hash of the stored bytes may compare it and throw on a mismatch; no adapter does yet (#2965). The engine
+     * reports a hash of the stored bytes compares it (the hash itself, or a vendor hash of the bytes it hashed and sent)
+     * and throws `CONTENT_CHECKSUM_MISMATCH` on a mismatch, as the engine's `ONEDRIVE` adapter does (#2965). The engine
      * checks the bytes it streamed to the adapter against this hash either way.
      */
     readonly contentSha256?: string;

package/dist/esm/protocols/file-storage.standard-interface.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"file-storage.standard-interface.d.ts","sourceRoot":"","sources":["~~../../../../~~src/protocols/file-storage.standard-interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,OAAO,KAAK,EAAE,sCAAsC,EAAE,MAAM,qDAAqD,CAAC;AAElH,2HAA2H;AAE3H;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,6BAA6B,GACrC,sCAAsC,CAAC,IAAI,GAC3C,sCAAsC,CAAC,YAAY,CAAC;AAExD,kEAAkE;AAClE,oBAAY,iCAAiC;IAC3C,gGAAgG;IAChG,aAAa,kBAAkB;IAC/B;;;;OAIG;IACH,iBAAiB,sBAAsB;CACxC;AAED,iGAAiG;AACjG,oBAAY,8BAA8B;IACxC,oDAAoD;IACpD,SAAS,cAAc;IACvB,2GAA2G;IAC3G,aAAa,kBAAkB;IAC/B,8GAA8G;IAC9G,iBAAiB,sBAAsB;IACvC,iDAAiD;IACjD,cAAc,mBAAmB;~~CAClC~~;AAED;;;GAGG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,IAAI,EAAE,8BAA8B,CAAC;IAC9C;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEb,IAAI,EAAE,8BAA8B,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAM1G;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,2CAA2C;AAC3C,MAAM,WAAW,8BAA8B;IAC7C,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4GAA4G;IAC5G,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,MAAM,EAAE,yBAAyB,CAAC;IAC3C,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACzC~~;;;;OAIG~~;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,MAAM,EAAE,yBAAyB,CAAC;IAC3C,mFAAmF;IACnF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,GAAG,mBAAmB,EAAE,CAAC;IAC3C,QAAQ,CAAC,UAAU,EAAE,6BAA6B,CAAC;IACnD,QAAQ,CAAC,cAAc,EAAE,iCAAiC,CAAC;IAC3D;;;;OAIG;IACH,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;IAC1C,MAAM,CAAC,OAAO,EAAE,gCAAgC,GAAG,OAAO,CAAC;QAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5F,QAAQ,CAAC,OAAO,EAAE,mCAAmC,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;IAC7F,QAAQ,CAAC,OAAO,EAAE,mCAAmC,GAAG,OAAO,CAAC,8BAA8B,CAAC,CAAC;IAChG,4DAA4D;IAC5D,MAAM,CAAC,OAAO,EAAE,mCAAmC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrE;AAED,6EAA6E"}
1	+ {"version":3,"file":"file-storage.standard-interface.d.ts","sourceRoot":"","sources":["../../../src/protocols/file-storage.standard-interface.ts"],"names":[],"mappings":"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"}

package/dist/esm/protocols/file-storage.standard-interface.js CHANGED Viewed

@@ -55,6 +55,12 @@ export var ProviderFileStorageFailureKind;
     ProviderFileStorageFailureKind["INVALID_REFERENCE"] = "INVALID_REFERENCE";
     /** The vendor failed or could not be reached. */
     ProviderFileStorageFailureKind["VENDOR_FAILURE"] = "VENDOR_FAILURE";
+    /**
+     * The vendor's hash of the stored file differs from the hash of the bytes the adapter sent (#2965). The adapter removes
+     * its copy at the vendor before throwing and says in the message whether that worked: a mismatched copy is the
+     * adapter's own upload, never the owner's document. The engine refuses it as `FileIntegrityErrorCode.CONTENT_CHECKSUM_MISMATCH`.
+     */
+    ProviderFileStorageFailureKind["CONTENT_CHECKSUM_MISMATCH"] = "CONTENT_CHECKSUM_MISMATCH";
 })(ProviderFileStorageFailureKind || (ProviderFileStorageFailureKind = {}));
 /**
  * The failure an adapter throws. Anything else an adapter throws is treated as `VENDOR_FAILURE`, so a

package/dist/esm/protocols/file-storage.standard-interface.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"file-storage.standard-interface.js","sourceRoot":"","sources":["../../../../src/protocols/file-storage.standard-interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AA0BH,kEAAkE;AAClE,MAAM,CAAN,IAAY,iCASX;AATD,WAAY,iCAAiC;IAC3C,gGAAgG;IAChG,oEAA+B,CAAA;IAC/B;;;;OAIG;IACH,4EAAuC,CAAA;AACzC,CAAC,EATW,iCAAiC,KAAjC,iCAAiC,QAS5C;AAED,iGAAiG;AACjG,MAAM,CAAN,IAAY,8BASX;AATD,WAAY,8BAA8B;IACxC,oDAAoD;IACpD,yDAAuB,CAAA;IACvB,2GAA2G;IAC3G,iEAA+B,CAAA;IAC/B,8GAA8G;IAC9G,yEAAuC,CAAA;IACvC,iDAAiD;IACjD,mEAAiC,CAAA;AACnC,CAAC,EATW,8BAA8B,KAA9B,8BAA8B,QASzC;AAED;;;GAGG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAC1C,IAAI,CAAiC;IAC9C;;;OAGG;IACM,MAAM,CAAU;IAEzB,YAAY,IAAoC,EAAE,OAAe,EAAE,OAAsC;QACvG,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,OAAO,EAAE,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAClE,CAAC;CACF;AAoGD,6EAA6E","sourcesContent":["/*\n Standard File Storage Adapter Interface (#1674)\n * --------\n * The contract a PROVIDER implements so a file storage whose bytes live at a vendor — a person's\n * OneDrive, an organization's SharePoint library, a Dropbox folder — can be contributed by a package\n * instead of being wired into the engine.\n \n ## Why it lives here, below the backend library\n \n The engine's storage contract (`IFileStorageProvider` in `@wildo-ai/saas-backend-lib`) takes the\n * backend library's `ExecutionContext`. A provider package depends on\n * `@wildo-ai/external-connectors-private`, which `saas-backend-lib` itself depends on, so a package\n * could not implement that interface without a dependency edge pointing the wrong way — the same\n * constraint billing met in #336. This contract sits in `@wildo-ai/external-connectors-models`, below\n * both sides, and deliberately knows nothing about execution contexts, tenants or stored credentials:\n * an adapter receives the ACCESS the engine resolved for one call and the file identifiers, and does\n * the vendor's half of the work.\n \n The engine wraps every contributed adapter in its own `IFileStorageProvider`, which keeps everything\n * an adapter must not decide for itself: which grant a file is read through (the person who linked or\n * uploaded it, or the file's organization), the recorded credential use naming the connection and the\n * contributing package, input validation and size limits, and the mapping of a vendor failure onto the\n * application's error vocabulary.\n \n ## What it rejects, on purpose\n \n Supersedes #336's decision D10 (\"file storage stays a separate registry, revisited when a storage\n * vendor package is actually wanted\"): Microsoft storage is now wanted from a package. The rejected\n * alternative was #336's billing pattern — a registry of ENGINE-shipped adapters keyed by a declared\n * name — because it keeps the implementation in the engine and so can never admit a package's adapter.\n \n The storage VOCABULARY stays closed. An adapter serves a member of `FileStorageAccepted` the engine\n * already declares; it never adds a member. A declared member nothing serves remains a startup refusal.\n /\n\nimport type { FileStorageAccepted } from '@wildo-ai/zod-decorators';\n\nimport type { ExternalProvider_Connection_OwnerScope } from '../core/security.external-connectors-models.schemas';\n\n/* @wildo_source:part:start external-connectors.models.file-storage-adapter facet:kind:api facet:audience:app-developer /\n\n/\n WHOSE grant a file in this storage is read and written through. A subset of the connection owner\n * vocabulary, not a new one: a vendor storage is reachable through a person's connection or an\n * organization's, never through the application's own account (the application's own bytes live in the\n * framework's storages).\n \n - `USER` — the person who LINKED or UPLOADED the file (the row's `uploadedBy`). Another reader still\n * reads it: the application authorizes the ROW, and the storage reads the BYTES as that person.\n * - `ORGANIZATION` — the organization the file belongs to (the row's `organizationId`, which only an\n * organization-scoped file carries).\n \n Both are already on the file row, which is what lets erasure and retention reach a file held in\n * someone's own drive.\n /\nexport type ProviderFileStorageGrantOwner =\n \| ExternalProvider_Connection_OwnerScope.USER\n \| ExternalProvider_Connection_OwnerScope.ORGANIZATION;\n\n/* What removing a file's row does to the bytes at the vendor. /\nexport enum ProviderFileStorageDeleteBehavior {\n /* The bytes are the application's, kept at the vendor on its behalf: `delete` removes them. /\n REMOVES_BYTES = 'REMOVES_BYTES',\n /\n The bytes are the owner's own document (a person's file they linked): `delete` forgets the\n * reference and never calls the vendor. Deleting someone's document because an application row went\n * away is an irreversible act that needs a deliberate door of its own.\n /\n FORGETS_REFERENCE = 'FORGETS_REFERENCE',\n}\n\n/* Why an adapter could not do what it was asked. The engine maps each to its own error type. /\nexport enum ProviderFileStorageFailureKind {\n /* The vendor knows no such file for this grant. /\n NOT_FOUND = 'NOT_FOUND',\n /* The vendor refused the grant for this file (revoked, insufficient scope, not shared with the owner). /\n ACCESS_DENIED = 'ACCESS_DENIED',\n /* The reference cannot be a file here (a folder, a vendor-native document with no bytes, a malformed id). /\n INVALID_REFERENCE = 'INVALID_REFERENCE',\n /* The vendor failed or could not be reached. /\n VENDOR_FAILURE = 'VENDOR_FAILURE',\n}\n\n/\n The failure an adapter throws. Anything else an adapter throws is treated as `VENDOR_FAILURE`, so a\n * vendor SDK's own error never reaches a person as an unexplained 500.\n /\nexport class ProviderFileStorageFailure extends Error {\n readonly kind: ProviderFileStorageFailureKind;\n /\n The HTTP status the vendor answered with, when it answered. Recorded on the outbound record, so a reviewer\n * can tell a vendor that refused from one that never answered. Leave it out when nothing came back.\n /\n readonly status?: number;\n\n constructor(kind: ProviderFileStorageFailureKind, message: string, options?: { readonly status?: number }) {\n super(message);\n this.name = 'ProviderFileStorageFailure';\n this.kind = kind;\n if (options?.status !== undefined) this.status = options.status;\n }\n}\n\n/\n The access the engine resolved for ONE call: the delegated token of the grant the file lives under.\n * Resolved, recorded as a credential use and handed over per call, so an adapter never holds a\n * credential between calls and never chooses whose it is.\n /\nexport interface ProviderFileStorageAccess {\n readonly accessToken: string;\n}\n\n/* What the vendor says about one file. /\nexport interface ProviderFileStorageDescription {\n /* The vendor's display name for the file. /\n readonly name: string;\n readonly contentType: string;\n /* Size in bytes. A vendor-native document with no bytes cannot be described: throw `INVALID_REFERENCE`. /\n readonly size: number;\n readonly etag?: string;\n readonly lastModified?: Date;\n}\n\nexport interface ProviderFileStorageUploadRequest {\n readonly access: ProviderFileStorageAccess;\n /* The application's id for the file — stable, never shown to a person. /\n readonly fileId: string;\n /* The name to give the file at the vendor. /\n readonly fileName: string;\n readonly contentType: string;\n /* The size the engine already validated against the application's limit. /\n readonly size: number;\n /* The bytes, streamed. Already bounded by the engine. /\n readonly body: AsyncIterable<Uint8Array>;\n /\n SHA-256 of `body`, lowercase hex, when the engine computed it before uploading (#2900). An adapter whose vendor\n * reports a hash of the stored bytes may compare it and throw on a mismatch; no adapter does yet (#2965). The engine\n * checks the bytes it streamed to the adapter against this hash either way.\n /\n readonly contentSha256?: string;\n}\n\nexport interface ProviderFileStorageReferenceRequest {\n readonly access: ProviderFileStorageAccess;\n /* The vendor's id for the file, as `upload` returned it or a picker linked it. /\n readonly storageRef: string;\n}\n\nexport interface ProviderFileStorageDownload {\n readonly body: AsyncIterable<Uint8Array>;\n readonly contentType: string;\n readonly size: number;\n readonly etag?: string;\n readonly lastModified?: Date;\n}\n\n/\n A file storage a provider contributes. Declared on the provider's backend module\n * (`fileStorageAdapters`); the grant it spends is ITS OWN provider's connection — a module cannot\n * point an adapter at another provider's grant — so a package whose ref belongs to a declared shared\n * connection (`microsoft`, #1725) stores through that one connection.\n \n @example\n * ```ts\n * export const oneDriveStorage: ProviderFileStorageAdapter = {\n * storage: FileStorageAccepted.ONEDRIVE,\n * grantOwner: ExternalProvider_Connection_OwnerScope.USER,\n * deleteBehavior: ProviderFileStorageDeleteBehavior.FORGETS_REFERENCE,\n * acceptsRemoteReferences: true,\n * upload: async ({ access, fileName, body }) => ({ storageRef: await putDriveItem(access, fileName, body) }),\n * download: async ({ access, storageRef }) => getDriveItemContent(access, storageRef),\n * describe: async ({ access, storageRef }) => getDriveItem(access, storageRef),\n * delete: async () => undefined,\n * };\n * ```\n /\nexport interface ProviderFileStorageAdapter {\n /\n The declared storage member this adapter serves. Exactly one adapter may serve a member.\n \n Typed as the member's VALUE (`'onedrive'`) rather than the `@wildo-ai/zod-decorators` enum, so a provider package\n * names it through the vocabulary it can already reach — `FileStorageAccepted.ONEDRIVE` from `@wildo-ai/saas-models`,\n * whose members are held equal to the enum's — without taking a dependency on the decorator package. The set stays\n * closed: the engine refuses a value that is not a member when it admits the adapter.\n /\n readonly storage: `${FileStorageAccepted}`;\n readonly grantOwner: ProviderFileStorageGrantOwner;\n readonly deleteBehavior: ProviderFileStorageDeleteBehavior;\n /\n Whether a person may LINK a file that already exists at the vendor (a picker's\n * `REMOTE_REFERENCE`). When true, the engine describes the reference through the linker's grant\n * before a row is created — which is also the proof the reference is real and reachable by them.\n /\n readonly acceptsRemoteReferences: boolean;\n upload(request: ProviderFileStorageUploadRequest): Promise<{ readonly storageRef: string }>;\n download(request: ProviderFileStorageReferenceRequest): Promise<ProviderFileStorageDownload>;\n describe(request: ProviderFileStorageReferenceRequest): Promise<ProviderFileStorageDescription>;\n /* Called only when `deleteBehavior` is `REMOVES_BYTES`. /\n delete(request: ProviderFileStorageReferenceRequest): Promise<void>;\n}\n\n/* @wildo_source:part:end external-connectors.models.file-storage-adapter */\n"]}
1	+ {"version":3,"file":"file-storage.standard-interface.js","sourceRoot":"","sources":["../../../src/protocols/file-storage.standard-interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AA0BH,kEAAkE;AAClE,MAAM,CAAN,IAAY,iCASX;AATD,WAAY,iCAAiC;IAC3C,gGAAgG;IAChG,oEAA+B,CAAA;IAC/B;;;;OAIG;IACH,4EAAuC,CAAA;AACzC,CAAC,EATW,iCAAiC,KAAjC,iCAAiC,QAS5C;AAED,iGAAiG;AACjG,MAAM,CAAN,IAAY,8BAeX;AAfD,WAAY,8BAA8B;IACxC,oDAAoD;IACpD,yDAAuB,CAAA;IACvB,2GAA2G;IAC3G,iEAA+B,CAAA;IAC/B,8GAA8G;IAC9G,yEAAuC,CAAA;IACvC,iDAAiD;IACjD,mEAAiC,CAAA;IACjC;;;;OAIG;IACH,yFAAuD,CAAA;AACzD,CAAC,EAfW,8BAA8B,KAA9B,8BAA8B,QAezC;AAED;;;GAGG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAC1C,IAAI,CAAiC;IAC9C;;;OAGG;IACM,MAAM,CAAU;IAEzB,YAAY,IAAoC,EAAE,OAAe,EAAE,OAAsC;QACvG,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,OAAO,EAAE,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAClE,CAAC;CACF;AAqGD,6EAA6E","sourcesContent":["/*\n Standard File Storage Adapter Interface (#1674)\n * --------\n * The contract a PROVIDER implements so a file storage whose bytes live at a vendor — a person's\n * OneDrive, an organization's SharePoint library, a Dropbox folder — can be contributed by a package\n * instead of being wired into the engine.\n \n ## Why it lives here, below the backend library\n \n The engine's storage contract (`IFileStorageProvider` in `@wildo-ai/saas-backend-lib`) takes the\n * backend library's `ExecutionContext`. A provider package depends on\n * `@wildo-ai/external-connectors-private`, which `saas-backend-lib` itself depends on, so a package\n * could not implement that interface without a dependency edge pointing the wrong way — the same\n * constraint billing met in #336. This contract sits in `@wildo-ai/external-connectors-models`, below\n * both sides, and deliberately knows nothing about execution contexts, tenants or stored credentials:\n * an adapter receives the ACCESS the engine resolved for one call and the file identifiers, and does\n * the vendor's half of the work.\n \n The engine wraps every contributed adapter in its own `IFileStorageProvider`, which keeps everything\n * an adapter must not decide for itself: which grant a file is read through (the person who linked or\n * uploaded it, or the file's organization), the recorded credential use naming the connection and the\n * contributing package, input validation and size limits, and the mapping of a vendor failure onto the\n * application's error vocabulary.\n \n ## What it rejects, on purpose\n \n Supersedes #336's decision D10 (\"file storage stays a separate registry, revisited when a storage\n * vendor package is actually wanted\"): Microsoft storage is now wanted from a package. The rejected\n * alternative was #336's billing pattern — a registry of ENGINE-shipped adapters keyed by a declared\n * name — because it keeps the implementation in the engine and so can never admit a package's adapter.\n \n The storage VOCABULARY stays closed. An adapter serves a member of `FileStorageAccepted` the engine\n * already declares; it never adds a member. A declared member nothing serves remains a startup refusal.\n /\n\nimport type { FileStorageAccepted } from '@wildo-ai/zod-decorators';\n\nimport type { ExternalProvider_Connection_OwnerScope } from '../core/security.external-connectors-models.schemas';\n\n/* @wildo_source:part:start external-connectors.models.file-storage-adapter facet:kind:api facet:audience:app-developer /\n\n/\n WHOSE grant a file in this storage is read and written through. A subset of the connection owner\n * vocabulary, not a new one: a vendor storage is reachable through a person's connection or an\n * organization's, never through the application's own account (the application's own bytes live in the\n * framework's storages).\n \n - `USER` — the person who LINKED or UPLOADED the file (the row's `uploadedBy`). Another reader still\n * reads it: the application authorizes the ROW, and the storage reads the BYTES as that person.\n * - `ORGANIZATION` — the organization the file belongs to (the row's `organizationId`, which only an\n * organization-scoped file carries).\n \n Both are already on the file row, which is what lets erasure and retention reach a file held in\n * someone's own drive.\n /\nexport type ProviderFileStorageGrantOwner =\n \| ExternalProvider_Connection_OwnerScope.USER\n \| ExternalProvider_Connection_OwnerScope.ORGANIZATION;\n\n/* What removing a file's row does to the bytes at the vendor. /\nexport enum ProviderFileStorageDeleteBehavior {\n /* The bytes are the application's, kept at the vendor on its behalf: `delete` removes them. /\n REMOVES_BYTES = 'REMOVES_BYTES',\n /\n The bytes are the owner's own document (a person's file they linked): `delete` forgets the\n * reference and never calls the vendor. Deleting someone's document because an application row went\n * away is an irreversible act that needs a deliberate door of its own.\n /\n FORGETS_REFERENCE = 'FORGETS_REFERENCE',\n}\n\n/* Why an adapter could not do what it was asked. The engine maps each to its own error type. /\nexport enum ProviderFileStorageFailureKind {\n /* The vendor knows no such file for this grant. /\n NOT_FOUND = 'NOT_FOUND',\n /* The vendor refused the grant for this file (revoked, insufficient scope, not shared with the owner). /\n ACCESS_DENIED = 'ACCESS_DENIED',\n /* The reference cannot be a file here (a folder, a vendor-native document with no bytes, a malformed id). /\n INVALID_REFERENCE = 'INVALID_REFERENCE',\n /* The vendor failed or could not be reached. /\n VENDOR_FAILURE = 'VENDOR_FAILURE',\n /\n The vendor's hash of the stored file differs from the hash of the bytes the adapter sent (#2965). The adapter removes\n * its copy at the vendor before throwing and says in the message whether that worked: a mismatched copy is the\n * adapter's own upload, never the owner's document. The engine refuses it as `FileIntegrityErrorCode.CONTENT_CHECKSUM_MISMATCH`.\n /\n CONTENT_CHECKSUM_MISMATCH = 'CONTENT_CHECKSUM_MISMATCH',\n}\n\n/\n The failure an adapter throws. Anything else an adapter throws is treated as `VENDOR_FAILURE`, so a\n * vendor SDK's own error never reaches a person as an unexplained 500.\n /\nexport class ProviderFileStorageFailure extends Error {\n readonly kind: ProviderFileStorageFailureKind;\n /\n The HTTP status the vendor answered with, when it answered. Recorded on the outbound record, so a reviewer\n * can tell a vendor that refused from one that never answered. Leave it out when nothing came back.\n /\n readonly status?: number;\n\n constructor(kind: ProviderFileStorageFailureKind, message: string, options?: { readonly status?: number }) {\n super(message);\n this.name = 'ProviderFileStorageFailure';\n this.kind = kind;\n if (options?.status !== undefined) this.status = options.status;\n }\n}\n\n/\n The access the engine resolved for ONE call: the delegated token of the grant the file lives under.\n * Resolved, recorded as a credential use and handed over per call, so an adapter never holds a\n * credential between calls and never chooses whose it is.\n /\nexport interface ProviderFileStorageAccess {\n readonly accessToken: string;\n}\n\n/* What the vendor says about one file. /\nexport interface ProviderFileStorageDescription {\n /* The vendor's display name for the file. /\n readonly name: string;\n readonly contentType: string;\n /* Size in bytes. A vendor-native document with no bytes cannot be described: throw `INVALID_REFERENCE`. /\n readonly size: number;\n readonly etag?: string;\n readonly lastModified?: Date;\n}\n\nexport interface ProviderFileStorageUploadRequest {\n readonly access: ProviderFileStorageAccess;\n /* The application's id for the file — stable, never shown to a person. /\n readonly fileId: string;\n /* The name to give the file at the vendor. /\n readonly fileName: string;\n readonly contentType: string;\n /* The size the engine already validated against the application's limit. /\n readonly size: number;\n /* The bytes, streamed. Already bounded by the engine. /\n readonly body: AsyncIterable<Uint8Array>;\n /\n SHA-256 of `body`, lowercase hex, when the engine computed it before uploading (#2900). An adapter whose vendor\n * reports a hash of the stored bytes compares it (the hash itself, or a vendor hash of the bytes it hashed and sent)\n * and throws `CONTENT_CHECKSUM_MISMATCH` on a mismatch, as the engine's `ONEDRIVE` adapter does (#2965). The engine\n * checks the bytes it streamed to the adapter against this hash either way.\n /\n readonly contentSha256?: string;\n}\n\nexport interface ProviderFileStorageReferenceRequest {\n readonly access: ProviderFileStorageAccess;\n /* The vendor's id for the file, as `upload` returned it or a picker linked it. /\n readonly storageRef: string;\n}\n\nexport interface ProviderFileStorageDownload {\n readonly body: AsyncIterable<Uint8Array>;\n readonly contentType: string;\n readonly size: number;\n readonly etag?: string;\n readonly lastModified?: Date;\n}\n\n/\n A file storage a provider contributes. Declared on the provider's backend module\n * (`fileStorageAdapters`); the grant it spends is ITS OWN provider's connection — a module cannot\n * point an adapter at another provider's grant — so a package whose ref belongs to a declared shared\n * connection (`microsoft`, #1725) stores through that one connection.\n \n @example\n * ```ts\n * export const oneDriveStorage: ProviderFileStorageAdapter = {\n * storage: FileStorageAccepted.ONEDRIVE,\n * grantOwner: ExternalProvider_Connection_OwnerScope.USER,\n * deleteBehavior: ProviderFileStorageDeleteBehavior.FORGETS_REFERENCE,\n * acceptsRemoteReferences: true,\n * upload: async ({ access, fileName, body }) => ({ storageRef: await putDriveItem(access, fileName, body) }),\n * download: async ({ access, storageRef }) => getDriveItemContent(access, storageRef),\n * describe: async ({ access, storageRef }) => getDriveItem(access, storageRef),\n * delete: async () => undefined,\n * };\n * ```\n /\nexport interface ProviderFileStorageAdapter {\n /\n The declared storage member this adapter serves. Exactly one adapter may serve a member.\n \n Typed as the member's VALUE (`'onedrive'`) rather than the `@wildo-ai/zod-decorators` enum, so a provider package\n * names it through the vocabulary it can already reach — `FileStorageAccepted.ONEDRIVE` from `@wildo-ai/saas-models`,\n * whose members are held equal to the enum's — without taking a dependency on the decorator package. The set stays\n * closed: the engine refuses a value that is not a member when it admits the adapter.\n /\n readonly storage: `${FileStorageAccepted}`;\n readonly grantOwner: ProviderFileStorageGrantOwner;\n readonly deleteBehavior: ProviderFileStorageDeleteBehavior;\n /\n Whether a person may LINK a file that already exists at the vendor (a picker's\n * `REMOTE_REFERENCE`). When true, the engine describes the reference through the linker's grant\n * before a row is created — which is also the proof the reference is real and reachable by them.\n /\n readonly acceptsRemoteReferences: boolean;\n upload(request: ProviderFileStorageUploadRequest): Promise<{ readonly storageRef: string }>;\n download(request: ProviderFileStorageReferenceRequest): Promise<ProviderFileStorageDownload>;\n describe(request: ProviderFileStorageReferenceRequest): Promise<ProviderFileStorageDescription>;\n /* Called only when `deleteBehavior` is `REMOVES_BYTES`. /\n delete(request: ProviderFileStorageReferenceRequest): Promise<void>;\n}\n\n/* @wildo_source:part:end external-connectors.models.file-storage-adapter */\n"]}

package/dist/esm/protocols/frontend.external-connectors-models.schemas.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"frontend.external-connectors-models.schemas.d.ts","sourceRoot":"","sources":["~~../../../../~~src/protocols/frontend.external-connectors-models.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yCAAyC,EAAE,MAAM,uDAAuD,CAAC;AAElH;;;;;GAKG;AACH,MAAM,MAAM,0BAA0B,GAAG,yCAAyC,CAAC"}
1	+ {"version":3,"file":"frontend.external-connectors-models.schemas.d.ts","sourceRoot":"","sources":["../../../src/protocols/frontend.external-connectors-models.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yCAAyC,EAAE,MAAM,uDAAuD,CAAC;AAElH;;;;;GAKG;AACH,MAAM,MAAM,0BAA0B,GAAG,yCAAyC,CAAC"}

package/dist/esm/protocols/frontend.external-connectors-models.schemas.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"frontend.external-connectors-models.schemas.js","sourceRoot":"","sources":["~~../../../../~~src/protocols/frontend.external-connectors-models.schemas.ts"],"names":[],"mappings":"","sourcesContent":["import { ExternalProvider_OperationDefinition_Base } from \"../core/operations.external-connectors-models.schemas\";\n\n/*\n A frontend SDK provider's operation definition. The provider itself is described by the live\n * `BackendProviderModule` / `ProviderProtocolRuntimeContract` pair; the profile, configuration and\n * status triple that once sat beside this alias was the per-protocol half of the retired\n * exchange-protocol model and had no reader (#965).\n */\nexport type FrontendProvider_Operation = ExternalProvider_OperationDefinition_Base;\n"]}
1	+ {"version":3,"file":"frontend.external-connectors-models.schemas.js","sourceRoot":"","sources":["../../../src/protocols/frontend.external-connectors-models.schemas.ts"],"names":[],"mappings":"","sourcesContent":["import { ExternalProvider_OperationDefinition_Base } from \"../core/operations.external-connectors-models.schemas\";\n\n/*\n A frontend SDK provider's operation definition. The provider itself is described by the live\n * `BackendProviderModule` / `ProviderProtocolRuntimeContract` pair; the profile, configuration and\n * status triple that once sat beside this alias was the per-protocol half of the retired\n * exchange-protocol model and had no reader (#965).\n */\nexport type FrontendProvider_Operation = ExternalProvider_OperationDefinition_Base;\n"]}