@ekanos/integration-schema 0.1.0

package/dist/integration-definition.js

@@ -0,0 +1,661 @@
+/**
+ * The canonical integration-definition contract: ONE zod schema and ONE set
+ * of inferred/hand-written types (F9). `@ekanos/sdk`'s `defineIntegration()`
+ * validates against this schema at authoring time; `@kit/integrations-core`'s
+ * `registerPartnerIntegration()` re-validates against the SAME schema at the
+ * host trust boundary (F3). Both packages depend on this one; it depends on
+ * neither, so there is no cycle and no hand-written structural twin.
+ *
+ * Dependency-pure (zod only): partner component refs are checked
+ * structurally via `ComponentReference`, so no React dependency leaks in.
+ */
+import { z } from 'zod';
+import { isComponentReference } from './component-reference.js';
+import { WorkspaceTargetListSchema, } from './workspace-target.js';
+const jsonValueSchema = z.lazy(() => z.union([
+    z.string(),
+    // `.finite()` rejects Infinity/-Infinity AND NaN (Number.isFinite) — all
+    // of which JSON.stringify silently turns to `null`, so they are not
+    // JSON-compatible values (F4).
+    z.number().finite(),
+    z.boolean(),
+    z.null(),
+    z.array(jsonValueSchema),
+    z.record(jsonValueSchema),
+]));
+// ---- Leaf validators -------------------------------------------------------
+function componentRefSchema(what) {
+    return z.custom(isComponentReference, {
+        message: `${what} must be a React component reference (a function component, or a memo/forwardRef/lazy wrapper) — pass the component itself, not an element or a module path.`,
+    });
+}
+const zodSchemaRef = z.custom((value) => typeof (value === null || value === void 0 ? void 0 : value.safeParse) === 'function', {
+    message: 'Every storage key must declare a zod schema (e.g. z.object({ … })) — ctx.storage validates reads and writes against it (capability-context ruling 1).',
+});
+const nonEmpty = (what) => z.string().min(1, { message: `${what} must be a non-empty string.` });
+const slugSchema = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, {
+    message: 'slug must be kebab-case ([a-z0-9] segments separated by single hyphens), e.g. "acme-crm" — it becomes the product slug, route segment, and MCP namespace.',
+});
+const widgetIdSchema = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, {
+    message: 'Widget ids are kebab-case and globally unique, e.g. "acme-crm-pipeline" — prefix with the integration slug to stay collision-free.',
+});
+const storageKeySchema = z.string().regex(/^[a-z0-9_-]+(?:\/[a-z0-9_-]+)?$/, {
+    message: 'Storage keys are "<dataType>" or "<dataType>/<subtype>" in lowercase [a-z0-9_-] — they map onto the account/user product-data columns (capability-context ruling 6).',
+});
+const toolNameSchema = z.string().regex(/^[a-z][a-z0-9_]*$/, {
+    message: 'Tool names are lowercase snake_case starting with a letter, e.g. "list_invoices" — the model calls them by this exact string.',
+});
+const webhookIdSchema = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, {
+    message: 'Webhook ids are kebab-case, e.g. "payment-updated" — the host ingress route addresses the handler by this exact string.',
+});
+const scheduleIdSchema = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, {
+    message: 'Schedule ids are kebab-case, e.g. "daily-reconcile" — the host scheduler addresses the handler by this exact string.',
+});
+// Origin-only egress entries (ruling 3): absolute https origins, optional
+// `*.` subdomain wildcard, no path/query/hash/credentials/http. Kept as a
+// pure regex here so this package depends on nothing; the SDK's shared
+// `parseEgressEntry`/`isEgressAllowed` matcher enforces the identical shape
+// at runtime.
+const egressEntrySchema = z.string().superRefine((entry, ctx) => {
+    var _a;
+    const match = /^https:\/\/(\*\.)?([a-z0-9.-]+)(?::(\d+))?$/i.exec(entry);
+    if (!match) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `Egress entry "${entry}" is invalid. Entries are https origins only — ` +
+                `"https://api.example.com" (exact) or "https://*.example.com" ` +
+                `(subdomain wildcard): scheme + host + optional port, no path, query, ` +
+                `hash, credentials, or http. Fix it in the integration's egress list.`,
+        });
+        return;
+    }
+    const host = (_a = match[2]) !== null && _a !== void 0 ? _a : '';
+    if (host.includes('*') || host.startsWith('.') || host.endsWith('.')) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `Egress entry "${entry}" has a malformed host — wildcards are only supported as a single leading "*." (e.g. "https://*.example.com").`,
+        });
+    }
+});
+// ---- Sub-object schemas ----------------------------------------------------
+const capabilitySchema = z
+    .object({
+    label: nonEmpty('capabilities[].label'),
+    description: nonEmpty('capabilities[].description'),
+    icon: componentRefSchema('capabilities[].icon').optional(),
+})
+    .strict();
+const permissionSchema = z
+    .object({
+    label: nonEmpty('permissions[].label'),
+    detail: nonEmpty('permissions[].detail'),
+    type: z.enum(['read', 'write']),
+})
+    .strict();
+const gridUnitSchema = z
+    .object({
+    cols: z.number().int().positive(),
+    rows: z.number().int().positive(),
+})
+    .strict();
+const layoutBoxSchema = z
+    .object({
+    x: z.number(),
+    y: z.number(),
+    w: z.number(),
+    h: z.number(),
+    maxHeight: z.number().optional(),
+})
+    .strict();
+/**
+ * F7: authorable widget fields ONLY. Host-resolved fields (`productId`,
+ * `widgetConfigId`, `workspaceId`, `collapsed`, `isPinned`, `health`,
+ * `integrationMetadata`) are absent by design and rejected at runtime by
+ * `.strict()` — the type and the runtime agree. The host adapter maps this
+ * into the full `WidgetConfig`.
+ */
+const widgetSchema = z
+    .object({
+    id: widgetIdSchema,
+    name: nonEmpty('widgets[].name'),
+    component: componentRefSchema('widgets[].component'),
+    widgetState: z.enum(['active', 'inactive', 'disabled']),
+    gridSize: z.union([gridUnitSchema, z.array(gridUnitSchema)]).optional(),
+    gridPosition: z
+        .object({ col: z.number(), row: z.number() })
+        .strict()
+        .optional(),
+    layouts: z
+        .object({
+        lg: layoutBoxSchema.optional(),
+        md: layoutBoxSchema.optional(),
+        sm: layoutBoxSchema.optional(),
+    })
+        .strict()
+        .optional(),
+    category: z
+        .object({
+        id: z.string(),
+        name: z.string(),
+        slug: z.string(),
+        icon: z.string().nullable(),
+    })
+        .strict()
+        .optional(),
+    isCollapsible: z.boolean().optional(),
+    isPinnable: z.boolean().optional(),
+    aiFooterEnabled: z.boolean().optional(),
+})
+    .strict();
+const toolParametersSchema = z
+    .object({
+    type: z.literal('object'),
+    properties: z.record(jsonValueSchema).optional(),
+    required: z.array(z.string()).optional(),
+    additionalProperties: z.boolean().optional(),
+})
+    .strict();
+const toolRunSchema = z.custom((value) => typeof value === 'function', {
+    message: 'tools[].run must be a function (ctx, args) => Promise<result> — it receives the host-scoped IntegrationContext, never a raw client.',
+});
+const toolSchema = z
+    .object({
+    name: toolNameSchema,
+    description: nonEmpty('tools[].description'),
+    parameters: toolParametersSchema.optional(),
+    run: toolRunSchema,
+    outputExample: z.record(jsonValueSchema).optional(),
+})
+    .strict();
+// ---- Event surfaces (webhooks, schedules, OAuth) ---------------------------
+//
+// Declared exactly like MCP tools: metadata parsed strictly, handlers checked
+// structurally as functions (`z.custom`) and carried through the parse
+// untouched. The declarations are the CONTRACT; every transport — the local
+// harness today, the host's public ingress/scheduler/hosted-callback later —
+// binds to these same fields, so a partner package never changes when the
+// real transports arrive.
+function handlerSchema(what, shape) {
+    return z.custom((value) => typeof value === 'function', {
+        message: `${what} must be a function ${shape} — it receives the host-scoped IntegrationContext, never a raw request or client.`,
+    });
+}
+const payloadSchemaRef = z.custom((value) => typeof (value === null || value === void 0 ? void 0 : value.safeParse) === 'function', {
+    message: 'webhooks[].payloadSchema must be a zod schema (e.g. z.object({ … })) — the transport validates every delivery against it before the handler runs.',
+});
+/**
+ * How the TRANSPORT verifies a delivery. Verification is never the partner's
+ * job: the declaration names the signature header and the secret that signs
+ * it; the host ingress enforces it (the local harness logs it as skipped).
+ * `'none'` is an explicit statement that the source is unsigned.
+ */
+const webhookSignatureSchema = z.union([
+    z.literal('none'),
+    z
+        .object({
+        header: nonEmpty('webhooks[].signature.header'),
+        secretName: nonEmpty('webhooks[].signature.secretName'),
+    })
+        .strict(),
+]);
+const webhookSchema = z
+    .object({
+    id: webhookIdSchema,
+    description: nonEmpty('webhooks[].description'),
+    payloadSchema: payloadSchemaRef,
+    signature: webhookSignatureSchema,
+    examplePayload: z.record(jsonValueSchema).optional(),
+    handler: handlerSchema('webhooks[].handler', '(ctx, event) => Promise<WebhookResult>'),
+})
+    .strict();
+const scheduleSchema = z
+    .object({
+    id: scheduleIdSchema,
+    description: nonEmpty('schedules[].description'),
+    // Presence only here — the dependency-pure schema package stays zod-only,
+    // so the real 5-field cron syntax check lives in the SDK layer
+    // (`defineIntegration()`), the same way it layers cross-field rules today.
+    cron: nonEmpty('schedules[].cron'),
+    handler: handlerSchema('schedules[].handler', '(ctx, invocation) => Promise<ScheduleResult>'),
+})
+    .strict();
+const httpsUrlSchema = (what) => z.string().superRefine((value, ctx) => {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch (_a) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `${what} must be an absolute URL, e.g. "https://provider.example/oauth/authorize".`,
+        });
+        return;
+    }
+    if (parsed.protocol !== 'https:') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `${what} must use https — OAuth endpoints are never plain http.`,
+        });
+    }
+    if (parsed.username !== '' || parsed.password !== '') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `${what} must not embed credentials.`,
+        });
+    }
+});
+const oauthSchema = z
+    .object({
+    provider: z
+        .object({
+        authorizationUrl: httpsUrlSchema('oauth.provider.authorizationUrl'),
+        tokenUrl: httpsUrlSchema('oauth.provider.tokenUrl'),
+        scopes: z.array(nonEmpty('oauth.provider.scopes[]')),
+        pkce: z.boolean().optional(),
+    })
+        .strict(),
+    credentials: z
+        .object({
+        clientIdSecretName: nonEmpty('oauth.credentials.clientIdSecretName'),
+        clientSecretSecretName: nonEmpty('oauth.credentials.clientSecretSecretName'),
+    })
+        .strict(),
+    onTokens: handlerSchema('oauth.onTokens', '(ctx, tokens) => Promise<void>'),
+})
+    .strict();
+const toolClassificationProposalSchema = z
+    .object({
+    effect: z.enum(['read', 'write']).optional(),
+    sensitivity: z.enum(['public', 'internal', 'pii', 'financial']).optional(),
+})
+    .strict();
+const proposalsSchema = z
+    .object({
+    credentialModel: z.enum(['account', 'user', 'source']).optional(),
+    tools: z.record(toolClassificationProposalSchema).optional(),
+})
+    .strict();
+/**
+ * A storage key's EXPLICIT declaration: the zod schema plus its exposure
+ * flags. `clientReadable` is the only way a declared key becomes readable by
+ * the browser through the generic storage route — and it defaults to false,
+ * so the bare-schema form stays server-only exactly as it always was.
+ * `.strict()` keeps an unrecognized flag (a typo like `clientReadible`) an
+ * error rather than a silently-ignored key whose author believes it is
+ * exposed — or, worse, believes it is not.
+ */
+const storageKeyDeclarationSchema = z
+    .object({
+    schema: zodSchemaRef,
+    clientReadable: z.boolean().optional(),
+})
+    .strict();
+/** Duck-typed so a partner's own bundled zod copy still reads as a schema. */
+function isZodSchemaLike(value) {
+    return (typeof (value === null || value === void 0 ? void 0 : value.safeParse) === 'function');
+}
+/**
+ * Either declaration form, hand-routed rather than expressed as `z.union` so
+ * the failure message stays specific. A union reports a bare "Invalid input"
+ * for every wrong shape, which would lose both the "declare a zod schema"
+ * guidance AND the strict-descriptor typo report — the two errors an author
+ * is actually going to hit.
+ */
+const storageKeyDeclarationRef = z
+    .custom(() => true)
+    .superRefine((value, ctx) => {
+    if (isZodSchemaLike(value))
+        return;
+    const looksLikeDescriptor = value !== null && typeof value === 'object' && !Array.isArray(value);
+    // Neither form: name both, since the descriptor is the less obvious one.
+    if (!looksLikeDescriptor ||
+        !isZodSchemaLike(value.schema)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Every storage key must declare either a zod schema (e.g. z.object({ … })) or a { schema, clientReadable } descriptor — ctx.storage validates reads and writes against the schema (capability-context ruling 1), and clientReadable (default false) is what opts the key in to the browser-readable storage route.',
+        });
+        return;
+    }
+    // A real descriptor with a real schema — report its own issues verbatim
+    // (an unrecognized flag, a non-boolean clientReadable) rather than the
+    // generic message, which would send the author looking in the wrong place.
+    const result = storageKeyDeclarationSchema.safeParse(value);
+    if (result.success)
+        return;
+    for (const issue of result.error.issues) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: issue.path,
+            message: issue.message,
+        });
+    }
+});
+const storageScopeSchema = z.record(storageKeySchema, storageKeyDeclarationRef);
+const componentsSchema = z
+    .object({
+    activationForm: componentRefSchema('components.activationForm').optional(),
+    marketplaceTile: componentRefSchema('components.marketplaceTile').optional(),
+    widgets: z.array(widgetSchema).optional(),
+})
+    .strict();
+/**
+ * THE canonical schema. Strict everywhere: an unrecognized key is an error,
+ * which is what keeps host-assigned fields (productId, kind, trust tier,
+ * credentialModel, per-tool effect/sensitivity, host-resolved widget fields)
+ * structurally un-settable at runtime, not merely absent from the type.
+ */
+export const IntegrationDefinitionSchema = z
+    .object({
+    slug: slugSchema,
+    name: nonEmpty('name'),
+    description: nonEmpty('description'),
+    version: z
+        .string()
+        .regex(/^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/, {
+        message: 'version must be semver ("1.0.0", optionally with a prerelease/build suffix) — promotion diffs definitions by it.',
+    }),
+    capabilities: z.array(capabilitySchema).optional(),
+    permissions: z.array(permissionSchema).optional(),
+    components: componentsSchema.optional(),
+    workspaceTargets: WorkspaceTargetListSchema.optional(),
+    tools: z.array(toolSchema).optional(),
+    storage: z
+        .object({
+        account: storageScopeSchema.optional(),
+        user: storageScopeSchema.optional(),
+    })
+        .strict()
+        .optional(),
+    egress: z.array(egressEntrySchema).optional(),
+    webhooks: z.array(webhookSchema).optional(),
+    schedules: z.array(scheduleSchema).optional(),
+    oauth: oauthSchema.optional(),
+    proposes: proposalsSchema.optional(),
+})
+    .strict()
+    .superRefine((definition, ctx) => {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const webhookIds = ((_a = definition.webhooks) !== null && _a !== void 0 ? _a : []).map((w) => w.id);
+    for (const id of findDuplicates(webhookIds)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['webhooks'],
+            message: `Webhook id "${id}" is declared more than once — give every webhook a unique id.`,
+        });
+    }
+    const scheduleIds = ((_b = definition.schedules) !== null && _b !== void 0 ? _b : []).map((s) => s.id);
+    for (const id of findDuplicates(scheduleIds)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['schedules'],
+            message: `Schedule id "${id}" is declared more than once — give every schedule a unique id.`,
+        });
+    }
+    const widgetIds = ((_d = (_c = definition.components) === null || _c === void 0 ? void 0 : _c.widgets) !== null && _d !== void 0 ? _d : []).map((w) => w.id);
+    for (const id of findDuplicates(widgetIds)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['components', 'widgets'],
+            message: `Widget id "${id}" is declared more than once — give every widget a unique id.`,
+        });
+    }
+    const toolNames = ((_e = definition.tools) !== null && _e !== void 0 ? _e : []).map((tool) => tool.name);
+    for (const name of findDuplicates(toolNames)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['tools'],
+            message: `Tool "${name}" is declared more than once — give every tool a unique name.`,
+        });
+    }
+    const declaredTools = new Set(toolNames);
+    for (const proposedName of Object.keys((_g = (_f = definition.proposes) === null || _f === void 0 ? void 0 : _f.tools) !== null && _g !== void 0 ? _g : {})) {
+        if (!declaredTools.has(proposedName)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['proposes', 'tools', proposedName],
+                message: `proposes.tools["${proposedName}"] does not match any declared tool — proposals are keyed by the exact tool name in \`tools\`.`,
+            });
+        }
+    }
+});
+// ---- Shared helpers --------------------------------------------------------
+function findDuplicates(values) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const value of values) {
+        if (seen.has(value))
+            duplicates.add(value);
+        seen.add(value);
+    }
+    return [...duplicates];
+}
+function formatIssues(issues) {
+    return issues
+        .map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join('.') : '(root)';
+        return `  - ${path}: ${issue.message}`;
+    })
+        .join('\n');
+}
+const HOST_ASSIGNED_REMINDER = 'Host-assigned fields are never partner-authorable: productId, kind, trust ' +
+    'tier, and machine exposure (credentialModel) do not exist on ' +
+    'IntegrationDefinition, per-tool effect/sensitivity belong in the ' +
+    '`proposes` block, and host-resolved widget fields (productId, ' +
+    'widgetConfigId, workspaceId, collapsed, isPinned, health, ' +
+    'integrationMetadata) are populated by the platform at runtime — remove ' +
+    'them from the definition.';
+/**
+ * A zod schema (storage leaf) — detected via `instanceof` so we NEVER read a
+ * property (like `.safeParse`) that could be a malicious getter (F4). A React
+ * exotic (`memo`/`forwardRef`) is an object tagged with `$$typeof`; the `in`
+ * check uses [[HasProperty]], which does not invoke a getter either.
+ */
+function isDeclarationLeaf(value) {
+    return value instanceof z.ZodType || '$$typeof' in value;
+}
+/**
+ * F4: reject accessor/proxy/class-instance/cyclic declaration containers
+ * before parsing. An object with getters (or a proxy) can return validated
+ * values during parse and different values later; a non-plain prototype can
+ * smuggle mutable state past `z.object()`; a cycle would recurse into zod
+ * rather than fail cleanly. We walk every CONTAINER (plain object / array),
+ * and stop at legitimate leaves: functions (component refs, `run`) and zod
+ * schemas (storage). Leaf detection happens BEFORE any own-property read, so
+ * a `safeParse` getter cannot execute. Proxy detection is best-effort — the
+ * re-parse at the host boundary (which materializes fresh values via zod) is
+ * the real guard.
+ *
+ * Cycle detection tracks the ANCESTOR chain only (add on enter, remove on
+ * exit): a genuine back-edge is a cycle, but the same object referenced from
+ * two sibling branches (a DAG — e.g. a shallow-cloned widget sharing a
+ * `layouts` object) is not, and must not be rejected.
+ */
+export function assertPlainDeclaration(value, path = '(root)', ancestors = new WeakSet()) {
+    if (value === null || typeof value !== 'object')
+        return;
+    if (typeof value === 'function')
+        return;
+    // Leaf detection first — instanceof / HasProperty never invoke a getter.
+    if (isDeclarationLeaf(value))
+        return;
+    if (ancestors.has(value)) {
+        throw new Error(`Integration definition contains a cycle at ${path}. ` +
+            `Declarations must be finite plain data — remove the self-reference. ${HOST_ASSIGNED_REMINDER}`);
+    }
+    const proto = Object.getPrototypeOf(value);
+    const isArray = Array.isArray(value);
+    if (!isArray && proto !== Object.prototype && proto !== null) {
+        throw new Error(`Integration definition value at ${path} is a class/exotic instance, not a plain object. ` +
+            `Declaration containers must be plain object/array literals so their values cannot mutate after validation. ${HOST_ASSIGNED_REMINDER}`);
+    }
+    ancestors.add(value);
+    for (const key of Object.keys(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor && (descriptor.get || descriptor.set)) {
+            throw new Error(`Integration definition property at ${path}.${key} is a getter/setter, not a data property. ` +
+                `Declaration values must be plain data — a getter can return a different value after validation. ${HOST_ASSIGNED_REMINDER}`);
+        }
+        assertPlainDeclaration(value[key], `${path}.${key}`, ancestors);
+    }
+    ancestors.delete(value);
+}
+const frozen = new WeakSet();
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Cycle-aware deep freeze (F4). Freezes plain objects and arrays; leaves zod
+ * schemas (freezing breaks their internal caches) and functions alone.
+ */
+export function deepFreezeDefinition(value) {
+    if (value === null || typeof value !== 'object')
+        return;
+    if (frozen.has(value))
+        return;
+    if (Array.isArray(value)) {
+        frozen.add(value);
+        Object.freeze(value);
+        for (const item of value)
+            deepFreezeDefinition(item);
+        return;
+    }
+    if (isPlainObject(value)) {
+        frozen.add(value);
+        Object.freeze(value);
+        for (const item of Object.values(value))
+            deepFreezeDefinition(item);
+    }
+}
+/**
+ * The single validation entry point used by BOTH `defineIntegration()` (SDK,
+ * authoring time) and `registerPartnerIntegration()` (core, host trust
+ * boundary — F3). Rejects non-plain containers, then parses against the
+ * canonical schema, and returns the SANITIZED `result.data` (fresh, plain,
+ * strict-stripped — never the caller's original object). Throws an Error
+ * whose message is a remediation instruction.
+ */
+export function parseIntegrationDefinition(input) {
+    assertPlainDeclaration(input);
+    const result = IntegrationDefinitionSchema.safeParse(input);
+    if (!result.success) {
+        const slug = typeof (input === null || input === void 0 ? void 0 : input.slug) === 'string'
+            ? ` for "${input.slug}"`
+            : '';
+        throw new Error(`Invalid integration definition${slug}:\n` +
+            `${formatIssues(result.error.issues)}\n` +
+            HOST_ASSIGNED_REMINDER);
+    }
+    // F4: freeze inside the canonical parser so BOTH defineIntegration() and
+    // registerPartnerIntegration() register immutable output — the host boundary
+    // no longer hands back mutable arrays. Function/zod leaves stay executable
+    // by design (the T1 model), so this is structural immutability, not
+    // behavioral.
+    deepFreezeDefinition(result.data);
+    // The schema's inferred output matches IntegrationDefinition in every
+    // non-generic field; the storage/tool generics default to the permissive
+    // base, which is exactly right for the loose registration boundary.
+    return result.data;
+}
+// ---- Cross-definition collision detection (F5) -----------------------------
+/**
+ * THE canonical effective MCP tool name — the single source of truth for how
+ * discovery keys a tool. Tool discovery namespaces each raw tool name with the
+ * integration slug (`slug.replace(/-/g,'_')`), skipping the prefix when the
+ * name already carries it. Two collision-free RAW pairs can therefore collapse
+ * to the same EFFECTIVE name (`{slug:"foo",tool:"bar_baz"}` and
+ * `{slug:"foo-bar",tool:"baz"}` both become `foo_bar_baz`), so collision
+ * checking MUST compare effective names, and runtime discovery MUST throw on a
+ * duplicate assignment. Both call this one helper
+ * (`packages/agents/src/tools/tool-discovery.ts`).
+ */
+export function getDiscoveredToolName(slug, rawName) {
+    const slugPrefix = slug.replace(/-/g, '_');
+    return rawName.startsWith(slugPrefix) ? rawName : `${slugPrefix}_${rawName}`;
+}
+/**
+ * Detects cross-definition collisions (duplicate slugs, widget ids, tool
+ * names across the partner set) AND collisions against the first-party
+ * inventory, throwing one error listing EVERY collision.
+ *
+ * This is the build-time gate the host registry deliberately lacks:
+ * `integrationRegistry.register()` keys by slug via `Map.set` and silently
+ * OVERWRITES, and duplicate widget/tool ids resolve last- or
+ * first-registration-wins by import order.
+ */
+export function validateIntegrationDefinitions(definitions, firstParty = {}) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    const slugCounts = new Map();
+    const widgetOwners = new Map();
+    const toolOwners = new Map();
+    for (const definition of definitions) {
+        slugCounts.set(definition.slug, ((_a = slugCounts.get(definition.slug)) !== null && _a !== void 0 ? _a : 0) + 1);
+        for (const widget of (_c = (_b = definition.components) === null || _b === void 0 ? void 0 : _b.widgets) !== null && _c !== void 0 ? _c : []) {
+            widgetOwners.set(widget.id, [
+                ...((_d = widgetOwners.get(widget.id)) !== null && _d !== void 0 ? _d : []),
+                definition.slug,
+            ]);
+        }
+        for (const tool of (_e = definition.tools) !== null && _e !== void 0 ? _e : []) {
+            // EFFECTIVE (discovery) name, not the raw name — two collision-free raw
+            // names can collapse to the same effective key.
+            const effective = getDiscoveredToolName(definition.slug, tool.name);
+            toolOwners.set(effective, [
+                ...((_f = toolOwners.get(effective)) !== null && _f !== void 0 ? _f : []),
+                definition.slug,
+            ]);
+        }
+    }
+    const collisions = [];
+    for (const [slug, count] of slugCounts) {
+        if (count > 1) {
+            collisions.push(`slug "${slug}" is declared by ${count} partner definitions — slugs are the registry key and must be globally unique.`);
+        }
+    }
+    for (const [id, owners] of widgetOwners) {
+        if (owners.length > 1) {
+            collisions.push(`widget id "${id}" is declared by [${owners.join(', ')}] — widget ids are global (widget_config rows key on them); prefix yours with the integration slug.`);
+        }
+    }
+    for (const [name, owners] of toolOwners) {
+        if (owners.length > 1) {
+            collisions.push(`effective tool name "${name}" is declared by [${owners.join(', ')}] — discovery namespaces tool names by slug, so these collapse to one flat key and overwrite each other. Rename so the slug-prefixed names differ.`);
+        }
+    }
+    const reservedSlugs = new Set((_g = firstParty.slugs) !== null && _g !== void 0 ? _g : []);
+    const reservedWidgets = new Set((_h = firstParty.widgetIds) !== null && _h !== void 0 ? _h : []);
+    const reservedTools = new Set((_j = firstParty.toolNames) !== null && _j !== void 0 ? _j : []);
+    for (const [slug, owners] of groupOwners(definitions, (d) => [d.slug])) {
+        if (reservedSlugs.has(slug)) {
+            collisions.push(`slug "${slug}" (declared by [${owners.join(', ')}]) collides with a first-party integration — pick a slug no built-in product uses.`);
+        }
+    }
+    for (const [id, owners] of widgetOwners) {
+        if (reservedWidgets.has(id)) {
+            collisions.push(`widget id "${id}" (declared by [${owners.join(', ')}]) collides with a first-party widget — the dashboard resolves widgets by id, so this would hijack it. Prefix with the integration slug.`);
+        }
+    }
+    for (const [name, owners] of toolOwners) {
+        if (reservedTools.has(name)) {
+            collisions.push(`effective tool name "${name}" (declared by [${owners.join(', ')}]) collides with a first-party tool — the flat, slug-namespaced tool registry would overwrite one with the other. Rename it.`);
+        }
+    }
+    if (collisions.length > 0) {
+        throw new Error(`Integration definitions collide (${collisions.length} collision${collisions.length === 1 ? '' : 's'}):\n` +
+            collisions.map((line) => `  - ${line}`).join('\n') +
+            '\nRename until every slug, widget id, and tool name is unique — the host registry would otherwise silently overwrite or drop a registration.');
+    }
+}
+function groupOwners(definitions, keysOf) {
+    var _a;
+    const owners = new Map();
+    for (const definition of definitions) {
+        for (const key of keysOf(definition)) {
+            owners.set(key, [...((_a = owners.get(key)) !== null && _a !== void 0 ? _a : []), definition.slug]);
+        }
+    }
+    return owners;
+}
+//# sourceMappingURL=integration-definition.js.map