<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/2.x/2026-02-27-2-host-owned-tracker-persistence-boundary/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-02-27-2-host-owned-tracker-persistence-boundary/</id>
  <title>Host-Owned Tracker Persistence Boundary</title>
  <updated>2026-02-27T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/2.x/2026-02-27-2-host-owned-tracker-persistence-boundary/"/>
  <summary>Keeps SQLite caches and checkpoints in the host CLI and leaves the tracker core protocol-only, matching how the sync queue and status store are already owned.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Tracker integration requires local cache and checkpoint persistence. One proposal added durable SQLite stores directly to &lt;code dir=&quot;auto&quot;&gt;spec-kitty-tracker&lt;/code&gt; core. That approach conflicts with existing SpecKitty architecture where persistence is host-owned and context-specific.&lt;/p&gt;
&lt;p&gt;Current patterns in CLI:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;SQLite queue in &lt;code dir=&quot;auto&quot;&gt;sync/queue.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;JSONL state/event store in &lt;code dir=&quot;auto&quot;&gt;status/store.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Credential storage + locking in &lt;code dir=&quot;auto&quot;&gt;sync/auth.py&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Adding core persistence in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-tracker&lt;/code&gt; would blur boundaries and make connector core responsible for deployment-specific storage concerns.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Keep &lt;code dir=&quot;auto&quot;&gt;spec-kitty-tracker&lt;/code&gt; reusable across CLI and SaaS hosts.&lt;/li&gt;
&lt;li&gt;Preserve existing host-owned persistence architecture.&lt;/li&gt;
&lt;li&gt;Avoid premature storage coupling in connector core.&lt;/li&gt;
&lt;li&gt;Keep connector testability simple with in-memory stores.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Add &lt;code dir=&quot;auto&quot;&gt;SqliteIssueStore&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;SqliteCheckpointStore&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;spec-kitty-tracker&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Host-owned durable store implementations (&lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; CLI and future SaaS adapters), with protocol interfaces in core (chosen).&lt;/li&gt;
&lt;li&gt;No durable local store in v1.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; host-owned persistence with protocol-only core.&lt;/p&gt;
&lt;h3 id=&quot;required-behavior&quot;&gt;Required Behavior&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-tracker&lt;/code&gt; defines protocols/contracts and connectors.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-tracker&lt;/code&gt; may include in-memory testing stores only.&lt;/li&gt;
&lt;li&gt;Durable SQLite tracker store/checkpoint implementations live in &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; CLI.&lt;/li&gt;
&lt;li&gt;SaaS may implement separate durable projections without changing core contracts.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Clear architectural boundary and ownership.&lt;/li&gt;
&lt;li&gt;Reusable connector core with minimal runtime assumptions.&lt;/li&gt;
&lt;li&gt;Storage technology remains host-selectable.&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Host implementations duplicate some store wiring logic.&lt;/li&gt;
&lt;li&gt;Shared migration helpers are deferred.&lt;/li&gt;
&lt;/ol&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ol&gt;
&lt;li&gt;Core docs must explicitly state persistence responsibility.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;This decision is validated when:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;No durable store classes are present in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-tracker&lt;/code&gt; core.&lt;/li&gt;
&lt;li&gt;CLI durable tracker cache/checkpoint persistence exists in &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Tracker connector tests run using protocol/in-memory store patterns.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-1-durable-sqlite-in-core&quot;&gt;Option 1: Durable SQLite in core&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Single implementation point.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Couples connector core to storage/runtime assumptions.&lt;/li&gt;
&lt;li&gt;Conflicts with established host-owned pattern.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;option-2-host-owned-persistence-chosen&quot;&gt;Option 2: Host-owned persistence (Chosen)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Architecture consistency with existing SpecKitty patterns.&lt;/li&gt;
&lt;li&gt;Better portability across hosts.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;More host-side implementation effort.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;option-3-no-durable-store&quot;&gt;Option 3: No durable store&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Simplifies short-term implementation.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Fails operational requirements for checkpointed sync.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Existing host persistence references:
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/sync/queue.py&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/status/store.py&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/sync/auth.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;CLI tracker store implementation:
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/tracker/store.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Core architecture docs:
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;spec-kitty-tracker-repo&gt;/docs/ARCHITECTURE.md&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;</content>
</entry>
