<?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-08-09-1-project-sync-store-boundary/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-08-09-1-project-sync-store-boundary/</id>
  <title>ADR: One Project UUID Owns One Sync Store and One Consent Decision</title>
  <updated>2026-08-09T00: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-08-09-1-project-sync-store-boundary/"/>
  <summary>Hosted-sync state is isolated by project UUID behind one ProjectSyncStore unit of work; ambient checkout, identity, target, or environment cannot select another project.</summary>
  <content type="html">&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Superseded (2026-09-06)&lt;/strong&gt; by
&lt;a href=&quot;/adr/3.x/2026-09-06-1-convergence-retirement-and-client-repo-inversion/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-09-06-1-convergence-retirement-and-client-repo-inversion.md&lt;/code&gt;&lt;/a&gt;.
The &lt;code dir=&quot;auto&quot;&gt;ProjectSyncStore&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;sync/project_store.py&lt;/code&gt; boundary this ADR governs was deleted with the sync
transport by the Convergence (#3881 / #3824). Retained as historical record.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;The hosted-sync implementation currently spreads one project’s journal, delivery
ledger, delivery targets, body queue, legacy outbox, and consent index across
several SQLite files under a machine-global runtime root. Components open those
files directly and commit independently. The arrangement makes a correspondence
between rows rather than an ownership boundary between projects.&lt;/p&gt;
&lt;p&gt;That correspondence failed during the #3030 confidentiality incident. A filter
defect selected records belonging to five never-opted-in projects alongside the
intended project’s records. On 2026-07-27, &lt;strong&gt;1,322&lt;/strong&gt; events from those projects
were delivered with 7,811 events from the consenting project. The server, login,
team, target, and transport were valid. The authorization question was answered
about one project while the shared store supplied another project’s data.&lt;/p&gt;
&lt;p&gt;This is not primarily a slug-collision defect. A path can move, a slug can be
reused, a login can cover many projects, a target can serve a whole team, and an
environment variable is machine-wide. None is a durable project identity. The
only isolation key for hosted-sync state is the canonical project UUID.&lt;/p&gt;
&lt;p&gt;The current direct-open/direct-commit architecture also prevents one action from
being atomic. A result can be recorded in the ledger while the journal or body
queue update fails, or a target can change between selection and transmit. Tests
can validate each file independently and still miss an incoherent cross-file
attempt.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Confidentiality must not depend on every reader remembering a project filter.&lt;/li&gt;
&lt;li&gt;A grant must authorize exactly the UUID whose data is selected and sent.&lt;/li&gt;
&lt;li&gt;Selection, target resolution, final eligibility, and result recording need one
transaction owner and one coherent project context.&lt;/li&gt;
&lt;li&gt;Existing #3030 protections remain security boundaries, not migration debris.&lt;/li&gt;
&lt;li&gt;Migration must preserve recoverability without sustaining two live truths.&lt;/li&gt;
&lt;li&gt;Refused historical data must remain locally inspectable and explicitly
purgeable, without becoming eligible merely because it exists.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;h3 id=&quot;1-one-uuid-owns-one-syncdb&quot;&gt;1. One UUID owns one &lt;code dir=&quot;auto&quot;&gt;sync.db&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;Each canonical project UUID owns exactly one hosted-sync SQLite database:&lt;/p&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;text&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;&amp;#x3C;runtime-root&gt;/projects/&amp;#x3C;lowercase-hyphenated-uuid&gt;/sync/sync.db&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;The database has a sibling &lt;code dir=&quot;auto&quot;&gt;egress.lock&lt;/code&gt; at
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;runtime-root&gt;/projects/&amp;#x3C;lowercase-hyphenated-uuid&gt;/sync/egress.lock&lt;/code&gt;. The lock
serializes the final transport/cutover boundary for that same UUID; it is not a
machine-global substitute for project ownership.&lt;/p&gt;
&lt;p&gt;The database holds that project’s journal, delivery results, targets, body-upload
work, refusal/parking state, consent decision, and migration provenance. A project
slug may be stored as descriptive metadata but never participates in the path or
the key. Two checkouts with the same slug and distinct UUIDs necessarily open
different files. Two checkouts that truthfully carry the same UUID necessarily
address the same project store.&lt;/p&gt;
&lt;h3 id=&quot;2-projectsyncstore-is-the-unit-of-work-boundary&quot;&gt;2. &lt;code dir=&quot;auto&quot;&gt;ProjectSyncStore&lt;/code&gt; is the unit-of-work boundary&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;ProjectSyncStore.unit_of_work()&lt;/code&gt; owns every live connection to a project’s
&lt;code dir=&quot;auto&quot;&gt;sync.db&lt;/code&gt;, the outer transaction, schema/version checks, and repository objects
used inside that transaction. Journal, ledger, target, body-queue, and outbox
components receive a store-owned connection or cursor. They do not open the live
database and do not commit it.&lt;/p&gt;
&lt;p&gt;One project-store action owns a hosted-sync attempt from request start through
result write. The attempt carries one immutable project UUID and a target snapshot.
It cannot pair project A’s journal with project B’s target, ledger, consent record,
or body queue. Nested components may use savepoints where needed, but cannot end
the outer transaction.&lt;/p&gt;
&lt;p&gt;Direct SQLite access outside &lt;code dir=&quot;auto&quot;&gt;ProjectSyncStore&lt;/code&gt; is permitted only in the migration
reader, against a legacy snapshot opened read-only/immutable. That reader cannot
be used by live dispatch or write a legacy file.&lt;/p&gt;
&lt;h3 id=&quot;3-consent-is-a-project-store-decision-not-ambient-state&quot;&gt;3. Consent is a project-store decision, not ambient state&lt;/h3&gt;
&lt;p&gt;There is one authoritative consent decision for each project UUID, and the
explicit project-store action is its only grant writer. Project-local records and
the pre-existing UUID index are migration inputs until cutover; checkout defaults,
repository defaults, backfill inference, login state, host, target, project
discovery, aliases, the existence of rows, and a truthy environment variable are
not grants.&lt;/p&gt;
&lt;p&gt;Legacy refusal records remain distinct from grants. Migration or reconciliation
may preserve or strengthen a refusal, but may not turn absence, unreadability, or
an inferred legacy default into permission. Machine-global arming can disable
transport globally; it cannot grant a project permission.&lt;/p&gt;
&lt;h3 id=&quot;4-the-3030-egress-boundary-is-preserved-and-strengthened&quot;&gt;4. The #3030 egress boundary is preserved and strengthened&lt;/h3&gt;
&lt;p&gt;Per-project storage removes the cross-project selection class, but it does not
replace defense in depth. All of these #3030 properties remain required:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;consent-bearing batches carry the decision made for their own project UUID;&lt;/li&gt;
&lt;li&gt;SQL selection includes an explicit UUID predicate even inside a per-project
file, so schema or path mistakes fail closed;&lt;/li&gt;
&lt;li&gt;every HTTP, WebSocket, daemon, foreground, reconnect, history-import, tracker,
and generic SaaS sender performs a &lt;strong&gt;final transmit recheck&lt;/strong&gt; against the
canonical attempt context immediately before bytes leave the process;&lt;/li&gt;
&lt;li&gt;a refusal is terminal for that attempt and is parked with a structured reason,
rather than retried as a transient transport failure;&lt;/li&gt;
&lt;li&gt;retained/refused records have explicit project-scoped and all-project purge
operations with differential evidence.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Authentication proves who the operator is. Target resolution proves where a
request would go. Neither substitutes for consent by the project that owns the
payload.&lt;/p&gt;
&lt;h3 id=&quot;5-shared-live-stores-are-retired-by-copy-verify-and-cutover&quot;&gt;5. Shared live stores are retired by copy, verify, and cutover&lt;/h3&gt;
&lt;p&gt;The migration is a three-stage operation:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Copy:&lt;/strong&gt; open each legacy source as a read-only snapshot and copy attributable
records into the destination UUID store. Unattributable or conflicting records
are quarantined, never assigned by slug/path guesswork.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Verify:&lt;/strong&gt; compare exact identifiers, counts, hashes/bytes where defined,
consent/refusal semantics, delivery state, and cross-project differentials.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cutover:&lt;/strong&gt; atomically publish the project-store manifest/marker only after all
required verification passes. Live code then reads and writes only the UUID
store.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;There is &lt;strong&gt;no dual-read&lt;/strong&gt; and no dual-write interval. A run uses either the
verified project store or the pre-cutover legacy snapshot; it never merges answers
from both. Failure before cutover leaves the legacy snapshot authoritative and the
partial destination disposable/restartable. Failure after cutover is recovered
from the project store and migration audit, never by silently consulting legacy
state.&lt;/p&gt;
&lt;p&gt;Legacy live stores are retired after verification and an explicit retention
window. Retirement is not deletion of evidence: migration provenance and operator
chosen backups make the operation auditable and recoverable.&lt;/p&gt;
&lt;h3 id=&quot;6-historical-inspection-is-an-explicit-capability&quot;&gt;6. Historical inspection is an explicit capability&lt;/h3&gt;
&lt;p&gt;Operators may need to inspect, export, reconcile, or purge historical local data.
Those actions are separate read-only or explicitly destructive capabilities; the
mere ability to inspect a legacy snapshot never makes it a live dispatch source.
This keeps forensic history available without reopening the shared-store boundary.&lt;/p&gt;
&lt;h2 id=&quot;supersession-and-relationship-to-3030&quot;&gt;Supersession and Relationship to #3030&lt;/h2&gt;
&lt;p&gt;This ADR &lt;strong&gt;supersedes #3030’s final consent-gated capture decision&lt;/strong&gt; and its
shared-live-store assumption, while preserving its egress policy. #3030’s final
FR-002, amended NFR-005, and C-006 required an unconsented project never to reach
the shared journal. This mission deliberately changes that collection decision:
local capture may occur without hosted consent only inside the owning UUID’s
store, where capture sequence and epoch assignment are atomic. Pre-consent rows
remain in sealed epochs and cannot become ordinary delivery candidates after a
later opt-in; only an explicit preview/confirm history capability can select
them. Shared journals and outboxes cease being live capture destinations.&lt;/p&gt;
&lt;p&gt;The egress-consent ADR remains authoritative for the sender-side question. This
ADR makes the at-rest and transaction boundary match it: the record, consent
decision, target, and result all name the same UUID.&lt;/p&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;A missing filter cannot expose another project’s records because that project
has no rows in the opened database.&lt;/li&gt;
&lt;li&gt;Ownership is deterministic under checkout relocation, duplicate slugs, multiple
logins, team-wide targets, and different environment configurations.&lt;/li&gt;
&lt;li&gt;One outer transaction makes delivery/result state coherent and testable.&lt;/li&gt;
&lt;li&gt;The connection, commit, consent-writer, sender, and local-writer censuses create
ratchets: growth fails while migration-driven shrinkage is visible.&lt;/li&gt;
&lt;li&gt;Historical inspection remains available as a named capability rather than an
accidental live fallback.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative-and-operational-cost&quot;&gt;Negative and operational cost&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Existing machines need a potentially long-running, restartable migration with
disk-space preflight and verification evidence.&lt;/li&gt;
&lt;li&gt;Components that currently own SQLite lifecycle or commit behavior must accept a
store-owned unit of work.&lt;/li&gt;
&lt;li&gt;Multi-project status/reporting must enumerate project stores rather than query
one aggregate database.&lt;/li&gt;
&lt;li&gt;Incident response and support tooling must state which project UUID store was
inspected; a slug-only report is insufficient.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;risks-retained-deliberately&quot;&gt;Risks retained deliberately&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;A caller can still construct the wrong UUID context. The named sender matrix,
coherent-attempt type, UUID SQL predicates, and final gate are independent
checks against that failure.&lt;/li&gt;
&lt;li&gt;Filesystem permissions and local-disk confidentiality remain operating-system
concerns. Per-project databases reduce correspondence risk; they do not encrypt
local state by themselves.&lt;/li&gt;
&lt;li&gt;An explicit all-project historical operation is necessarily powerful and must
remain visibly distinct from normal project-scoped operation.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;rejected-alternatives&quot;&gt;Rejected Alternatives&lt;/h2&gt;
&lt;h3 id=&quot;keep-shared-databases-and-add-more-uuid-predicates&quot;&gt;Keep shared databases and add more UUID predicates&lt;/h3&gt;
&lt;p&gt;Rejected because one missed or widened predicate recreates the incident, and
independent commits still permit incoherent result state. UUID predicates remain
as defense in depth, not the primary isolation boundary.&lt;/p&gt;
&lt;h3 id=&quot;partition-by-slug-repository-path-checkout-path-login-team-or-target&quot;&gt;Partition by slug, repository path, checkout path, login, team, or target&lt;/h3&gt;
&lt;p&gt;Rejected because each is mutable, reusable, many-to-many, or ambient. None is the
identity of the project whose record is being sent.&lt;/p&gt;
&lt;h3 id=&quot;make-the-machine-global-environment-flag-a-grant&quot;&gt;Make the machine-global environment flag a grant&lt;/h3&gt;
&lt;p&gt;Rejected because it cannot distinguish projects. It may arm or disable the
feature globally, but cannot express per-project permission.&lt;/p&gt;
&lt;h3 id=&quot;use-a-shared-database-with-one-connection-manager&quot;&gt;Use a shared database with one connection manager&lt;/h3&gt;
&lt;p&gt;Rejected because connection ownership would improve atomicity while retaining the
cross-project row pool whose filter failure caused the incident.&lt;/p&gt;
&lt;h3 id=&quot;dual-read-old-and-new-stores-during-a-compatibility-window&quot;&gt;Dual-read old and new stores during a compatibility window&lt;/h3&gt;
&lt;p&gt;Rejected because two authorities make absence/refusal ambiguous, hide incomplete
migrations, and allow a legacy record to re-enter the live path. Compatibility is
provided by deterministic copy/verify/cutover and an explicit read-only historical
capability instead.&lt;/p&gt;
&lt;h2 id=&quot;scope-exclusions&quot;&gt;Scope Exclusions&lt;/h2&gt;
&lt;p&gt;This decision does not combine unrelated remediation merely because it touches a
nearby transport:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;#3108/PR #3135 remains separate work.&lt;/li&gt;
&lt;li&gt;The historical &lt;strong&gt;1,322 SaaS events&lt;/strong&gt; incident classification and downstream
handling remain &lt;strong&gt;Human-in-Charge (HiC)&lt;/strong&gt; controlled. This ADR supplies local isolation
and evidence mechanics; it does not decide notification, deletion, or any
server-side legal/operational action.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;No production call site changes are made by the WP01 evidence package. Later work
packages own the store implementation, schema, migration, component rewiring,
sender conversion, cutover gate, and operator documentation.&lt;/p&gt;
&lt;h2 id=&quot;verification-and-enforcement&quot;&gt;Verification and Enforcement&lt;/h2&gt;
&lt;p&gt;WP01 establishes executable inventories rather than line-number allowlists:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_project_store_boundary.py&lt;/code&gt; records qualified SQLite
open, commit, and transaction-context sites, classifies legacy read-only and
live debt, rejects growth, and exposes the final strict predicate.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_sync_writer_census.py&lt;/code&gt; records grant writers and every
legacy grant input while proving ambient operator state and a truthy environment
are not permission.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_egress_consent_boundary.py&lt;/code&gt; names request-start and
result-write sites for every project-data sender, plus the current local writer
inventory that later WPs must route through the store layout.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/sync/test_project_consent_incident_baseline.py&lt;/code&gt; provides same-slug A/B
fixtures, store-open and exact-byte spies, differential counters,
cross-process barriers, coherent-context assertions, and synthetic mutants for
the incident’s four principal regression shapes.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The census baseline may shrink without being rewritten. New direct store owners,
grant writers, unnamed senders, or layout writers are failures. WP11 activates the
strict final-state predicate only after all migration work packages remove the
recorded debt.&lt;/p&gt;</content>
</entry>
