@ekanos/integration-schema 0.1.1 → 0.1.3

package/README.md

@@ -10,19 +10,25 @@ a dependency cycle and there is no hand-written structural twin to drift.
 
 ## Why it exists
 
-Adversarial review (GPT-5.6, 2026-08-27) found three problems a shared schema
-resolves at once:
+A security review found three problems a shared schema resolves at once:
 
-- **F3** — the host must re-parse partner exports at the trust boundary, not
+- The host must re-parse partner exports at the trust boundary rather than
   trust a `.d.ts`. `registerPartnerIntegration()` calls
-  `parseIntegrationDefinition()` from here.
-- **F9** — hand-written structural twins in `@kit/integrations-core` could not
-  catch security-relevant drift. There are no twins now: one type, imported by
-  both sides.
-- **F10** — the SDK validated a weaker workspace contract than the host. The
+  `parseIntegrationDefinition()` from here, so a definition is validated twice
+  against the same rules: once when you author it, once when the host accepts
+  it.
+- Hand-written structural twins on the host side could not catch
+  security-relevant drift. There are no twins now: one type, imported by both
+  sides.
+- The SDK used to validate a weaker workspace contract than the host. The
   workspace-target schema lives here; the host injects icon-name validity via
   `createWorkspaceTargetListSchema({ isValidIcon })`.
 
+**Authoring an integration? Read the `@ekanos/sdk` README instead.** It is the
+partner guide, and it documents every field this schema validates with a worked
+example. This package is the contract underneath it: you install it only if you
+need the schema or the types without the SDK.
+
 ## What's here
 
 - `IntegrationDefinitionSchema` — the strict canonical zod schema.
@@ -40,9 +46,10 @@ Dependency-pure by construction: `zod` only. No `@kit/*`, no React, no
 
 ## Publishing
 
-This package is publishable (`version` set, not `private`) and is a **runtime
-dependency of `@ekanos/sdk`**, so it must be published **before** the SDK — a
-fresh `npm install @ekanos/sdk` resolves `@ekanos/integration-schema` from the
-registry. The compiled ESM in `dist/` uses explicit `.js` relative specifiers
+This package is a **runtime dependency of `@ekanos/sdk`**, so it must be
+published **before** the SDK — a fresh `npm install @ekanos/sdk` resolves
+`@ekanos/integration-schema` from the registry. (It carries `private: true`
+between releases as a deliberate publish latch; a release commit lifts it on
+every publishable package at once.) The compiled ESM in `dist/` uses explicit `.js` relative specifiers
 so a real Node import resolves without a bundler; the SDK's `pack:test`
 exercises that path end to end.

package/dist/capability-context.d.ts

@@ -7,7 +7,7 @@
  * zod-type-only, erased at compile time. The value half of the contract —
  * error classes, the egress matcher, the storage validators — lives in
  * `@ekanos/sdk/context`; the in-memory mock in `@ekanos/sdk/testing`.
