Repository navigation
docs: design crash-safe ownership checkpointing - #79
Merged
Merged
Conversation
Resolves the spec §9.1 persistence-handoff blocker at the design level: proves the four-table model cannot carry exact crash-safe accumulation, and specifies the minimal amendment — one EPHEMERAL pseudonymous work table, a single-transaction CAS page checkpoint, per-scope two-pass identity resolution, and a pinned-revision walk (pending a B0.5 non-persisting spike). Records the proposed spec amendment in §27. Docs only — no code, schema, or config changes. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…dentity Revision 2: move all durable contributor writes into the single scope-COMMIT transaction (no identity rows during page-by-page resolve), split ephemeral state into accumulation counters plus a represented-key-only identity staging relation, remove the unimplementable resolve-drift fold (a null author.user carries no node id to map back), reclassify work_key as a linkable pseudonymous identifier, and make TTL/cursor bounds concrete. Docs only. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
…semantics Revision 3: is_bot is frozen pass-1 attribution — resolve verifies rather than re-derives it and a classification flip fails the scope closed; the staging relation drops is_bot entirely. Adds the explicit pre-flip abandon transaction (versioned snapshot/ephemeral deletes plus anti-join pruning of contributor rows unreferenced in ANY version, preserving active-version references). first_seen_at/last_seen_at now accumulate only across finalized scopes where the contributor was individually represented — recorded in the spec so the field names don't overclaim. Docs only. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Revision 3: ownership_contributors is shared across calculation versions but the dashboard RPCs version-filter only snapshots — mid-build mutation of shared contributor metadata would leak into active-version responses and could not be restored on abort. Identity/metadata staging moves to a build-grain ephemeral relation (ownership_contributor_build_work); retained rows are never mutated while a building version is incomplete; promotion applies staged metadata and flips active_version in one transaction; abort deletes building artifacts and anti-join prunes unreferenced contributor rows. is_bot is frozen once per build — drift between passes or across scopes fails closed. Docs only. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Revision 4: build-level contributor staging accumulates across already-finalized scopes, so losing any required ephemeral state invalidates the entire building version — piecemeal resume is impossible. Adds the canonical own_abandon_build operation reused by the stale sweep, restore reconciliation, operator abort, and invalid-state recovery; defines build-state validity invariants; forbids overlapping building versions; keeps both relations EPHEMERAL (loss = discarded build, never active data). Docs only. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
ownership_scopes is shared across calculation versions and the deployed dash_ownership_scopes enumerates base scope rows unversioned, so a building version could leak new scopes or mutate active exclusion state. Design adds retained ownership_scope_versions (CORE), moves excluded/exclusion_reason to per-version membership, routes abandon/GC and the scopes RPC through membership, and keeps base scope identity immutable. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
A snapshot must be impossible without version membership: prospective 013 adds a composite (scope, repo, tenant, version) FK from ownership_snapshots to ownership_scope_versions with NO ACTION/RESTRICT semantics so cleanup can never cascade-destroy snapshots. Also separates the hard 500-directory enumeration cap (overflow paths never persisted) from the cardinality_cap analysis-omission marker, and states per-version bounds honestly. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Revision 7 state-integrity pass. The snapshot→scope-version FK protected membership, but 012's snapshots→scopes CASCADE and a cascading scope_versions→scopes FK would still let a direct base-scope delete destroy active membership and snapshots — prospective 013 sets both retained child→scope FKs to ON DELETE NO ACTION (repo/account teardown still cascades via the direct repository/user FKs; NO ACTION is named exactly because it checks after the statement's referential actions, unlike RESTRICT). Adds the retired-version lifecycle gate: at most one active plus one building version, fresh-build preflight GCs retired versions in legal order before initializing, making the ≤~1000 base identity bound real. Defines committed-V-provenance staging cleanup on scope restart (build-level staging has no scope provenance and the represented set can drift), and strengthens promotion to require the staged linked key set to exactly equal the represented V key set. Docs only — no migration, no production change. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
15 of 17 tasks
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 1C-B0 design tranche — resolves the ownership spec §9.1 persistence-handoff blocker at the design level only. No code, schema, runtime wiring, or production changes.
Fundamental finding: the four-table 012 model is provably insufficient for exact crash-safe accumulation — exact Top-25/
human_contributor_countrequires the complete per-contributor scope set, multi-invocation walks lose in-memory state, and none of the four tables can hold provisional counters without violating the privacy contract. Minimum amendment: one ephemeral work table (ownership_history_work) + one CAS checkpoint function (prospective migration 013, not created).Recommended architecture: per-scope accumulate → resolve → commit lifecycle; page delta + cursor advance in ONE Postgres transaction (exactly-once under retry, proven for both forbidden crash windows and lost-response replays); deterministic
contributor_keyas the work key (preserves Top-25 tie semantics exactly); two-pass identity resolution so overflow contributors'github_node_id/loginare never persisted; pinned-revision walks viaobject(oid:)— flagged as requiring a non-persisting Phase 1C-B0.5 spike (unmeasured query shape).Contains: full option evaluation (A–D), impossibility analysis, work-table shape/bounds/TTL, versioning/promotion, 19-case failure matrix, concurrency/rate-limit design, backup classification (EPHEMERAL), differential-equivalence test design, and the proposed spec amendment (recorded in §27 as PROPOSED — not live).
Test plan
npm test— 613 pass / 0 fail (docs-only diff; contract-scan tests green)lib/,api/,src/,migrations/, config, or test changesGenerated with Devin