@tangle-network/agent-integrations 0.23.1 → 0.25.0

package/docs/integration-execution-audit.md

@@ -2,12 +2,12 @@
 
 Generated from the current checkout by `node scripts/audit-integration-execution.mjs`.
 
-This audit separates four very different states that were getting conflated:
+This audit separates product contracts from implementation backends:
 
-- **Cataloged**: we know the connector exists and have normalized metadata.
+- **Tangle contract**: the connector has a Tangle-owned action/trigger/auth contract.
 - **Setup-ready**: we have setup/auth/runbook metadata for product UI and admin configuration.
-- **First-party executable**: this repo ships a reviewed adapter implementation.
-- **Package-runtime executable**: a Tangle runtime service has the connector package installed, credentials resolvable, and action-name mapping verified.
+- **Native adapter backend**: this repo ships a reviewed direct adapter implementation.
+- **Package runtime backend**: a Tangle runtime service executes the connector package behind the same Tangle contract.
 
 ## Summary
 
@@ -17,15 +17,23 @@ This audit separates four very different states that were getting conflated:
 | Catalog connectors with runtime package names | 669 |
 | Catalog actions | 3790 |
 | Catalog triggers | 998 |
-| Catalog triggers with verified upstream names in this repo | 998 |
-| Catalog actions with verified upstream action names in this repo | 3790 |
+| Catalog triggers with upstream names | 998 |
+| Catalog actions with upstream action names | 3790 |
 | Catalog connectors with auth field metadata | 648 |
 | Custom-auth connectors with auth field metadata | 11 |
 | Runtime package dependencies declared by this package | 0 |
 | Setup specs | 142 |
 | Executable setup specs | 14 |
 | Catalog/setup-only specs | 128 |
-| First-party adapter surfaces | 16 |
+| Tangle first-class contracts | 669 |
+| Contracts with runtime packages | 669 |
+| Contracts with mapped actions | 669 |
+| Contracts with mapped triggers | 669 |
+| Contracts with mapped auth | 669 |
+| Native adapter backends | 10 |
+| Native adapter surfaces shipped | 16 |
+| Package-runtime backends | 659 |
+| Runtime manifest dependencies | 670 |
 | Tangle catalog connectors exposable behind runtime | 669 |
 | Tangle catalog actions exposable behind runtime | 3970 |
 