- * Spec: docs/devex/capability-context-proposal.md (all six §7 rulings).
+ * The authoring guide for everything below is the `@ekanos/sdk` README.
  */
 import type { z } from 'zod';
 /**

package/dist/capability-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"capability-context.js","sourceRoot":"","sources":["../src/capability-context.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * The capability context — the one object partner code receives.\n *\n * Canonical home (moved here from `@ekanos/sdk`'s `context/types.ts` so the\n * definition schema below can reference `IntegrationContext` without a\n * package cycle; `@ekanos/sdk` re-exports every type from here). Pure types,\n * zod-type-only, erased at compile time. The value half of the contract —\n * error classes, the egress matcher, the storage validators — lives in\n * `@ekanos/sdk/context`; the in-memory mock in `@ekanos/sdk/testing`.\n * Spec: docs/devex/capability-context-proposal.md (all six §7 rulings).\n */\nimport type { z } from 'zod';\n\n/**\n * Who is executing. A closed union: a machine context without a grant is\n * unrepresentable rather than merely checked (proposal §2).\n */\nexport type IntegrationActor =\n  | { readonly kind: 'user'; readonly userId: string }\n  | {\n      readonly kind: 'machine';\n      readonly tokenId: string;\n      readonly createdBy: string | null;\n    };\n\n/**\n * One storage key's declaration in EXPLICIT form: the zod schema plus the\n * exposure flags that decide which host surfaces may serve the key.\n *\n * Exposure is opt-in and fails closed. A declaration's keys are server-side\n * by construction — partner code reaches them only through `ctx.storage`,\n * which runs behind the capability layer. The generic browser-readable\n * storage route (`GET /api/integrations/[slug]/storage`) would otherwise\n * turn EVERY declared key into a browser-readable one, including keys a\n * partner reasonably treated as server-only: sync cursors, cached upstream\n * responses, internal bookkeeping. So the route serves a key only when its\n * declaration opts in with `clientReadable: true`.\n */\nexport interface StorageKeyDeclaration<S extends z.ZodType = z.ZodType> {\n  readonly schema: S;\n  /**\n   * Opt in to the generic browser-readable storage route. **Defaults to\n   * `false`** — an omitted flag, and the bare-schema declaration form, both\n   * mean server-only. Set it only for values the browser legitimately needs\n   * and that are safe for any active member of the account to read (widget\n   * settings, display preferences). Never for cursors, cached upstream\n   * payloads, or anything a `secret` would be a better home for.\n   */\n  readonly clientReadable?: boolean;\n}\n\n/**\n * How a single storage key may be declared: a bare zod schema (the original\n * form — always server-only), or a `StorageKeyDeclaration` descriptor that\n * carries exposure flags alongside the schema. Both forms validate reads and\n * writes identically; only the descriptor can widen exposure.\n */\nexport type StorageKeyDeclarationInput<S extends z.ZodType = z.ZodType> =\n  | S\n  | StorageKeyDeclaration<S>;\n\n/**\n * Storage schemas for one scope: key → zod schema, or key → declaration\n * descriptor (ruling 1). Keys are strict — a key with no declared schema\n * cannot be read, written, or deleted; the attempt is a type error where the\n * schema map is statically known, and always a runtime\n * `StorageValidationError`.\n */\nexport type StorageSchemaMap = Record<string, StorageKeyDeclarationInput>;\n\n/**\n * Resolves the zod schema out of either declaration form, so `ScopedStore`\n * stays schema-typed whichever form the author chose.\n */\nexport type StorageKeySchema<D> = [D] extends [z.ZodType]\n  ? D\n  : D extends StorageKeyDeclaration<infer S>\n    ? S\n    : D extends z.ZodType\n      ? D\n      : never;\n\n/**\n * The storage declaration `defineIntegration({ storage })` consumes and\n * `createMockContext({ storageSchemas })` enforces (ruling 1). A scope left\n * undeclared has no usable keys.\n */\nexport interface StorageSchemas {\n  account?: StorageSchemaMap;\n  user?: StorageSchemaMap;\n}\n\n/**\n * Resolves the schema map for one scope of a declaration. A scope the\n * integration did not declare resolves to an empty map (no key typechecks);\n * only the unparameterized default (`StorageSchemas` itself) stays\n * permissive, for signatures that cannot know the integration's schemas.\n */\nexport type StorageScopeSchemas<\n  Schemas extends StorageSchemas,\n  Scope extends keyof StorageSchemas,\n> = [Schemas[Scope]] extends [undefined]\n  ? Record<never, never>\n  : NonNullable<Schemas[Scope]>;\n\nexport interface StorageEntry<T> {\n  data: T;\n  externalId: string | null;\n  expiresAt: string | null;\n  updatedAt: string;\n}\n\nexport interface StorageWriteOptions {\n  externalId?: string;\n  /** ISO-8601 timestamp; an entry past it reads as `null`. */\n  expiresAt?: string;\n}\n\n/**\n * One scope of `ctx.storage`, bound to `{account, product}` (and `userId`\n * for the user scope) at construction — there is no id parameter to lie in.\n *\n * Schema-typed (ruling 1): `get` returns the declared schema's output type,\n * `set` validates before write, and a read whose stored data no longer\n * matches the schema throws `StorageValidationError` — schema evolution is\n * handled explicitly (versioned keys or `z.union`), never silently.\n * All methods are async (ruling 4).\n */\nexport interface ScopedStore<\n  Schemas extends StorageSchemaMap = StorageSchemaMap,\n> {\n  get<K extends keyof Schemas & string>(\n    key: K,\n  ): Promise<StorageEntry<z.output<StorageKeySchema<Schemas[K]>>> | null>;\n  set<K extends keyof Schemas & string>(\n    key: K,\n    data: z.input<StorageKeySchema<Schemas[K]>>,\n    options?: StorageWriteOptions,\n  ): Promise<void>;\n  delete<K extends keyof Schemas & string>(key: K): Promise<void>;\n}\n\nexport interface IntegrationStorage<\n  Schemas extends StorageSchemas = StorageSchemas,\n> {\n  /** account_product_data, bound to {accountId, productId}. */\n  readonly account: ScopedStore<StorageScopeSchemas<Schemas, 'account'>>;\n  /**\n   * user_product_data, bound to {userId, accountId, productId}.\n   * Throws for machine actors.\n   */\n  readonly user: ScopedStore<StorageScopeSchemas<Schemas, 'user'>>;\n}\n\n/**\n * Reads from the credential set the host resolved (account → source →\n * global tiers + hydrated activation secrets) before partner code ran.\n * All methods are async (ruling 4).\n */\nexport interface IntegrationSecrets {\n  /** A named field of the resolved credential set + hydrated activation secrets. */\n  get(name: string): Promise<string | null>;\n  /** All resolved secret names (values not included) — for capability probing. */\n  names(): Promise<string[]>;\n  /**\n   * Write back a rotated value (OAuth refresh). Tier-bound (ruling 2):\n   * writes go only to the account-tier store bound to {account, product} at\n   * construction. Source- and global-tier credentials (admin-issued) are\n   * structurally unreachable from this path; a write against a name that\n   * resolves only from those tiers throws `SecretAccessError`.\n   */\n  set(name: string, value: string): Promise<void>;\n}\n\n/**\n * Host-allowlisted egress (ruling 3): origin-only allowlist with explicit\n * `*.` subdomain wildcards, enforced against the RESOLVED URL's origin —\n * redirect targets included. A denied call throws `EgressDeniedError`\n * synchronously, before any network I/O.\n */\nexport type IntegrationFetch = (\n  input: string | URL,\n  init?: RequestInit,\n) => Promise<Response>;\n\n/**\n * Structured, pino-style. The host pre-binds `{integration, accountId,\n * actor}` so every partner log line is attributable.\n */\nexport interface IntegrationLogger {\n  debug(context: Record<string, unknown>, message: string): void;\n  info(context: Record<string, unknown>, message: string): void;\n  warn(context: Record<string, unknown>, message: string): void;\n  error(context: Record<string, unknown>, message: string): void;\n}\n\n/**\n * One host-constructed object whose every method is already scoped to\n * `{account, integration}` before partner code runs. Handed to MCP tool\n * `run()` and SDK server handlers alike (ruling 5: one type, one mock).\n */\nexport interface IntegrationContext<\n  Schemas extends StorageSchemas = StorageSchemas,\n> {\n  /** Identity facts — read-only, informational. Authorization already happened. */\n  readonly accountId: string;\n  readonly accountSlug: string | null;\n  readonly userId: string | null; // null for machine actors\n  readonly actor: IntegrationActor;\n  readonly sourceId: string | null;\n  readonly integration: { readonly slug: string; readonly productId: string };\n  readonly timezone: string | null;\n\n  readonly storage: IntegrationStorage<Schemas>;\n  readonly secrets: IntegrationSecrets;\n  readonly fetch: IntegrationFetch;\n  readonly logger: IntegrationLogger;\n}\n"]}
+{"version":3,"file":"capability-context.js","sourceRoot":"","sources":["../src/capability-context.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * The capability context — the one object partner code receives.\n *\n * Canonical home (moved here from `@ekanos/sdk`'s `context/types.ts` so the\n * definition schema below can reference `IntegrationContext` without a\n * package cycle; `@ekanos/sdk` re-exports every type from here). Pure types,\n * zod-type-only, erased at compile time. The value half of the contract —\n * error classes, the egress matcher, the storage validators — lives in\n * `@ekanos/sdk/context`; the in-memory mock in `@ekanos/sdk/testing`.\n * The authoring guide for everything below is the `@ekanos/sdk` README.\n */\nimport type { z } from 'zod';\n\n/**\n * Who is executing. A closed union: a machine context without a grant is\n * unrepresentable rather than merely checked (proposal §2).\n */\nexport type IntegrationActor =\n  | { readonly kind: 'user'; readonly userId: string }\n  | {\n      readonly kind: 'machine';\n      readonly tokenId: string;\n      readonly createdBy: string | null;\n    };\n\n/**\n * One storage key's declaration in EXPLICIT form: the zod schema plus the\n * exposure flags that decide which host surfaces may serve the key.\n *\n * Exposure is opt-in and fails closed. A declaration's keys are server-side\n * by construction — partner code reaches them only through `ctx.storage`,\n * which runs behind the capability layer. The generic browser-readable\n * storage route (`GET /api/integrations/[slug]/storage`) would otherwise\n * turn EVERY declared key into a browser-readable one, including keys a\n * partner reasonably treated as server-only: sync cursors, cached upstream\n * responses, internal bookkeeping. So the route serves a key only when its\n * declaration opts in with `clientReadable: true`.\n */\nexport interface StorageKeyDeclaration<S extends z.ZodType = z.ZodType> {\n  readonly schema: S;\n  /**\n   * Opt in to the generic browser-readable storage route. **Defaults to\n   * `false`** — an omitted flag, and the bare-schema declaration form, both\n   * mean server-only. Set it only for values the browser legitimately needs\n   * and that are safe for any active member of the account to read (widget\n   * settings, display preferences). Never for cursors, cached upstream\n   * payloads, or anything a `secret` would be a better home for.\n   */\n  readonly clientReadable?: boolean;\n}\n\n/**\n * How a single storage key may be declared: a bare zod schema (the original\n * form — always server-only), or a `StorageKeyDeclaration` descriptor that\n * carries exposure flags alongside the schema. Both forms validate reads and\n * writes identically; only the descriptor can widen exposure.\n */\nexport type StorageKeyDeclarationInput<S extends z.ZodType = z.ZodType> =\n  | S\n  | StorageKeyDeclaration<S>;\n\n/**\n * Storage schemas for one scope: key → zod schema, or key → declaration\n * descriptor (ruling 1). Keys are strict — a key with no declared schema\n * cannot be read, written, or deleted; the attempt is a type error where the\n * schema map is statically known, and always a runtime\n * `StorageValidationError`.\n */\nexport type StorageSchemaMap = Record<string, StorageKeyDeclarationInput>;\n\n/**\n * Resolves the zod schema out of either declaration form, so `ScopedStore`\n * stays schema-typed whichever form the author chose.\n */\nexport type StorageKeySchema<D> = [D] extends [z.ZodType]\n  ? D\n  : D extends StorageKeyDeclaration<infer S>\n    ? S\n    : D extends z.ZodType\n      ? D\n      : never;\n\n/**\n * The storage declaration `defineIntegration({ storage })` consumes and\n * `createMockContext({ storageSchemas })` enforces (ruling 1). A scope left\n * undeclared has no usable keys.\n */\nexport interface StorageSchemas {\n  account?: StorageSchemaMap;\n  user?: StorageSchemaMap;\n}\n\n/**\n * Resolves the schema map for one scope of a declaration. A scope the\n * integration did not declare resolves to an empty map (no key typechecks);\n * only the unparameterized default (`StorageSchemas` itself) stays\n * permissive, for signatures that cannot know the integration's schemas.\n */\nexport type StorageScopeSchemas<\n  Schemas extends StorageSchemas,\n  Scope extends keyof StorageSchemas,\n> = [Schemas[Scope]] extends [undefined]\n  ? Record<never, never>\n  : NonNullable<Schemas[Scope]>;\n\nexport interface StorageEntry<T> {\n  data: T;\n  externalId: string | null;\n  expiresAt: string | null;\n  updatedAt: string;\n}\n\nexport interface StorageWriteOptions {\n  externalId?: string;\n  /** ISO-8601 timestamp; an entry past it reads as `null`. */\n  expiresAt?: string;\n}\n\n/**\n * One scope of `ctx.storage`, bound to `{account, product}` (and `userId`\n * for the user scope) at construction — there is no id parameter to lie in.\n *\n * Schema-typed (ruling 1): `get` returns the declared schema's output type,\n * `set` validates before write, and a read whose stored data no longer\n * matches the schema throws `StorageValidationError` — schema evolution is\n * handled explicitly (versioned keys or `z.union`), never silently.\n * All methods are async (ruling 4).\n */\nexport interface ScopedStore<\n  Schemas extends StorageSchemaMap = StorageSchemaMap,\n> {\n  get<K extends keyof Schemas & string>(\n    key: K,\n  ): Promise<StorageEntry<z.output<StorageKeySchema<Schemas[K]>>> | null>;\n  set<K extends keyof Schemas & string>(\n    key: K,\n    data: z.input<StorageKeySchema<Schemas[K]>>,\n    options?: StorageWriteOptions,\n  ): Promise<void>;\n  delete<K extends keyof Schemas & string>(key: K): Promise<void>;\n}\n\nexport interface IntegrationStorage<\n  Schemas extends StorageSchemas = StorageSchemas,\n> {\n  /** account_product_data, bound to {accountId, productId}. */\n  readonly account: ScopedStore<StorageScopeSchemas<Schemas, 'account'>>;\n  /**\n   * user_product_data, bound to {userId, accountId, productId}.\n   * Throws for machine actors.\n   */\n  readonly user: ScopedStore<StorageScopeSchemas<Schemas, 'user'>>;\n}\n\n/**\n * Reads from the credential set the host resolved (account → source →\n * global tiers + hydrated activation secrets) before partner code ran.\n * All methods are async (ruling 4).\n */\nexport interface IntegrationSecrets {\n  /** A named field of the resolved credential set + hydrated activation secrets. */\n  get(name: string): Promise<string | null>;\n  /** All resolved secret names (values not included) — for capability probing. */\n  names(): Promise<string[]>;\n  /**\n   * Write back a rotated value (OAuth refresh). Tier-bound (ruling 2):\n   * writes go only to the account-tier store bound to {account, product} at\n   * construction. Source- and global-tier credentials (admin-issued) are\n   * structurally unreachable from this path; a write against a name that\n   * resolves only from those tiers throws `SecretAccessError`.\n   */\n  set(name: string, value: string): Promise<void>;\n}\n\n/**\n * Host-allowlisted egress (ruling 3): origin-only allowlist with explicit\n * `*.` subdomain wildcards, enforced against the RESOLVED URL's origin —\n * redirect targets included. A denied call throws `EgressDeniedError`\n * synchronously, before any network I/O.\n */\nexport type IntegrationFetch = (\n  input: string | URL,\n  init?: RequestInit,\n) => Promise<Response>;\n\n/**\n * Structured, pino-style. The host pre-binds `{integration, accountId,\n * actor}` so every partner log line is attributable.\n */\nexport interface IntegrationLogger {\n  debug(context: Record<string, unknown>, message: string): void;\n  info(context: Record<string, unknown>, message: string): void;\n  warn(context: Record<string, unknown>, message: string): void;\n  error(context: Record<string, unknown>, message: string): void;\n}\n\n/**\n * One host-constructed object whose every method is already scoped to\n * `{account, integration}` before partner code runs. Handed to MCP tool\n * `run()` and SDK server handlers alike (ruling 5: one type, one mock).\n */\nexport interface IntegrationContext<\n  Schemas extends StorageSchemas = StorageSchemas,\n> {\n  /** Identity facts — read-only, informational. Authorization already happened. */\n  readonly accountId: string;\n  readonly accountSlug: string | null;\n  readonly userId: string | null; // null for machine actors\n  readonly actor: IntegrationActor;\n  readonly sourceId: string | null;\n  readonly integration: { readonly slug: string; readonly productId: string };\n  readonly timezone: string | null;\n\n  readonly storage: IntegrationStorage<Schemas>;\n  readonly secrets: IntegrationSecrets;\n  readonly fetch: IntegrationFetch;\n  readonly logger: IntegrationLogger;\n}\n"]}

package/dist/index.d.ts

@@ -13,7 +13,7 @@
  * Relative specifiers are extensionless here on purpose. Workspace consumers
  * resolve this package's raw `src/*.ts` through a bundler, so a `./x.js`
  * specifier would point at a file that does not exist. The published ESM still
- * needs the extension for a real Node import, so `scripts/rewrite-esm-specifiers.mjs`
+ * needs the extension for a real Node import, so the build's specifier-rewrite step
  * adds it to `dist/` after the compiler runs — see that file for the full
  * rationale. Do not hand-write `.js` extensions back into this source tree.
  */
@@ -22,5 +22,6 @@ export type { ComponentReference } from './component-reference.js';
 export { isComponentReference } from './component-reference.js';
 export { DNS_NAMESPACE, EKANOS_INTEGRATION_NAMESPACE, derivePlanId, deriveProductId, uuidv5, } from './product-id.js';
 export { WorkspaceTargetSchema, WorkspaceTargetListSchema, WorkspaceTargetSlugSchema, WorkspaceTargetLayoutSchema, createWorkspaceTargetSchema, createWorkspaceTargetListSchema, normalizeWorkspaceTargets, type WorkspaceTargetSchemaOptions, type WorkspaceTargetDefinition, type ResolvedWorkspaceTarget, } from './workspace-target.js';
-export { IntegrationDefinitionSchema, parseIntegrationDefinition, validateIntegrationDefinitions, getDiscoveredToolName, assertPlainDeclaration, deepFreezeDefinition, } from './integration-definition.js';
+export { IntegrationDefinitionSchema, parseIntegrationDefinition, validateIntegrationDefinitions, collectDefinitionFindings, collectCollisionFindings, getDiscoveredToolName, assertPlainDeclaration, deepFreezeDefinition, ACCOUNT_STORAGE_DATA_TYPES, USER_STORAGE_DATA_TYPES, RESERVED_STORAGE_DATA_TYPES, } from './integration-definition.js';
+export type { Finding, CollectDefinitionOptions, } from './integration-definition.js';
 export type { IntegrationDefinition, IntegrationComponentDeclarations, IntegrationProposals, IntegrationCapabilityDeclaration, IntegrationPermissionDeclaration, PartnerWidgetDeclaration, PartnerToolModule, PartnerToolParameters, ToolClassificationProposal, DefinitionCollisionInput, FirstPartyInventory, JsonValue, PartnerWebhookDeclaration, WebhookSignatureDeclaration, WebhookEvent, WebhookResult, PartnerScheduleDeclaration, ScheduleInvocation, ScheduleResult, PartnerOAuthDeclaration, OAuthProviderDeclaration, OAuthTokens, } from './integration-definition.js';

package/dist/index.js

@@ -13,7 +13,7 @@
  * Relative specifiers are extensionless here on purpose. Workspace consumers
  * resolve this package's raw `src/*.ts` through a bundler, so a `./x.js`
  * specifier would point at a file that does not exist. The published ESM still
- * needs the extension for a real Node import, so `scripts/rewrite-esm-specifiers.mjs`
+ * needs the extension for a real Node import, so the build's specifier-rewrite step
  * adds it to `dist/` after the compiler runs — see that file for the full
  * rationale. Do not hand-write `.js` extensions back into this source tree.
  */
@@ -25,5 +25,13 @@ export { DNS_NAMESPACE, EKANOS_INTEGRATION_NAMESPACE, derivePlanId, deriveProduc
 // Workspace-target contract (F10): one schema, host injects icon validity
 export { WorkspaceTargetSchema, WorkspaceTargetListSchema, WorkspaceTargetSlugSchema, WorkspaceTargetLayoutSchema, createWorkspaceTargetSchema, createWorkspaceTargetListSchema, normalizeWorkspaceTargets, } from './workspace-target.js';
 // The integration-definition contract
-export { IntegrationDefinitionSchema, parseIntegrationDefinition, validateIntegrationDefinitions, getDiscoveredToolName, assertPlainDeclaration, deepFreezeDefinition, } from './integration-definition.js';
+export { IntegrationDefinitionSchema, parseIntegrationDefinition, validateIntegrationDefinitions, 
+// Non-throwing sibling collectors (0.2.0 surface add): recover structured
+// findings instead of a thrown, pre-formatted string. `@ekanos/cli validate`
+// consumes these; the throwing functions above are built on the same rules.
+collectDefinitionFindings, collectCollisionFindings, getDiscoveredToolName, assertPlainDeclaration, deepFreezeDefinition, 
+// The storage data_type allowlists. Exported because the HOST imports them
+// for its runtime `ctx.storage` check — one list, validated at authoring
+// time here and at access time there, so the two cannot drift.
+ACCOUNT_STORAGE_DATA_TYPES, USER_STORAGE_DATA_TYPES, RESERVED_STORAGE_DATA_TYPES, } from './integration-definition.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAsBH,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAE7D,6EAA6E;AAC7E,6EAA6E;AAC7E,kCAAkC;AAClC,OAAO,EACL,aAAa,EACb,4BAA4B,EAC5B,YAAY,EACZ,eAAe,EACf,MAAM,GACP,MAAM,cAAc,CAAC;AAEtB,0EAA0E;AAC1E,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,yBAAyB,EACzB,2BAA2B,EAC3B,2BAA2B,EAC3B,+BAA+B,EAC/B,yBAAyB,GAI1B,MAAM,oBAAoB,CAAC;AAE5B,sCAAsC;AACtC,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,EAC1B,8BAA8B,EAC9B,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC","sourcesContent":["/**\n * @ekanos/integration-schema — the canonical, dependency-pure contract for\n * Ekanos integration definitions.\n *\n * ONE zod schema, ONE set of types, imported by BOTH `@ekanos/sdk`\n * (authoring: `defineIntegration()`) and `@kit/integrations-core` (host trust\n * boundary: `registerPartnerIntegration()` re-parses against this schema).\n * This package depends on nothing but zod, so neither consumer forms a cycle\n * and there is no hand-written structural twin to drift (F3/F9/F10).\n *\n * Depends on: zod. Nothing else — no `@kit/*`, no React, no `server-only`.\n *\n * Relative specifiers are extensionless here on purpose. Workspace consumers\n * resolve this package's raw `src/*.ts` through a bundler, so a `./x.js`\n * specifier would point at a file that does not exist. The published ESM still\n * needs the extension for a real Node import, so `scripts/rewrite-esm-specifiers.mjs`\n * adds it to `dist/` after the compiler runs — see that file for the full\n * rationale. Do not hand-write `.js` extensions back into this source tree.\n */\n\n// Capability-context types (canonical home; @ekanos/sdk re-exports these)\nexport type {\n  IntegrationActor,\n  IntegrationContext,\n  IntegrationStorage,\n  ScopedStore,\n  IntegrationSecrets,\n  IntegrationFetch,\n  IntegrationLogger,\n  StorageEntry,\n  StorageWriteOptions,\n  StorageSchemas,\n  StorageSchemaMap,\n  StorageScopeSchemas,\n  StorageKeyDeclaration,\n  StorageKeyDeclarationInput,\n  StorageKeySchema,\n} from './capability-context';\n\nexport type { ComponentReference } from './component-reference';\nexport { isComponentReference } from './component-reference';\n\n// Deterministic slug → uuid derivation. One slug, one product id, everywhere\n// and forever — the SDK, the seed generator and any future gate all agree by\n// computing rather than choosing.\nexport {\n  DNS_NAMESPACE,\n  EKANOS_INTEGRATION_NAMESPACE,\n  derivePlanId,\n  deriveProductId,\n  uuidv5,\n} from './product-id';\n\n// Workspace-target contract (F10): one schema, host injects icon validity\nexport {\n  WorkspaceTargetSchema,\n  WorkspaceTargetListSchema,\n  WorkspaceTargetSlugSchema,\n  WorkspaceTargetLayoutSchema,\n  createWorkspaceTargetSchema,\n  createWorkspaceTargetListSchema,\n  normalizeWorkspaceTargets,\n  type WorkspaceTargetSchemaOptions,\n  type WorkspaceTargetDefinition,\n  type ResolvedWorkspaceTarget,\n} from './workspace-target';\n\n// The integration-definition contract\nexport {\n  IntegrationDefinitionSchema,\n  parseIntegrationDefinition,\n  validateIntegrationDefinitions,\n  getDiscoveredToolName,\n  assertPlainDeclaration,\n  deepFreezeDefinition,\n} from './integration-definition';\n\nexport type {\n  IntegrationDefinition,\n  IntegrationComponentDeclarations,\n  IntegrationProposals,\n  IntegrationCapabilityDeclaration,\n  IntegrationPermissionDeclaration,\n  PartnerWidgetDeclaration,\n  PartnerToolModule,\n  PartnerToolParameters,\n  ToolClassificationProposal,\n  DefinitionCollisionInput,\n  FirstPartyInventory,\n  JsonValue,\n  // Event surfaces (webhooks, schedules, OAuth) — interface-first: the local\n  // harness executes them today; the host transports bind to them later.\n  PartnerWebhookDeclaration,\n  WebhookSignatureDeclaration,\n  WebhookEvent,\n  WebhookResult,\n  PartnerScheduleDeclaration,\n  ScheduleInvocation,\n  ScheduleResult,\n  PartnerOAuthDeclaration,\n  OAuthProviderDeclaration,\n  OAuthTokens,\n} from './integration-definition';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAsBH,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAE7D,6EAA6E;AAC7E,6EAA6E;AAC7E,kCAAkC;AAClC,OAAO,EACL,aAAa,EACb,4BAA4B,EAC5B,YAAY,EACZ,eAAe,EACf,MAAM,GACP,MAAM,cAAc,CAAC;AAEtB,0EAA0E;AAC1E,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,yBAAyB,EACzB,2BAA2B,EAC3B,2BAA2B,EAC3B,+BAA+B,EAC/B,yBAAyB,GAI1B,MAAM,oBAAoB,CAAC;AAE5B,sCAAsC;AACtC,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,EAC1B,8BAA8B;AAC9B,0EAA0E;AAC1E,6EAA6E;AAC7E,4EAA4E;AAC5E,yBAAyB,EACzB,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB;AACpB,2EAA2E;AAC3E,yEAAyE;AACzE,+DAA+D;AAC/D,0BAA0B,EAC1B,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,0BAA0B,CAAC","sourcesContent":["/**\n * @ekanos/integration-schema — the canonical, dependency-pure contract for\n * Ekanos integration definitions.\n *\n * ONE zod schema, ONE set of types, imported by BOTH `@ekanos/sdk`\n * (authoring: `defineIntegration()`) and `@kit/integrations-core` (host trust\n * boundary: `registerPartnerIntegration()` re-parses against this schema).\n * This package depends on nothing but zod, so neither consumer forms a cycle\n * and there is no hand-written structural twin to drift (F3/F9/F10).\n *\n * Depends on: zod. Nothing else — no `@kit/*`, no React, no `server-only`.\n *\n * Relative specifiers are extensionless here on purpose. Workspace consumers\n * resolve this package's raw `src/*.ts` through a bundler, so a `./x.js`\n * specifier would point at a file that does not exist. The published ESM still\n * needs the extension for a real Node import, so the build's specifier-rewrite step\n * adds it to `dist/` after the compiler runs — see that file for the full\n * rationale. Do not hand-write `.js` extensions back into this source tree.\n */\n\n// Capability-context types (canonical home; @ekanos/sdk re-exports these)\nexport type {\n  IntegrationActor,\n  IntegrationContext,\n  IntegrationStorage,\n  ScopedStore,\n  IntegrationSecrets,\n  IntegrationFetch,\n  IntegrationLogger,\n  StorageEntry,\n  StorageWriteOptions,\n  StorageSchemas,\n  StorageSchemaMap,\n  StorageScopeSchemas,\n  StorageKeyDeclaration,\n  StorageKeyDeclarationInput,\n  StorageKeySchema,\n} from './capability-context';\n\nexport type { ComponentReference } from './component-reference';\nexport { isComponentReference } from './component-reference';\n\n// Deterministic slug → uuid derivation. One slug, one product id, everywhere\n// and forever — the SDK, the seed generator and any future gate all agree by\n// computing rather than choosing.\nexport {\n  DNS_NAMESPACE,\n  EKANOS_INTEGRATION_NAMESPACE,\n  derivePlanId,\n  deriveProductId,\n  uuidv5,\n} from './product-id';\n\n// Workspace-target contract (F10): one schema, host injects icon validity\nexport {\n  WorkspaceTargetSchema,\n  WorkspaceTargetListSchema,\n  WorkspaceTargetSlugSchema,\n  WorkspaceTargetLayoutSchema,\n  createWorkspaceTargetSchema,\n  createWorkspaceTargetListSchema,\n  normalizeWorkspaceTargets,\n  type WorkspaceTargetSchemaOptions,\n  type WorkspaceTargetDefinition,\n  type ResolvedWorkspaceTarget,\n} from './workspace-target';\n\n// The integration-definition contract\nexport {\n  IntegrationDefinitionSchema,\n  parseIntegrationDefinition,\n  validateIntegrationDefinitions,\n  // Non-throwing sibling collectors (0.2.0 surface add): recover structured\n  // findings instead of a thrown, pre-formatted string. `@ekanos/cli validate`\n  // consumes these; the throwing functions above are built on the same rules.\n  collectDefinitionFindings,\n  collectCollisionFindings,\n  getDiscoveredToolName,\n  assertPlainDeclaration,\n  deepFreezeDefinition,\n  // The storage data_type allowlists. Exported because the HOST imports them\n  // for its runtime `ctx.storage` check — one list, validated at authoring\n  // time here and at access time there, so the two cannot drift.\n  ACCOUNT_STORAGE_DATA_TYPES,\n  USER_STORAGE_DATA_TYPES,\n  RESERVED_STORAGE_DATA_TYPES,\n} from './integration-definition';\n\nexport type {\n  Finding,\n  CollectDefinitionOptions,\n} from './integration-definition';\n\nexport type {\n  IntegrationDefinition,\n  IntegrationComponentDeclarations,\n  IntegrationProposals,\n  IntegrationCapabilityDeclaration,\n  IntegrationPermissionDeclaration,\n  PartnerWidgetDeclaration,\n  PartnerToolModule,\n  PartnerToolParameters,\n  ToolClassificationProposal,\n  DefinitionCollisionInput,\n  FirstPartyInventory,\n  JsonValue,\n  // Event surfaces (webhooks, schedules, OAuth) — interface-first: the local\n  // harness executes them today; the host transports bind to them later.\n  PartnerWebhookDeclaration,\n  WebhookSignatureDeclaration,\n  WebhookEvent,\n  WebhookResult,\n  PartnerScheduleDeclaration,\n  ScheduleInvocation,\n  ScheduleResult,\n  PartnerOAuthDeclaration,\n  OAuthProviderDeclaration,\n  OAuthTokens,\n} from './integration-definition';\n"]}

package/dist/integration-definition.d.ts

@@ -17,6 +17,37 @@ type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonValue[] | {
     [key: string]: JsonValue;
 };
+/**
+ * The `data_type` values each storage scope permits.
+ *
+ * THIS IS THE SOURCE OF TRUTH, and it lives here rather than in the host
+ * because this package is the one a partner's `defineIntegration()` validates
+ * against — a declaration naming an impossible data_type should fail at
+ * authoring time, not on the first `ctx.storage` call in production. The host
+ * (`apps/web/lib/server/integration-context.ts`) imports these same arrays for
+ * its runtime check, so the two cannot drift.
+ *
+ * They mirror the DB CHECK constraints on `account_product_data` and
+ * `user_product_data` (`apps/web/supabase/schemas/26-integrations.sql`), with
+ * one deliberate subtraction: see `RESERVED_STORAGE_DATA_TYPES`.
+ */
+export declare const ACCOUNT_STORAGE_DATA_TYPES: readonly ["activation", "settings", "metrics_summary", "sync_state", "cache"];
+export declare const USER_STORAGE_DATA_TYPES: readonly ["config", "preferences", "cache"];
+/**
+ * In the DB CHECK but NEVER addressable through `ctx.storage`.
+ *
+ * `secret` rows are host-managed per-name credential rows whose values live in
+ * Vault; partner code reaches them only through `ctx.secrets`, which never
+ * exposes a value or a vault id. Letting a partner DECLARE `secret` storage
+ * would hand them a key that collides with host-managed secret rows, so it is
+ * rejected here with its own message rather than the generic "not an allowed
+ * data_type" — an author who wrote `secret` meant something specific and needs
+ * to be pointed at `ctx.secrets`.
+ *
+ * Kept as its own list rather than simply omitted from the arrays above so the
+ * reason survives: `secret` is a real column value, not a typo.
+ */
+export declare const RESERVED_STORAGE_DATA_TYPES: readonly ["secret"];
 declare const capabilitySchema: z.ZodObject<{
     label: z.ZodString;
     description: z.ZodString;
@@ -854,8 +885,8 @@ export declare const IntegrationDefinitionSchema: z.ZodEffects<z.ZodObject<{
         outputExample?: Record<string, JsonValue> | undefined;
     }>, "many">>;
     storage: z.ZodOptional<z.ZodObject<{
-        account: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodType<StorageKeyDeclarationInput, z.ZodTypeDef, StorageKeyDeclarationInput>, StorageKeyDeclarationInput, StorageKeyDeclarationInput>>>;
-        user: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodType<StorageKeyDeclarationInput, z.ZodTypeDef, StorageKeyDeclarationInput>, StorageKeyDeclarationInput, StorageKeyDeclarationInput>>>;
+        account: z.ZodOptional<z.ZodRecord<z.ZodEffects<z.ZodString, string, string>, z.ZodEffects<z.ZodType<StorageKeyDeclarationInput, z.ZodTypeDef, StorageKeyDeclarationInput>, StorageKeyDeclarationInput, StorageKeyDeclarationInput>>>;
+        user: z.ZodOptional<z.ZodRecord<z.ZodEffects<z.ZodString, string, string>, z.ZodEffects<z.ZodType<StorageKeyDeclarationInput, z.ZodTypeDef, StorageKeyDeclarationInput>, StorageKeyDeclarationInput, StorageKeyDeclarationInput>>>;
     }, "strict", z.ZodTypeAny, {
         user?: Record<string, StorageKeyDeclarationInput> | undefined;
         account?: Record<string, StorageKeyDeclarationInput> | undefined;
@@ -1681,6 +1712,38 @@ export interface IntegrationDefinition<Schemas extends StorageSchemas = StorageS
     oauth?: PartnerOAuthDeclaration<Schemas>;
     proposes?: IntegrationProposals;
 }
+/**
+ * One structured validation result. This is the committed shape the CLI and
+ * any other tooling consumes — the collectors below return arrays of these,
+ * and the throwing entry points (`parseIntegrationDefinition`,
+ * `validateIntegrationDefinitions`) are built on the exact same rules so there
+ * is one rule set, not two.
+ *
+ * `line` is deliberately optional and usually ABSENT: zod reports a `path`
+ * (`components.widgets[2].id`), not a byte offset into a source file, and
+ * fabricating a line number would be a lie. The zod path lives in `message`;
+ * `file` names the module the definition was loaded from when the caller knows
+ * it. `hint` is always a non-empty, imperative remediation instruction.
+ */
+export interface Finding {
+    check: string;
+    severity: 'error' | 'warn' | 'info';
+    file?: string;
+    line?: number;
+    message: string;
+    hint: string;
+}
+export interface CollectDefinitionOptions {
+    /** The module the definition was loaded from, stamped onto every finding. */
+    file?: string;
+}
+/**
+ * Non-throwing sibling of `parseIntegrationDefinition`: validates a single
+ * integration definition against the canonical schema and returns structured
+ * findings instead of throwing a pre-formatted string. An empty array means
+ * the definition is valid. Used by `@ekanos/cli validate`.
+ */
+export declare function collectDefinitionFindings(input: unknown, options?: CollectDefinitionOptions): Finding[];
 /**
  * F4: reject accessor/proxy/class-instance/cyclic declaration containers
  * before parsing. An object with getters (or a proxy) can return validated
@@ -1721,8 +1784,8 @@ export declare function parseIntegrationDefinition(input: unknown): IntegrationD
  * 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`).
+ * duplicate assignment. Host-side tool discovery calls this same helper, so
+ * there is one definition of the effective name.
  */
 export declare function getDiscoveredToolName(slug: string, rawName: string): string;
 /**
@@ -1758,14 +1821,11 @@ export interface FirstPartyInventory {
     toolNames?: readonly string[];
 }
 /**
- * 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.
+ * Non-throwing sibling of `validateIntegrationDefinitions`: returns structured
+ * collision findings across the partner set (and against the first-party
+ * inventory) instead of throwing. An empty array means no collisions. Used by
+ * `@ekanos/cli validate`.
  */
+export declare function collectCollisionFindings(definitions: readonly DefinitionCollisionInput[], firstParty?: FirstPartyInventory): Finding[];
 export declare function validateIntegrationDefinitions(definitions: readonly DefinitionCollisionInput[], firstParty?: FirstPartyInventory): void;
 export {};