<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-06-26-2-core-integration-boundary/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-06-26-2-core-integration-boundary/</id>
  <title>ADR: CORE / INTEGRATION Boundary Model</title>
  <updated>2026-06-26T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-06-26-2-core-integration-boundary/"/>
  <summary>Enforces a one-directional CORE-to-INTEGRATION import rule in place using adapter registries and an AST gate, before any physical extraction to `src/orchestrator/`.</summary>
  <content type="html">&lt;h2 id=&quot;core--integration-boundary-model&quot;&gt;CORE / INTEGRATION Boundary Model&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Filename:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;2026-06-26-2-core-integration-boundary.md&lt;/code&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-06-26&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Jeroen Nouws (owner), Spec Kitty planning system (recommendation)&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Mission &lt;code dir=&quot;auto&quot;&gt;integration-boundary-01KW0PBE&lt;/code&gt; — fix and enforce the CORE/INTEGRATION boundary&lt;/li&gt;
&lt;li&gt;ADR &lt;code dir=&quot;auto&quot;&gt;docs/adr/3.x/2026-05-11-1-defer-391-structural-extraction-from-3-2-x.md&lt;/code&gt; — context for deferred physical extraction&lt;/li&gt;
&lt;li&gt;Historical ownership context: &lt;a href=&quot;/architecture/05_ownership_map/&quot;&gt;ownership map&lt;/a&gt; (narrative only; current enforced sources are listed under More Information).&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/&lt;/code&gt; contains two conceptually distinct layers: a &lt;strong&gt;CORE&lt;/strong&gt; layer that
implements the canonical mission lifecycle and governance logic, and an &lt;strong&gt;INTEGRATION&lt;/strong&gt;
layer that connects spec-kitty to external systems (SaaS, issue trackers, orchestrator).&lt;/p&gt;
&lt;p&gt;Before this mission, three import leaks allowed CORE modules to depend directly on
INTEGRATION modules, violating the intended separation. These violations:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Made the governance engine dependent on external-connector availability and startup
ordering.&lt;/li&gt;
&lt;li&gt;Made isolated testing of CORE logic harder (import side effects from INTEGRATION).&lt;/li&gt;
&lt;li&gt;Prevented future physical extraction of INTEGRATION to &lt;code dir=&quot;auto&quot;&gt;src/orchestrator/&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;This ADR records the boundary model, the one-directional rule, all allowlist exemptions,
and deferred scope items so that contributors can understand the model without reading the
enforcement test.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;CORE governance logic (state machine, mission creation, readiness, invocation lifecycle)
must remain fast and independently testable without importing outbound connectors.&lt;/li&gt;
&lt;li&gt;INTEGRATION modules (sync, tracker, SaaS, orchestrator client) can legitimately read
CORE state; the reverse dependency is an architectural inversion.&lt;/li&gt;
&lt;li&gt;The observer/adapter registry pattern (already in use for &lt;code dir=&quot;auto&quot;&gt;status/adapters.py&lt;/code&gt;) is the
proven mechanism for decoupling CORE events from INTEGRATION consumers.&lt;/li&gt;
&lt;li&gt;Physical extraction to &lt;code dir=&quot;auto&quot;&gt;src/orchestrator/&lt;/code&gt; is a planned future step; the boundary must
be enforced in-place first so that extraction can proceed safely.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;(A) Enforce in-place boundary&lt;/strong&gt; — add adapter registries in CORE; move INTEGRATION
logic into INTEGRATION-owned consumers; enforce with an AST-based test.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;(B) Defer until physical extraction&lt;/strong&gt; — allow the leaks to remain until
&lt;code dir=&quot;auto&quot;&gt;src/orchestrator/&lt;/code&gt; is ready.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;(C) Silently allowlist all three leaks&lt;/strong&gt; — add three blanket exemptions to the test.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option: (A) Enforce in-place boundary&lt;/strong&gt;, because CORE governance logic must be
independently testable and the adapter-registry pattern is already proven in the codebase.
Options (B) and (C) preserve structural coupling that makes the governance engine brittle.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;set-definitions&quot;&gt;Set Definitions&lt;/h2&gt;
&lt;h3 id=&quot;core-set&quot;&gt;CORE Set&lt;/h3&gt;
&lt;p&gt;Modules that implement the canonical mission lifecycle and governance logic.
These modules &lt;strong&gt;MUST NOT&lt;/strong&gt; import from the INTEGRATION set.&lt;/p&gt;






























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Package&lt;/th&gt;&lt;th&gt;Root path&lt;/th&gt;&lt;th&gt;Description&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;core&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Mission creation, contract gate, dependency graph&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/status/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;State machine, event log, adapter registry&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;readiness&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/readiness/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Readiness checks and coordinator&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;invocation&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/invocation/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Op lifecycle propagation and registry&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;integration-set&quot;&gt;INTEGRATION Set&lt;/h3&gt;
&lt;p&gt;Modules that connect spec-kitty to external systems.
These modules &lt;strong&gt;MAY&lt;/strong&gt; import CORE facades (allowed direction).&lt;/p&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Package&lt;/th&gt;&lt;th&gt;Root path&lt;/th&gt;&lt;th&gt;Description&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;orchestrator_api&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/orchestrator_api/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Orchestrator HTTP client&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;sync&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/sync/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Real-time SaaS sync, WebSocket, OfflineQueue&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;tracker&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/tracker/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Issue-tracker origin binding&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;saas&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/saas/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;SaaS-specific feature flags and rollout&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;saas_client&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/saas_client/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;SaaS REST client&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;out-of-scope-modules-c-004&quot;&gt;Out-of-Scope Modules (C-004)&lt;/h3&gt;
&lt;p&gt;The following modules are &lt;strong&gt;not classified&lt;/strong&gt; in either set for this mission.
Their import patterns are &lt;strong&gt;not checked&lt;/strong&gt; by &lt;code dir=&quot;auto&quot;&gt;test_integration_boundary.py&lt;/code&gt;.&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Package&lt;/th&gt;&lt;th&gt;Root path&lt;/th&gt;&lt;th&gt;Reason for exclusion&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;coordination&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/coordination/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Deferred (C-004)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;lanes&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/lanes/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Deferred (C-004)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;runtime&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/runtime/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;src/runtime/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Deferred (C-004)&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;hr&gt;
&lt;h2 id=&quot;the-one-directional-rule-and-its-rationale&quot;&gt;The One-Directional Rule and Its Rationale&lt;/h2&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;CORE must NOT import INTEGRATION.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;INTEGRATION may import CORE facades.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Rationale:&lt;/strong&gt; CORE modules implement the canonical mission lifecycle and governance
logic; coupling them to outbound adapters would make the governance engine depend on the
availability and startup ordering of external connectors. Inversion (CORE fires events;
INTEGRATION registers handlers) keeps the governance path fast, testable, and independent
of connectivity.&lt;/p&gt;
&lt;p&gt;The adapter/observer registry pattern is the sanctioned mechanism for this inversion:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Core → Sync/Tracker/SaaS fan-out: register an observer with &lt;code dir=&quot;auto&quot;&gt;status/adapters.py&lt;/code&gt; or
&lt;code dir=&quot;auto&quot;&gt;core/adapters.py&lt;/code&gt;; call the fire function.&lt;/li&gt;
&lt;li&gt;Invocation → Sync: register via &lt;code dir=&quot;auto&quot;&gt;invocation/adapters.py&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;enforcement&quot;&gt;Enforcement&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_integration_boundary.py&lt;/code&gt; enforces this rule on every CI run.
The test:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Uses stdlib &lt;code dir=&quot;auto&quot;&gt;ast.walk&lt;/code&gt; to scan &lt;strong&gt;all&lt;/strong&gt; import forms — module-level,
&lt;code dir=&quot;auto&quot;&gt;if TYPE_CHECKING:&lt;/code&gt; blocks, and lazy function-body imports.&lt;/li&gt;
&lt;li&gt;Scans every &lt;code dir=&quot;auto&quot;&gt;.py&lt;/code&gt; file in all four CORE-set directories by consuming the
session-scoped &lt;code dir=&quot;auto&quot;&gt;src_source_tree&lt;/code&gt; fixture (&lt;code dir=&quot;auto&quot;&gt;tests/architectural/conftest.py&lt;/code&gt;) —
the shared, read-once/parse-once source cache the other boundary gates use —
filtered to the CORE set, rather than independently re-walking &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Fails with a message identifying: the violating source file, the offending import
path, and the corrective action (NFR-002: at least 3 diagnostic fields).&lt;/li&gt;
&lt;li&gt;Carries &lt;code dir=&quot;auto&quot;&gt;pytest.mark.architectural&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Includes a path-existence sanity check for every CORE-set directory so that a
directory rename causes a loud failure rather than a vacuous pass (C-008).&lt;/li&gt;
&lt;li&gt;Includes a sanity sub-test that drives a &lt;strong&gt;real on-disk&lt;/strong&gt; non-allowlisted
violation through the &lt;em&gt;same&lt;/em&gt; enforcement scanner the gate uses, proving the
allowlist cannot be bypassed silently (and a regression in the enforcement loop
itself — not just a re-implemented copy — would be caught).&lt;/li&gt;
&lt;li&gt;Pins &lt;code dir=&quot;auto&quot;&gt;len(ALLOWLIST) == 0&lt;/code&gt; with a count-ratchet so the exemption set can never
silently grow. Issue #2252 has landed: the last exemption
(&lt;code dir=&quot;auto&quot;&gt;readiness/coordinator.py&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;specify_cli.saas.rollout&lt;/code&gt;) was resolved when
&lt;code dir=&quot;auto&quot;&gt;is_saas_sync_enabled&lt;/code&gt; moved to &lt;code dir=&quot;auto&quot;&gt;core/saas_sync_config.py&lt;/code&gt;, so the ratchet now
holds the allowlist at zero.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Any new &lt;code dir=&quot;auto&quot;&gt;.py&lt;/code&gt; file added to a CORE-set directory is automatically covered without
any test change (FR-001, C-008).&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;relationship-to-2173-infralogic-separation-via-ports&quot;&gt;Relationship to #2173 (infra/logic separation via ports)&lt;/h2&gt;
&lt;p&gt;This boundary and the infra/logic-separation work in #2173 (tracked under #1619)
operate on &lt;strong&gt;orthogonal axes&lt;/strong&gt; and land independently:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;This ADR governs package import &lt;em&gt;direction&lt;/em&gt;&lt;/strong&gt; — CORE must not import the
INTEGRATION set, enforced by &lt;code dir=&quot;auto&quot;&gt;test_integration_boundary.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;#2173 injects infra &lt;em&gt;ports&lt;/em&gt; into pure core&lt;/strong&gt; (FS / Clock / Git / Resolver) —
a dependency-&lt;em&gt;shape&lt;/em&gt; concern, not a cross-package import-direction concern.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The two reinforce each other: the &lt;code dir=&quot;auto&quot;&gt;core/adapters.py&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;invocation/adapters.py&lt;/code&gt;
registries introduced here reuse the established &lt;code dir=&quot;auto&quot;&gt;status/adapters.py&lt;/code&gt; seam, and
#2173 explicitly &lt;em&gt;drops&lt;/em&gt; its SaaS port (“already seamed via &lt;code dir=&quot;auto&quot;&gt;fire_saas_fanout&lt;/code&gt;”),
i.e. it leans on the very inversion seam this boundary hardens. Neither blocks the
other; there is no file-level collision.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;allowlist-exemptions&quot;&gt;Allowlist Exemptions&lt;/h2&gt;
&lt;p&gt;Each entry permits one specific &lt;code dir=&quot;auto&quot;&gt;(source_module, imported_module)&lt;/code&gt; pair with a written
rationale. &lt;strong&gt;The allowlist is now empty.&lt;/strong&gt; Exactly one exemption existed when this mission
merged (&lt;code dir=&quot;auto&quot;&gt;readiness/coordinator.py&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;specify_cli.saas.rollout&lt;/code&gt;); it was resolved by
&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2252&quot;&gt;#2252&lt;/a&gt;, which relocated
&lt;code dir=&quot;auto&quot;&gt;is_saas_sync_enabled&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;core/saas_sync_config.py&lt;/code&gt;. The &lt;code dir=&quot;auto&quot;&gt;len(ALLOWLIST) == 0&lt;/code&gt;
count-ratchet in the enforcement test now holds the exemption set at zero.&lt;/p&gt;

















