docs(triggers): TRG-1 gate records, event-transport matrices, and the checker's --design-root

[erichare]

TRG-1: gate records, event-transport matrices, and the checker's --design-root

Docs-only, plus one CI checker. Base: feat/int-1-discovery-gate (#14906), not feat/trg-1-triggers-gate
(#14911) — see "Why this base" below. #14911's content is an ancestor of this branch, so merging this closes both.

Summary

• Findings stub at design/dedicated-integrations-triggers/findings/2026-09-listeners.md (exit criterion 1):
  the dated evidence on both precedents and on why neither shape survives the current runtime, with the sidecar
  position and the recommendation left as marked author sections for the platform owner. It stays Status: draft and
  criterion 1 stays open.
• Event-transport matrices and schema (criterion 2): schema/event_transport.schema.json plus
  matrices/{google,microsoft,slack}-events.json. Every mechanism records track, ingress requirement, inbound
  authentication, subscription TTL and renewal, payload shape, delivery guarantee, replay availability, rate limits,
  dedupe key, session key, and the deployment contexts it supports, each claim pointing at a dated provider-docs
  source. Excluded and deferred mechanisms are recorded with their reason so nobody re-opens them:
  Slack RTM (excluded), Graph rich resource-data notifications (deferred on certificate lifecycle), and Teams message
  subscriptions (excluded: protected APIs, application permissions and a Teams billing model) — which is this gate's
  answer to the open "Teams messages" question.
• decisions/process-model.md (criterion 3): both shapes. A separate langflow listeners process is
  primary; LANGFLOW_LISTENERS_MODE=subprocess is the single-container and Desktop shape; the dispatcher and the
  schedule tick stay in the API lifespan under a trigger_lease singleton; lfx serve hosts neither listeners nor a
  trigger ingress, which answers the "Track A on lfx serve" question with no. Lease semantics: TTL 30 s,
  heartbeat 10 s, reconcile poll 5 s, failover within two TTLs. Health on LANGFLOW_LISTENERS_HEALTH_PORT (7861).
• decisions/self-managed-ingress.md (criterion 4): the no-relay statement first — Langflow operates no
  relay, in this release or as a follow-up. Every provider therefore ships at least one outbound-only mechanism
  (Slack Socket Mode, Graph delta, Google sync-token / page-token polling and Pub/Sub pull), which settles "Calendar
  and Drive without ingress" as poll, not relay, "Slack on Desktop" as Socket Mode with a customer-owned app, and
  moves the deferred record's third re-open trigger from two of three providers to three of three.
• decisions/delivery-semantics.md (criterion 5): at-least-once collapsed once by a
  UNIQUE (trigger_id, dedupe_key) index; write-then-ack; a 7-day replay window with a 30-day purge; replay writes a
  new linked row rather than mutating; retries with backoff to max_attempts then dead-letter; no cross-trigger
  ordering; per-trigger concurrency as the backpressure knob.
• trigger-contract.md (criterion 6): the record TRG-2 through TRG-7 build against — five tables in one
  migration, binding and pinning, the trigger_push / trigger_listener families executing as flow_owner with
  actor trigger_dispatcher, provider_signed as the ingress access mode, authz on the flow resource, and the
  boundary with the 1.13 connection contract. Session derivation is stated as the precedence TRG-2 implements: a
  provider conversation key on the event payload wins, otherwise the trigger's two-value session_policy
  (per_event → trigger:{trigger_id}:{event_id}, shared → trigger:{trigger_id}). Accepted by the release
  owner; the lfx, langflow-base, Enterprise and platform sign-offs are outstanding.
• frontend-surfaces.md (criterion 8): every surface with its owning ticket, plus the trigger display-name rule
  Product: On Event extending the 1.13 Product: Verb Object palette rule, the server-driven allowed_actions
  contract, config-driven polling with no SSE, and the interim connection field TRG-7 uses until INT-8's shared
  picker lands.
• estimate.md (criterion 9): 34 engineer-weeks re-issued as 39.5 across TRG-1 to TRG-8, per ticket with a
  named cause for every delta, plus sequencing and external lead times.
• The three 1.13 records the triggers decision supersedes are amended here, not left to contradict the gate
  (DECISIONS.md item 1: amend in the pull request that implements the work). Each carries a dated
  "release owner decision, 2026-09-04" note: design/dedicated-integrations/estimate.md (the triggers exclusion —
  the 48.75-engineer-week actions total is unchanged, the 39.5 sit alongside it),
  design/dedicated-integrations/triggers-deferred.md (Status re-opened, plus an Amendment section walking its own
  three re-open clauses and restating the boundary it fixed, which still binds every wave-1 action), and the INT-1
  README's exit-criterion row 6. The "1.14 candidate" framing is gone from the triggers README itself.
• Checker --design-root: scripts/ci/check_capability_matrices.py gains --design-root (and --matrix-dir
  now defaults to <design-root>/matrices). A design root that publishes schema/event_transport.schema.json is
  validated as a triggers gate; every other root, INT-1's included, behaves exactly as before. The triggers rules live
  in the new scripts/ci/event_transport_matrix.py: JSON Schema validation, sourced claims, and the no-ingress rule
  per context — a mechanism needing public HTTPS may not claim a context whose public_ingress_by_context entry is
  unavailable, a conditional context is allowed only against an outbound_only fallback covering that same
  context, and every provider must ship at least one outbound-only wave-1 mechanism. The CI Scripts Tests workflow now
  watches design/dedicated-integrations-triggers/**.
• README updated for the 1.13 decision: title, status, the real per-criterion statuses, both remaining open rows,
  Google push channels added to the Track A list (they were in no gate record before), the full sign-off map, and the
  checker invocation.

Why this base

scripts/ci/check_capability_matrices.py — the checker this pull request extends — is introduced by #14906
(feat/int-1-discovery-gate) and exists neither on release-1.13.0 nor on feat/trg-1-triggers-gate
(git ls-tree origin/feat/trg-1-triggers-gate scripts/ci/check_capability_matrices.py returns nothing). The triggers
README also links ../dedicated-integrations/... records from that same pull request, and this branch amends three of
them. Basing on #14906 keeps INT-1's eighteen files and ~5,800 lines out of this diff and avoids an add/add conflict
on files TRG-1 never touched once #14906 squash-merges into release-1.13.0.

#14911's two files are ancestors of this branch, so #14911 needs no separate merge. The diff against #14906 also
carries twelve files of release-1.13.0 drift between the two branch points (the funasr bundle and its
registration seams, ~530 lines); those disappear once #14906 merges. The TRG-1 work itself is nineteen files,
+2879/−79 (git diff 13e88b13ce..HEAD).

Verification

$ uv run --no-sync python -m pytest scripts/ci/ -q
212 passed in 9.66s

$ uv run --no-sync python -m pytest scripts/ci/test_event_transport_matrices.py -q
25 passed

$ uv run --no-sync python -m pytest scripts/ci/test_capability_matrices.py -q
36 passed            # unchanged from the pre-change baseline on this branch

$ uv run --no-sync python scripts/ci/check_capability_matrices.py
Capability matrices are complete for .../design/dedicated-integrations.

$ uv run --no-sync python scripts/ci/check_capability_matrices.py --design-root design/dedicated-integrations-triggers
Event-transport matrices are complete for .../design/dedicated-integrations-triggers.

$ uv run --no-sync python scripts/ci/check_capability_matrices.py --design-root design/dedicated-integrations-triggers --require-accepted
exit 1 — 20 errors, all of the form "must complete Name, Date, and PR"

$ uv run --no-sync python scripts/ci/check_capability_matrices.py --require-accepted
exit 1 — 34 errors, all of the form "must complete Name, Date, and PR"   # INT-1's own pre-existing state

The two --require-accepted failures are expected and one of them is asserted by a test: gate-close mode fails while
the sign-off tables are empty, and it reports only outstanding signatures — no structural errors. The INT-1 run is
included to show this branch's amendments introduce none either.

$ uv run --no-sync ruff check scripts/ci/event_transport_matrix.py scripts/ci/test_event_transport_matrices.py scripts/ci/check_capability_matrices.py
All checks passed!
$ uv run --no-sync ruff format --check <same files>
3 files already formatted

No backend, frontend or lfx suite is exercised: this pull request changes no runtime code.

Review round

Three changes after review, all on this branch:

1. trigger-contract.md now compiles against the parallel TRG-2 build. The record calls itself normative, and two
   of its names were rejected by TRG-2's CHECK constraints: session_policy: provider_correlated (TRG-2 ships
   per_event | shared, and the record did not document shared at all) and trigger_event.state: replayed
   (TRG-2 ships six states; a replay is a new linked row). Also dropped the enabled and mechanism_id columns
   TRG-2's migration does not create, recorded job_id's deliberate lack of a foreign key, added the columns TRG-2
   does create, and named the two singleton leases by their constants — trigger_dispatcher and trigger_scheduler,
   not dispatcher/schedule_tick — so TRG-3's dispatcher cannot claim a different row and drain the ledger in
   parallel.
2. The amendments the gate claimed now exist (see the Summary bullet above).
3. The checker reports malformed matrices instead of raising. Three reads assumed a well-formed file even though
   the rules also run on one that already failed the schema: the inbound_auth/payload/delivery/dedupe_key
   enum checks raised AttributeError on a scalar block, and both the duplicate-id set and the no-ingress index
   raised TypeError on an unhashable mechanism_id. Two new tests cover it. scripts/ci was also put on
   sys.path so python -m scripts.ci.check_capability_matrices works alongside running the file directly.

What is still open (and deliberately so)

• Exit criterion 1 — the findings document is a stub; sections 3 and 4 are the platform owner's to write. The
  README and the record both say so. It is the one record left at Status: draft: marking a stub accepted would make
  the README's criterion-1 row read done before it is written. The checker only enforces accepted under
  decisions/, so flipping it is a one-line change if the release owner prefers the letter of the rule.
• Exit criterion 7 — the 1.13 conformance walk needs merged INT-2, INT-5 and INT-6 pull requests, and those are
  open. One gap is already recorded in the README boundary table: connection-contract.md assigns the
  connection_resolution matrix dimension and its checker vocabulary to INT-4 and INT-5, and neither feat(integrations): add persistent connection API #14921 nor
  feat(integrations): broker delegated OAuth connections #14935 delivers it; INT-6 now carries it. The walk is repeated before gate close.
• Six sign-off rows across the README and the records. Status: accepted records the release owner's acceptance
  only; the other roles sign in review.
• Jira estimate fields are untouched. estimate.md carries the per-ticket 39.5-week breakdown with the right keys
  (LE-2481, LE-2479, LE-2478, LE-2483, LE-2484, LE-2485, LE-2482 under epic LE-2477); pushing those numbers into the
  Jira fields is a human pass.
• Provider facts wanting one owner verification before the ticket that cites them ships: Slack's 30,000
  events/hour per-workspace ceiling (carried as an open question on the mechanism row), Microsoft Graph subscription
  lifetimes (4230 minutes for Outlook, confidence: medium, recorded as "read subscriptionExpirationDateTime, do
  not assume a constant"), and the Google Calendar/Drive channel expiries, left as max_ttl_seconds: null rather
  than invented.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (1)

• release-.*

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: d2284daa-3c51-4367-90da-742a69280f7c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Test Coverage Advisor

No source changes detected without accompanying tests. Thanks for keeping coverage up! 🎉

Advisory check only — never blocks merge.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 66.74%. Comparing base (be623cc) to head (a677af7).

Additional details and impacted files

@@                      Coverage Diff                      @@
##           feat/int-1-discovery-gate   #14955      +/-   ##
=============================================================
+ Coverage                      66.45%   66.74%   +0.29%     
=============================================================
  Files                           2499     2509      +10     
  Lines                         259913   261683    +1770     
  Branches                       36772    39325    +2553     
=============================================================
+ Hits                          172736   174673    +1937     
+ Misses                         85009    84846     -163     
+ Partials                        2168     2164       -4     

Flag	Coverage Δ
backend	74.12% <ø> (-0.08%)	⬇️
frontend	64.98% <ø> (+0.41%)	⬆️
lfx	64.86% <ø> (-0.02%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 149 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Frontend Unit Test Coverage Report

Coverage Summary

Lines	Statements	Branches	Functions
	55.65% (84754/152292)	72.47% (12552/17320)	50.95% (2000/3925)

Unit Test Results

Tests	Skipped	Failures	Errors	Time
6641	0 💤	0 ❌	0 🔥	20m 7s ⏱️