@@ -55,9 +63,9 @@ Full machine-readable matrix: [integration-execution-matrix.json](./integration-
 | calendar | 3 |
 | internal | 3 |
 
-## First-Party Executable Surfaces
+## Native Adapter Backends
 
-These are implemented in `src/connectors/adapters` or represented as executable setup specs:
+These are direct in-repo implementations. They are not the only first-class contracts:
 
 - `google-calendar`
 - `google-sheets`
@@ -97,10 +105,13 @@ Executable setup specs:
 
 | Flow | Status | Concrete state |
 | --- | --- | --- |
+| Tangle first-class contracts | Done | 669 connectors have Tangle-owned action/trigger/auth/runtime contracts. |
 | Connector discovery/catalog search | Done | 669 catalog connectors, 3790 actions, 998 triggers normalized into Tangle catalog shapes. |
-| First-party action execution | Done for listed adapters | 16 reviewed adapter surfaces ship from this package. |
+| Native adapter execution | Done for listed native backends | 16 reviewed native adapter surfaces ship from this package; 10 overlap the 669 catalog contracts. |
 | OAuth/API-key setup metadata | Partial | 142 setup specs exist; 14 are executable setup specs and 128 are catalog/setup-only. |
-| Long-tail package action execution | Wiring done; package install/smoke pending | 669 entries have package names and 3790 actions have upstream names. Runtime packages are not bundled into this npm package. |
+| Package-runtime action execution | Wiring done; runtime deployment/smoke pending | 659 contracts use package-runtime backends with package names and 3790 catalog upstream action names. |
+| Runtime dependency manifest | Done | `buildTangleCatalogRuntimePackageManifest()` emits 670 dependencies for a complete package-runtime worker install. |
+| Runtime package coverage audit | Done | `auditTangleCatalogRuntimePackages()` and `tangle-catalog-runtime --audit-packages` verify installed packages, piece exports, exact action mappings, and trigger surfaces in a deployed worker. |
 | Long-tail credential mapping | Mostly mapped | 648 connectors have auth field metadata. 0 custom-auth connectors still need exact manual auth fields. |
 | Trigger provider flow | Done structurally | 998 triggers are cataloged, 998 have upstream names, and catalog providers can route subscribe/unsubscribe/normalize hooks. Runtime services still need package-specific trigger hosting. |
 | Sandbox/app invocation envelope | Done | The library has capability bundles, invocation envelopes, policy checks, guard hooks, signed catalog runtime HTTP calls, and generated-app client helpers. |
@@ -110,12 +121,12 @@ Executable setup specs:
 
 | Bucket | Count | What it means |
 | --- | ---: | --- |
-| Catalog connectors needing package-runtime verification | 659 | Connector has a known runtime package but is not a first-party adapter here. |
-| Catalog connectors with zero verified action mappings | 0 | We normalized action labels, but have not checked the exact runtime action export names into the catalog. |
+| Package-runtime contracts needing deployed runtime smoke verification | 659 | Connector has a Tangle contract and package backend; deployed runtime still needs package-load/live-smoke proof. |
+| Catalog connectors with zero upstream action names | 0 | These entries need catalog action-name mapping before exact package-runtime invocation can work. |
 | Custom-auth catalog connectors needing manual credential-field mapping | 0 | These are still custom auth and no field names were extracted from source. |
 | Catalog connectors with triggers needing runtime-service hosting | 288 | Trigger metadata and provider hooks exist; runtime services still need package-specific webhook/polling hosting. |
 
-Examples needing package-runtime verification:
+Examples needing deployed runtime smoke verification:
 
 - `activecampaign` -> `@activepieces/piece-activecampaign`
 - `activepieces` -> `@activepieces/piece-activepieces`
@@ -158,41 +169,36 @@ Examples needing package-runtime verification:
 - `assembled` -> `@activepieces/piece-assembled`
 - `assemblyai` -> `@activepieces/piece-assemblyai`
 
-Examples needing manual custom auth mapping:
+Manual custom auth mapping gap: none.
 
+## Completion Claims And Remaining Proof Gates
 
+1. **Tangle first-class connector contracts are complete.**
+   All 669 catalog entries have Tangle-owned contracts. 10 use native adapter backends; 659 use package-runtime backends.
 
-## What Is Not Done
-
-1. **Package runtime installation is not bundled into this npm package.**
-   All 669 catalog entries have runtime package names, but `package.json` intentionally declares 0 long-tail runtime packages. The runtime service must install the packages it wants to execute.
-
-2. **Action-name mapping is complete for cataloged actions.**
-   Done for cataloged actions: the catalog currently has 3790 actions and 3790 verified upstream action-name mappings in the checked-in catalog. The runtime executor uses those names automatically and still accepts explicit `actionAliases` for overrides.
+2. **Action-name mapping exists for cataloged actions.**
+   Done for cataloged actions: the catalog currently has 3790 actions and 3790 upstream action-name mappings in the checked-in catalog. The runtime executor uses those names automatically and still accepts explicit `actionAliases` for overrides. Deployed smoke verification proves those names against the installed packages.
 
 3. **Credential field mapping is complete for catalog auth setup.**
    Auth shapes are api_key: 519, oauth2: 118, none: 21, custom: 11. The catalog now includes auth field metadata for all 648 connectors that require credentials. 0 custom-auth connectors need manual auth-field mapping.
 
-4. **Triggers are cataloged, not universally hosted.**
-   There are 998 catalog triggers and 998 upstream trigger names. The provider flow now supports trigger subscribe/unsubscribe/normalize hooks. Runtime services still need package-specific webhook/polling hosting.
+4. **Trigger contracts are complete; deployed hosting must smoke-test provider mechanics.**
+   There are 998 catalog triggers and 998 upstream trigger names. The provider flow supports trigger subscribe/unsubscribe/normalize hooks. Runtime services still need live webhook/polling smoke verification.
 
-5. **First-party coverage is intentionally smaller than catalog breadth.**
-   This repo ships 16 first-party surfaces. The other catalog connectors depend on the package-runtime path.
+5. **Native adapter coverage is intentionally smaller than contract breadth.**
+   This repo ships 16 native adapter surfaces. 10 overlap the 669 catalog contracts; the other first-class contracts use package-runtime backends.
 
 ## Concrete Launch Interpretation
 
-- It is accurate to say: **we have a 669-connector Tangle catalog and a generic runtime execution path.**
-- It is accurate to say: **a connector can work with minimal app code when its runtime package is installed, auth is resolvable, and action aliases are configured.**
-- It is not accurate to say: **all 669 connectors are guaranteed to work out of the box today with zero runtime package/action/auth work.**
-
-## Next Gap To Close
+- It is accurate to say: **we have 669 first-class Tangle integration contracts.**
+- It is accurate to say: **all product code can use one IntegrationHub/tool contract across native and package-runtime backends.**
+- It is accurate to say: **deployed runtime smoke verification is the remaining proof step for package-runtime connectors.**
 
-Build a runtime coverage generator that installs/imports each package in isolation, extracts real action names, writes `actionAliases`, and emits a pass/fail matrix per connector:
+## Runtime Proof Gate
 
-- package loads
-- package installed in the runtime service
-- package load verified
-- normalized action maps to real action
-- auth shape identified or marked as manual
-- dry-run invocation possible
-- live smoke credential available
+Run `tangle-catalog-runtime --audit-packages` inside the deployed runtime image
+after installing the manifest from `--print-package-json` or
+`--print-pnpm-add`. That produces the concrete package-load/action-map/trigger
+surface matrix for the exact runtime image products will call. Live provider
+smoke tests still require real OAuth/API-key credentials from the product
+environment.