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

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

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 (59) hide show

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

@@ -113,11 +113,48 @@ export const EMBEDDINGS_MODEL_APPLICABILITY_PREFERENCE = {
         EmbeddingsProvider_Model.OPEN_AI_TEXT_EMBEDDING_3_SMALL,
     ],
 };
+/**
+ * Why a provider's declared embedding models ({@link Embeddings_ModelDeclaration}) cannot be used, or `undefined`
+ * (#2516). Absent is fine: an engine provider has none. A registry module is loaded at runtime, so nothing compiled its
+ * `models`; `dims` in particular decides which vector index a chunk enters, so it must be a positive integer.
+ */
+export const describeEmbeddingsModelDeclarationsDefect = (models) => {
+    if (models === undefined)
+        return undefined;
+    if (!Array.isArray(models))
+        return "are not a list";
+    const applicabilities = new Set(Object.values(Embeddings_Applicability));
+    const seen = new Set();
+    for (const [index, declaration] of models.entries()) {
+        if (typeof declaration !== "object" || declaration === null || Array.isArray(declaration))
+            return `have no \`model\` at position ${index}`;
+        const { model, dims, applicabilities: declared } = declaration;
+        if (typeof model !== "string" || model.trim().length === 0)
+            return `have no \`model\` at position ${index}`;
+        if (seen.has(model))
+            return `declare "${model}" twice`;
+        seen.add(model);
+        if (typeof dims !== "number" || !Number.isInteger(dims) || dims <= 0)
+            return `give "${model}" no positive integer \`dims\``;
+        if (!Array.isArray(declared) || !declared.every((member) => applicabilities.has(member)))
+            return `give "${model}" unknown \`applicabilities\``;
+    }
+    return undefined;
+};
+/**
+ * Whether the engine's embedding catalog knows this provider, which decides where its model facts come from (#2516): catalog
+ * rows for an engine provider, the provider's own `models` declaration otherwise.
+ */
+export const isEmbeddingsCatalogProvider = (providerRef, catalog = EMBEDDINGS_MODEL_CATALOG) => Object.values(catalog).some((entry) => entry.providerRef === providerRef);
 /** Why {@link resolveEmbeddingsModelForApplicability} could not answer — carried into a named CONFIGURATION error. */
 export var Embeddings_ModelResolutionFailure;
 (function (Embeddings_ModelResolutionFailure) {
     /** The applicability has no candidate at all for this provider. */
     Embeddings_ModelResolutionFailure["NO_CANDIDATE_FOR_PROVIDER"] = "no_candidate_for_provider";
+    /** An engine provider (one the catalog knows) also declares models; its models are catalog rows, so it is refused. */
+    Embeddings_ModelResolutionFailure["CATALOG_PROVIDER_DECLARES_MODELS"] = "catalog_provider_declares_models";
+    /** A declared model's `dims` is not a positive integer, so nothing could verify or index its vectors. */
+    Embeddings_ModelResolutionFailure["DECLARED_DIMS_INVALID"] = "declared_dims_invalid";
 })(Embeddings_ModelResolutionFailure || (Embeddings_ModelResolutionFailure = {}));
 /**
  * Resolve an applicability class to ONE concrete embedding model for a given provider.
@@ -126,8 +163,27 @@ export var Embeddings_ModelResolutionFailure;
  * fallback to some other model would fracture the vector space the class exists to keep whole.
  * The resolved `(class, model)` pair is what the RAG drain worker stamps on every chunk and what
  * its migration pass compares stamps against.
+ *
+ * Two sources, decided by whether the catalog knows the provider (as `resolveModelForApplicability`, #2516): an engine
+ * provider resolves through the preference and catalog and is refused if it also declares models; any other provider
+ * resolves from its `declaredModels`, the first declaring the applicability.
  */
 export const resolveEmbeddingsModelForApplicability = (input, catalog = EMBEDDINGS_MODEL_CATALOG) => {
+    const declared = input.declaredModels ?? [];
+    const catalogKnowsProvider = isEmbeddingsCatalogProvider(input.providerRef, catalog);
+    if (catalogKnowsProvider && declared.length > 0) {
+        return { resolved: false, failure: Embeddings_ModelResolutionFailure.CATALOG_PROVIDER_DECLARES_MODELS, consideredModels: declared.map((entry) => entry.model) };
+    }
+    if (!catalogKnowsProvider) {
+        const chosen = declared.find((entry) => entry.applicabilities.includes(input.applicability));
+        if (chosen === undefined) {
+            return { resolved: false, failure: Embeddings_ModelResolutionFailure.NO_CANDIDATE_FOR_PROVIDER, consideredModels: declared.map((entry) => entry.model) };
+        }
+        if (!Number.isInteger(chosen.dims) || chosen.dims <= 0) {
+            return { resolved: false, failure: Embeddings_ModelResolutionFailure.DECLARED_DIMS_INVALID, consideredModels: [chosen.model] };
+        }
+        return { resolved: true, model: chosen.model, dims: chosen.dims };
+    }
     const candidates = EMBEDDINGS_MODEL_APPLICABILITY_PREFERENCE[input.applicability];
     const forProvider = candidates.filter((model) => {
         const entry = catalog[model];
@@ -137,7 +193,7 @@ export const resolveEmbeddingsModelForApplicability = (input, catalog = EMBEDDIN
         return { resolved: false, failure: Embeddings_ModelResolutionFailure.NO_CANDIDATE_FOR_PROVIDER, consideredModels: candidates };
     }
     const model = forProvider[0];
-    return { resolved: true, model, entry: catalog[model] };
+    return { resolved: true, model, dims: catalog[model].dims };
 };
 // ===============================================================
 // Embeddings Operations Context

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/* 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}\n\nexport type Embeddings_ModelResolution =\n \| { resolved: true; model: EmbeddingsProvider_Model; entry: Embeddings_ModelCatalogEntry }\n \| { resolved: false; failure: Embeddings_ModelResolutionFailure; consideredModels: readonly EmbeddingsProvider_Model[] };\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 /\nexport const resolveEmbeddingsModelForApplicability = (\n input: { applicability: Embeddings_Applicability; providerRef: string },\n catalog: Record<EmbeddingsProvider_Model, Embeddings_ModelCatalogEntry> = EMBEDDINGS_MODEL_CATALOG,\n): Embeddings_ModelResolution => {\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, entry: catalog[model] };\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":"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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"]}

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

@@ -116,6 +116,12 @@ export interface ProviderFileStorageUploadRequest {
     readonly size: number;
     /** The bytes, streamed. Already bounded by the engine. */
     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
+     * checks the bytes it streamed to the adapter against this hash either way.
+     */
+    readonly contentSha256?: string;
 }
 export interface ProviderFileStorageReferenceRequest {
     readonly access: ProviderFileStorageAccess;

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;~~CAC1C~~;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.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;AA8FD,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\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,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"]}

package/dist/esm/protocols/hooks-capability.external-connectors-models.schemas.d.ts CHANGED Viewed

@@ -52,8 +52,13 @@ export interface StandardHook_ResolvedScope {
  * and parseWebhookEvent() into the standard interface.
  */
 export interface WebhookCapabilityAdapter {
-    /** Verify the webhook signature using the capability's verification logic */
-    verifySignature(rawBody: string | Uint8Array, signatureHeader: string, secret: string): boolean | Promise<boolean>;
+    /**
+     * Verify the webhook signature using the capability's verification logic.
+     *
+     * `headers` is EVERY request header, names lower-cased (#2659): a scheme that signs a timestamp or an id
+     * carried in a second header cannot be verified from the signature header alone.
+     */
+    verifySignature(rawBody: string | Uint8Array, signatureHeader: string, secret: string, headers: Readonly<Record<string, string>>): boolean | Promise<boolean>;
     /**
      * Parse the raw webhook body into a StandardHook_ParsedEvent.
      * Returns null if the event type is unknown/unsupported (acknowledged but not processed).

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

	@@ -1 +1 @@
1	- {"version":3,"file":"hooks-capability.external-connectors-models.schemas.d.ts","sourceRoot":"","sources":["../../../../src/protocols/hooks-capability.external-connectors-models.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,OAAO,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,UAAU,EAAE,OAAO,CAAC;IACpB,sBAAsB;IACtB,SAAS,EAAE,IAAI,GAAG,MAAM,CAAC;CAC1B;AAMD;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAMD;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAwB;IACvC~~,6EAA6E~~;~~IAC7E~~,eAAe,CACb,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,MAAM,~~GACb~~,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE9B;;;OAGG;IACH,UAAU,CACR,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,wBAAwB,GAAG,IAAI,CAAC;CACpC;AAMD;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,WAAW,CACT,gBAAgB,EAAE,OAAO,EAAE,wEAAwE;IACnG,WAAW,EAAE,wBAAwB,GACpC,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,0BAA0B;IACzC,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yCAAyC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,mDAAmD;IACnD,YAAY,CAAC,WAAW,EAAE,wBAAwB,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;IAEzF,wFAAwF;IACxF,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;CAC7C"}
1	+ {"version":3,"file":"hooks-capability.external-connectors-models.schemas.d.ts","sourceRoot":"","sources":["../../../../src/protocols/hooks-capability.external-connectors-models.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,OAAO,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,UAAU,EAAE,OAAO,CAAC;IACpB,sBAAsB;IACtB,SAAS,EAAE,IAAI,GAAG,MAAM,CAAC;CAC1B;AAMD;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAMD;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,eAAe,CACb,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACxC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE9B;;;OAGG;IACH,UAAU,CACR,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,wBAAwB,GAAG,IAAI,CAAC;CACpC;AAMD;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,WAAW,CACT,gBAAgB,EAAE,OAAO,EAAE,wEAAwE;IACnG,WAAW,EAAE,wBAAwB,GACpC,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,0BAA0B;IACzC,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yCAAyC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,mDAAmD;IACnD,YAAY,CAAC,WAAW,EAAE,wBAAwB,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;IAEzF,wFAAwF;IACxF,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;CAC7C"}

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

	@@ -1 +1 @@
1	- {"version":3,"file":"hooks-capability.external-connectors-models.schemas.js","sourceRoot":"","sources":["../../../../src/protocols/hooks-capability.external-connectors-models.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG","sourcesContent":["/*\n Hook Protocol Feature Types\n * \n * Standard types for the webhook processing pipeline:\n * - StandardHook_ParsedEvent: Provider-agnostic parsed event\n * - StandardHook_ResolvedScope: Resolved engine scope from event\n * - WebhookCapabilityAdapter: Runtime contract for verify + parse\n * - WebhookCapabilityHandler: Dispatches processed events to business logic\n * - Hook_ScopeResolverStrategy: Escape hatch for custom scope resolution\n /\n\n// ===============================================================\n// Standard Parsed Event (Provider-Agnostic)\n// ===============================================================\n\n/\n A webhook event normalized to a provider-agnostic format.\n * Produced by WebhookCapabilityAdapter.parseEvent().\n /\nexport interface StandardHook_ParsedEvent {\n /* Unique event ID from the provider (for idempotency) /\n eventId: string;\n /* Standardized event type (e.g., 'SUBSCRIPTION_CREATED') /\n eventType: string;\n /* Original provider event type (e.g., 'customer.subscription.created') /\n providerEventType: string;\n /* Provider reference (e.g., 'stripe', 'google') /\n providerRef: string;\n /* Endpoint key this event was received on (e.g., 'billing', 'calendar') /\n endpointKey: string;\n /* Parsed event payload (provider-specific structure) /\n payload: unknown;\n /* Raw event payload as received (for scope ID extraction via dot-path) /\n rawPayload: unknown;\n /* Event timestamp /\n timestamp: Date \| string;\n}\n\n// ===============================================================\n// Standard Resolved Scope\n// ===============================================================\n\n/\n Framework scope resolved from a webhook event.\n * Maps to ExecutionContext initiatorIds fields.\n /\nexport interface StandardHook_ResolvedScope {\n applicationId?: string;\n organizationId?: string;\n userId?: string;\n /* Additional provider-specific scope IDs for audit/debug /\n providerScopeIds?: Record<string, string>;\n}\n\n// ===============================================================\n// Webhook Capability Adapter\n// ===============================================================\n\n/\n Adapter that bridges a capability-specific transformer\n * (e.g., StandardBilling_Interface) to the generic webhook pipeline.\n * \n * Each capability implements one adapter. The adapter normalizes\n * capability-specific verify/parse methods into the standard pipeline contract.\n * \n * Example: BillingWebhookAdapter wraps Stripe_BillingTransformer.verifyWebhookSignature()\n * and parseWebhookEvent() into the standard interface.\n /\nexport interface WebhookCapabilityAdapter {\n /* Verify the webhook signature using the capability's verification logic /\n verifySignature(\n rawBody: string \| Uint8Array~~, \~~n signatureHeader: string~~, \~~n secret: string\n ): boolean \| Promise<boolean>;\n\n /* \n * Parse the raw webhook body into a StandardHook_ParsedEvent.\n * Returns null if the event type is unknown/unsupported (acknowledged but not processed).\n /\n parseEvent(\n rawBody: string \| Uint8Array, \n headers: Record<string, string>\n ): StandardHook_ParsedEvent \| null;\n}\n\n// ===============================================================\n// Webhook Capability Handler\n// ===============================================================\n\n/\n Handles processed webhook events for a specific capability.\n * Dispatches to business logic (e.g., BillingWebhookEventRouter) with the ExecutionContext.\n * \n * Registered at startup and matched by endpoint capability.\n /\nexport interface WebhookCapabilityHandler {\n /* Which capability this handler serves (e.g., 'billing', 'calendar') /\n readonly capability: string;\n\n /* \n * Handle the processed webhook event with its execution context.\n * The executionContext carries the resolved scope and can be used for all DB operations.\n /\n handleEvent(\n executionContext: unknown, // ExecutionContext<any> — typed as unknown to avoid circular dependency\n parsedEvent: StandardHook_ParsedEvent\n ): Promise<void>;\n}\n\n// ===============================================================\n// Hook Scope Resolver Strategy (Escape Hatch)\n// ===============================================================\n\n/\n Optional override for scope resolution when the declarative\n * Hook_EndpointScopeBinding config is insufficient.\n * \n * Register with WebhookHandlerBackendService.registerCustomScopeResolver()\n * to override the generic declarative resolver for a specific endpoint.\n * \n * Use cases:\n * - Different event types within the same endpoint have scope IDs at different payload paths\n * - Complex multi-step scope resolution logic\n * - Provider-specific edge cases\n /\nexport interface Hook_ScopeResolverStrategy {\n /* Provider reference this resolver handles /\n readonly providerRef: string;\n /* Endpoint key this resolver handles /\n readonly endpointKey: string;\n\n /* Resolve the engine scope from a parsed event /\n resolveScope(parsedEvent: StandardHook_ParsedEvent): Promise<StandardHook_ResolvedScope>;\n\n /* Whether scope resolution is required for this event type (affects error handling) */\n isScopeRequired(eventType: string): boolean;\n}\n"]}
1	+ {"version":3,"file":"hooks-capability.external-connectors-models.schemas.js","sourceRoot":"","sources":["../../../../src/protocols/hooks-capability.external-connectors-models.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG","sourcesContent":["/*\n Hook Protocol Feature Types\n * \n * Standard types for the webhook processing pipeline:\n * - StandardHook_ParsedEvent: Provider-agnostic parsed event\n * - StandardHook_ResolvedScope: Resolved engine scope from event\n * - WebhookCapabilityAdapter: Runtime contract for verify + parse\n * - WebhookCapabilityHandler: Dispatches processed events to business logic\n * - Hook_ScopeResolverStrategy: Escape hatch for custom scope resolution\n /\n\n// ===============================================================\n// Standard Parsed Event (Provider-Agnostic)\n// ===============================================================\n\n/\n A webhook event normalized to a provider-agnostic format.\n * Produced by WebhookCapabilityAdapter.parseEvent().\n /\nexport interface StandardHook_ParsedEvent {\n /* Unique event ID from the provider (for idempotency) /\n eventId: string;\n /* Standardized event type (e.g., 'SUBSCRIPTION_CREATED') /\n eventType: string;\n /* Original provider event type (e.g., 'customer.subscription.created') /\n providerEventType: string;\n /* Provider reference (e.g., 'stripe', 'google') /\n providerRef: string;\n /* Endpoint key this event was received on (e.g., 'billing', 'calendar') /\n endpointKey: string;\n /* Parsed event payload (provider-specific structure) /\n payload: unknown;\n /* Raw event payload as received (for scope ID extraction via dot-path) /\n rawPayload: unknown;\n /* Event timestamp /\n timestamp: Date \| string;\n}\n\n// ===============================================================\n// Standard Resolved Scope\n// ===============================================================\n\n/\n Framework scope resolved from a webhook event.\n * Maps to ExecutionContext initiatorIds fields.\n /\nexport interface StandardHook_ResolvedScope {\n applicationId?: string;\n organizationId?: string;\n userId?: string;\n /* Additional provider-specific scope IDs for audit/debug /\n providerScopeIds?: Record<string, string>;\n}\n\n// ===============================================================\n// Webhook Capability Adapter\n// ===============================================================\n\n/\n Adapter that bridges a capability-specific transformer\n * (e.g., StandardBilling_Interface) to the generic webhook pipeline.\n * \n * Each capability implements one adapter. The adapter normalizes\n * capability-specific verify/parse methods into the standard pipeline contract.\n * \n * Example: BillingWebhookAdapter wraps Stripe_BillingTransformer.verifyWebhookSignature()\n * and parseWebhookEvent() into the standard interface.\n /\nexport interface WebhookCapabilityAdapter {\n /\n Verify the webhook signature using the capability's verification logic.\n \n `headers` is EVERY request header, names lower-cased (#2659): a scheme that signs a timestamp or an id\n * carried in a second header cannot be verified from the signature header alone.\n /\n verifySignature(\n rawBody: string \| Uint8Array,\n signatureHeader: string,\n secret: string,\n headers: Readonly<Record<string, string>>,\n ): boolean \| Promise<boolean>;\n\n /* \n * Parse the raw webhook body into a StandardHook_ParsedEvent.\n * Returns null if the event type is unknown/unsupported (acknowledged but not processed).\n /\n parseEvent(\n rawBody: string \| Uint8Array, \n headers: Record<string, string>\n ): StandardHook_ParsedEvent \| null;\n}\n\n// ===============================================================\n// Webhook Capability Handler\n// ===============================================================\n\n/\n Handles processed webhook events for a specific capability.\n * Dispatches to business logic (e.g., BillingWebhookEventRouter) with the ExecutionContext.\n * \n * Registered at startup and matched by endpoint capability.\n /\nexport interface WebhookCapabilityHandler {\n /* Which capability this handler serves (e.g., 'billing', 'calendar') /\n readonly capability: string;\n\n /* \n * Handle the processed webhook event with its execution context.\n * The executionContext carries the resolved scope and can be used for all DB operations.\n /\n handleEvent(\n executionContext: unknown, // ExecutionContext<any> — typed as unknown to avoid circular dependency\n parsedEvent: StandardHook_ParsedEvent\n ): Promise<void>;\n}\n\n// ===============================================================\n// Hook Scope Resolver Strategy (Escape Hatch)\n// ===============================================================\n\n/\n Optional override for scope resolution when the declarative\n * Hook_EndpointScopeBinding config is insufficient.\n * \n * Register with WebhookHandlerBackendService.registerCustomScopeResolver()\n * to override the generic declarative resolver for a specific endpoint.\n * \n * Use cases:\n * - Different event types within the same endpoint have scope IDs at different payload paths\n * - Complex multi-step scope resolution logic\n * - Provider-specific edge cases\n /\nexport interface Hook_ScopeResolverStrategy {\n /* Provider reference this resolver handles /\n readonly providerRef: string;\n /* Endpoint key this resolver handles /\n readonly endpointKey: string;\n\n /* Resolve the engine scope from a parsed event /\n resolveScope(parsedEvent: StandardHook_ParsedEvent): Promise<StandardHook_ResolvedScope>;\n\n /* Whether scope resolution is required for this event type (affects error handling) */\n isScopeRequired(eventType: string): boolean;\n}\n"]}