&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Source&lt;/th&gt;&lt;th&gt;Imported&lt;/th&gt;&lt;th&gt;Rationale&lt;/th&gt;&lt;th&gt;Planned resolution&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;em&gt;(none — the single historical exemption was resolved by #2252)&lt;/em&gt;&lt;/td&gt;&lt;td&gt;&lt;/td&gt;&lt;td&gt;&lt;/td&gt;&lt;td&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;Adding new exemptions:&lt;/strong&gt; Do NOT add an allowlist entry unless the crossing is a
deliberate, time-bounded exception with a written follow-up plan. Edit
&lt;code dir=&quot;auto&quot;&gt;test_integration_boundary.py&lt;/code&gt; directly with a written rationale. Broadening an
existing entry is not permitted.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;adapter-registries-introduced-by-this-mission&quot;&gt;Adapter Registries Introduced by This Mission&lt;/h2&gt;
&lt;p&gt;Three adapter registries were introduced or used to eliminate the leaks:&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Registry&lt;/th&gt;&lt;th&gt;Module&lt;/th&gt;&lt;th&gt;Registration site&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Pending-origin consumer&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;core/adapters.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;tracker/__init__.py&lt;/code&gt; startup hook&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Sync-routing resolver&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;invocation/adapters.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;sync/__init__.py&lt;/code&gt; startup hook&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;SaaS-client factory&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;invocation/adapters.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;sync/__init__.py&lt;/code&gt; startup hook&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;All registries follow the idempotent, non-raising contract established by
&lt;code dir=&quot;auto&quot;&gt;status/adapters.py&lt;/code&gt;.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;deferred-scope&quot;&gt;Deferred Scope&lt;/h2&gt;
&lt;p&gt;The following items are &lt;strong&gt;out of scope&lt;/strong&gt; for this mission and are explicitly deferred:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Physical extraction to &lt;code dir=&quot;auto&quot;&gt;src/orchestrator/&lt;/code&gt;&lt;/strong&gt; — deferred per ADR
&lt;code dir=&quot;auto&quot;&gt;docs/adr/3.x/2026-05-11-1-defer-391-structural-extraction-from-3-2-x.md&lt;/code&gt; and the
ownership manifest &lt;code dir=&quot;auto&quot;&gt;docs/architecture/05_ownership_manifest.yaml&lt;/code&gt;. The boundary is
enforced in-place first; the physical move to a separate top-level package is a
follow-up mission.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Bidirectional enforcement&lt;/strong&gt; (preventing INTEGRATION from importing CORE in ways that
violate contract) — out of scope for this mission (C-003); deferred to a follow-up.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;coordination/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;lanes/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;runtime/&lt;/code&gt;&lt;/strong&gt; — not classified in either set; their import
patterns are not checked by &lt;code dir=&quot;auto&quot;&gt;test_integration_boundary.py&lt;/code&gt; (C-004). Their boundary
classification is deferred.&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;CORE governance logic is independently testable without importing external connectors.&lt;/li&gt;
&lt;li&gt;A new &lt;code dir=&quot;auto&quot;&gt;.py&lt;/code&gt; file in any CORE-set directory is automatically covered by the enforcement
test — no test change required.&lt;/li&gt;
&lt;li&gt;The adapter-registry pattern is consistent across the codebase
(&lt;code dir=&quot;auto&quot;&gt;status/adapters.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;core/adapters.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;invocation/adapters.py&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Physical extraction to &lt;code dir=&quot;auto&quot;&gt;src/orchestrator/&lt;/code&gt; can proceed safely on top of this enforced
boundary.&lt;/li&gt;
&lt;li&gt;The allowlist is empty: #2252 relocated &lt;code dir=&quot;auto&quot;&gt;is_saas_sync_enabled&lt;/code&gt; to
&lt;code dir=&quot;auto&quot;&gt;core/saas_sync_config.py&lt;/code&gt;, so CORE no longer imports the INTEGRATION set even for the
feature-flag read. The enforcement ratchet is pinned at &lt;code dir=&quot;auto&quot;&gt;len(ALLOWLIST) == 0&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Shim-depth trade-off (intentional):&lt;/strong&gt; the &lt;code dir=&quot;auto&quot;&gt;tracker&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;sync&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;feature_flags&lt;/code&gt; modules
re-export through &lt;code dir=&quot;auto&quot;&gt;saas/rollout.py&lt;/code&gt; (retained as a re-export shim) rather than pointing
directly at &lt;code dir=&quot;auto&quot;&gt;core/saas_sync_config.py&lt;/code&gt;. This keeps a two-hop shim chain
(&lt;code dir=&quot;auto&quot;&gt;feature_flags&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;saas/rollout.py&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;core/saas_sync_config.py&lt;/code&gt;) but avoids churning
the NFR-001 function-identity tests that assert &lt;code dir=&quot;auto&quot;&gt;is&lt;/code&gt; identity across every shim.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;em&gt;(Resolved)&lt;/em&gt; The historical allowlist entry (&lt;code dir=&quot;auto&quot;&gt;readiness/coordinator.py&lt;/code&gt; →
&lt;code dir=&quot;auto&quot;&gt;specify_cli.saas.rollout&lt;/code&gt;) that once left a structural coupling in CORE was
closed by #2252; the allowlist is now empty. See the Positive section for the
resolved state and the intentional shim-depth trade-off.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;coordination/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;lanes/&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;runtime/&lt;/code&gt; remain unclassified; their import patterns
accumulate unchecked until a follow-up mission addresses C-004.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;This decision is correct when:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;All three original leaks are fixed (WP01–WP03 merged and approved).&lt;/li&gt;
&lt;li&gt;✅ &lt;code dir=&quot;auto&quot;&gt;pytest tests/architectural/test_integration_boundary.py&lt;/code&gt; passes with zero
allowlist entries.&lt;/li&gt;
&lt;li&gt;✅ Follow-up issue &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2252&quot;&gt;#2252&lt;/a&gt;
relocated &lt;code dir=&quot;auto&quot;&gt;is_saas_sync_enabled&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;core/saas_sync_config.py&lt;/code&gt; and removed the last
allowlist entry.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Mission spec: &lt;a href=&quot;../../../kitty-specs/integration-boundary-01KW0PBE/spec.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/integration-boundary-01KW0PBE/spec.md&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Data model (set definitions and allowlist): &lt;a href=&quot;../../../kitty-specs/integration-boundary-01KW0PBE/data-model.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/integration-boundary-01KW0PBE/data-model.md&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Contract: &lt;a href=&quot;../../../kitty-specs/integration-boundary-01KW0PBE/contracts/integration-boundary-rule.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;kitty-specs/integration-boundary-01KW0PBE/contracts/integration-boundary-rule.md&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Enforcement test: &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_integration_boundary.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Physical extraction deferral: &lt;a href=&quot;/adr/3.x/2026-05-11-1-defer-391-structural-extraction-from-3-2-x/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/adr/3.x/2026-05-11-1-defer-391-structural-extraction-from-3-2-x.md&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Current package inventory: &lt;a href=&quot;../../../pyproject.toml&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt;&lt;/a&gt; &lt;code dir=&quot;auto&quot;&gt;[tool.hatch.build.targets.wheel].packages&lt;/code&gt;, enforced by &lt;a href=&quot;../../../tests/architectural/test_pyproject_shape.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;test_pyproject_shape.py&lt;/code&gt;&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Current import direction: the &lt;code dir=&quot;auto&quot;&gt;landscape&lt;/code&gt; fixture in &lt;a href=&quot;../../../tests/architectural/conftest.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;conftest.py&lt;/code&gt;&lt;/a&gt; and &lt;a href=&quot;../../../tests/architectural/test_layer_rules.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;test_layer_rules.py&lt;/code&gt;&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Historical ownership narrative: &lt;a href=&quot;/architecture/05_ownership_map/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;05_ownership_map.md&lt;/code&gt;&lt;/a&gt;. Its companion manifest was deleted; the map is narrative only and does not define current package inventory or import direction.&lt;/li&gt;
&lt;li&gt;Shared-package-boundary precedent: &lt;a href=&quot;/adr/3.x/2026-04-25-1-shared-package-boundary/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;architecture/3.x/adr/2026-04-25-1-shared-package-boundary.md&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-10-22-the-seam-this-adr-cites-as-fire_saas_fanout-is-renamed-6607&quot;&gt;Amendment 2026-10-22: the seam this ADR cites as &lt;code dir=&quot;auto&quot;&gt;fire_saas_fanout&lt;/code&gt; is renamed (#6607)&lt;/h2&gt;
&lt;p&gt;The “Relationship to #2173” section above names &lt;code dir=&quot;auto&quot;&gt;fire_saas_fanout&lt;/code&gt; as the established inversion seam. That function is now &lt;code dir=&quot;auto&quot;&gt;fire_status_fanout&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;status/adapters.py&lt;/code&gt;, and the lifecycle counterpart &lt;code dir=&quot;auto&quot;&gt;fire_lifecycle_saas_fanout&lt;/code&gt; is &lt;code dir=&quot;auto&quot;&gt;fire_lifecycle_fanout&lt;/code&gt;, with no alias. The #2173 quotation is historical and is left as written. The decision in this ADR is unchanged.&lt;/p&gt;</content>
</entry>
