Skip to content
go-libfossil Artifact [138c3bcde9]
Login

Artifact [138c3bcde9]

Check-ins Using Download Hex

Artifact 138c3bcde92e0232420d098d45480200956ef20abfeb76a3b904b34d0d18571c:

# Requirements of draft-fossil-sparse-cone-00, written from the draft text.
# Cases cover cone specification, sparse worktrees, store classification,
# internal synchronization and explicit compaction. Scope notes preserve
# incomplete behavior: incomplete file history, bounded request preprocessing
# and public wiring. The e03d91943e57 sparse canonical-writing correction is
# exercised by the Appendix A.6 MAX, final-merge and parent-basis vectors.
# Store cases include deliberately elided fixtures; sync cases exercise real
# loopback wire exchanges, and compaction cases exercise rebuild and healing.
# A passing internal case does not remove an explicitly recorded scope gap.
# Skipped, with reasons: 1 (introduction), 4.5 and 7's last two paragraphs
# (informative), 6.5 (a statement of non-guarantee with no behaviour), 9
# (IANA). Where the draft is silent the
# reference is zit, the other implementation: its serialized form
# (src/cone.zig, byte-identical here and checked against zit in
# testdata/zit-cones), its refusal of an empty inclusion list, and its
# exact-member removal.
# Format: <id>\t<section>\t<requirement>[\t<scope note>]
# draft	draft-fossil-sparse-cone-00.txt	41e70bcc6a6c2b6ccb6476aa65975f3c97849b7d6a0e0ed8af58aa0fbc15f13a
SC-2-1	2	A member covers a path when it equals the path or is a prefix of it ending at a '/' boundary; the absent cone covers everything (dense operation).	an empty cone cannot be built, as in zit: at least one inclusion is required
SC-3.1-1	3.1	A worktree cone is checkout-local state recorded with the checkout's other local records; it is not an artifact, does not synchronize, and affects no artifact's bytes or name.
SC-3.1-2	3.1	A cone may be widened or narrowed at any time.
SC-3.1-3	3.1	The canonical serialization marks a cone carrying members of other kinds with a distinct version, and an implementation that does not understand a version refuses the cone rather than reading it as path members.
SC-3.1-4	3.1	Refusal of a store cone is policy loss: the store heals toward dense.
SC-3.2-1	3.2	Members are normalized through the worktree-path validation applied to tracked paths: no dot or dot-dot components, no empty components, no reserved roots.
SC-3.2-2	3.2	A member covered by another member of the same polarity with no opposite-polarity member between them is removed, and the normalized cone is what classification uses.
SC-3.2-3	3.2	At least 64 members are supported, and 255 should be.
SC-3.3-1	3.3	Coverage is decided by the longest member of either polarity that covers the path, which is order-independent, so the canonical sorted serialization and the digest do not depend on input order.
SC-3.3-2	3.3	Polarity may alternate along a nesting chain: a subtree excluded from an inclusion may contain a deeper re-inclusion.
SC-3.3-3	3.3	A member whose nearest covering member has the same polarity is redundant and is removed.
SC-3.3-4	3.3	An exclusion that no inclusion covers is a dead rule and is refused.
SC-3.3-5	3.3	One path carried with both polarities is a contradiction and is refused.
SC-3.3-6	3.3	A key range wholly inside an inclusion and outside every exclusion classifies as before; a range an exclusion intersects is classified per file, at no cost to correctness.
SC-3.4-1	3.4	Members are literal path prefixes; glob and pattern members are not part of the mechanism.
SC-3.4-2	3.4	A member names a directory subtree or a single file with equal standing.
SC-3.4-3	3.4	A metacharacter in a member is a literal character of the path: it is never expanded, and the member may be refused.
SC-3.5-1	3.5	Amending a cone by wholesale replacement and by member addition or removal are equivalent, and the incremental form should be offered.
SC-3.5-2	3.5	Widening fetches what the cone newly covers (the policy form of demand fetch).	over a dense store widening materializes from the store; demand fetch over a sparse store is Appendix A step 4
SC-3.5-3	3.5	Narrowing dematerializes and leaves reclamation to explicit compaction.
SC-4-1	4	The sparse worktree is available to any conforming repository, with flat or tree-structured manifests.
SC-4.1-1	4.1	A checkout operation given a cone materializes exactly the covered files.
SC-4.1-2	4.1	The managed-file record covers only in-cone files.	the strict three-physical-row fixture passes on the private-marker implementation; marker transitions, legacy unstamped undo refusal and cone-stamped undo images are reviewed; durable crash recovery of the marker remains unverified
SC-4.1-3	4.1	Status, untracked-file listing and bulk tracking operate within the cone; an uncovered on-disk path is neither reported as untracked nor eligible for tracking.
SC-4.1-4	4.1	A request to track a path outside the cone is refused, and the refusal names the cone as the reason; a diagnostic that reports a missing file or alleges damage does not conform.
SC-4.1-5	4.1	All file-set enumeration flows through the shared enumeration interface with the cone applied there as a range predicate, never filtered at individual call sites.
SC-4.2-1	4.2	A commit from a sparse worktree produces a check-in whose file set is the in-cone files as observed in the worktree and the baseline's out-of-cone entries carried unchanged.
SC-4.2-2	4.2	For flat manifests the baseline's out-of-cone F cards are copied byte-verbatim, merged in sorted order with the in-cone F cards.
SC-4.2-3	4.2	Tree commits produce full canonical construction under the requested k; opaque reuse requires compatible partition evidence bound to the immutable parent, rules and k or verification from needed descriptors and entries. The structural affected range includes MAX-cut shifts, final-small-group merges and propagation at every height; necessary absent nodes are fetched or cause explicit refusal without a partial check-in.
SC-4.2-4	4.2	The result is an ordinary check-in: a reader cannot detect that it was committed sparsely, and no new artifact form is introduced.
SC-4.3-1	4.3	A sparse-worktree commit over a dense store may compute the R card by reading out-of-cone content from the store.
SC-4.3-2	4.3	A commit over a sparse store omits the R card.
SC-4.3-3	4.3	Verifiers do not treat an absent R card as damage.
SC-4.3-4	4.3	A verifier checking a present R card during a sparse materialization computes the aggregate over the dense enumeration, reading out-of-cone content from the store.	materialization verifies no R card; manifest.VerifyRCard, which every commit runs, always aggregates the dense enumeration
SC-4.3-5	4.3	A verifier over a sparse store skips R verification rather than report disagreement.
SC-4.4-1	4.4	Over a dense store, merge, update and revert apply changes to out-of-cone files to the record without materializing them.	record-only merge and conflict, update keeping the pending merge, partial-commit queue handling, mode-only revert and undo after cone changes are reviewed against fossil; revert of a record-only change has no conformance case and stash apply on a sparse checkout is untested
SC-4.4-2	4.4	The count of out-of-cone changes applied should be reported.
SC-4.4-3	4.4	Read operations on an uncovered path over a dense store read the store: the cone governs materialization, not readability.
SC-5-1	5	A sparse store requires tree manifests for the segment it elides; a flat segment may elide only its content blobs and holds its manifests densely.
SC-5.1-1	5.1	A store sparse at a cone holds every manifest, every in-cone sub-manifest node and every blob an in-cone F card names, and every non-manifest structural artifact densely. Out-of-cone nodes and blobs MAY be absent as elided phantoms; already-held or demand-fetched payloads need not be discarded.
SC-5.2-1	5.2	Transit phantoms, shunned artifacts and elided phantoms are distinguished; synchronization does not spontaneously request an elided phantom, whose absence is healthy.
SC-5.2-2	5.2	Elision is computed from the cone, not stored on the phantom: reclassification on cone change is recomputation, and losing the store cone should reclassify every elided phantom as a transit phantom.
SC-5.2-3	5.2	Verification reports a store complete within its cone as healthy, reports elision counts distinctly from damage, and reports transit phantoms and damaged in-cone artifacts as for a dense store.
SC-5.3-1	5.3	A commit may reference elided subtrees proved identical to canonical construction by hash without possession; nodes required for boundary propagation or partition validation are fetched or cause explicit refusal. Pushing a canonically valid check-in is sound.
SC-5.3-2	5.3	A server should refuse to be a clone origin for cones it does not cover, unless configured as a partial mirror, with one error card and no content.	internal handler refusal and override are tested; public partial-mirror configuration remains pending
SC-5.3-3	5.3	A client treats a clone-round reply that carries an error card and no clone progress as fatal.
SC-5.4-1	5.4	Widening reclassifies the newly covered elided phantoms as transit phantoms and fetches them.
SC-5.4-2	5.4	Narrowing does not by itself delete held content; only explicit compaction deletes, dropping artifacts both out-of-cone and unreferenced by any spine, through the store-rewrite machinery and its locks.	internal file and limited interior-node compaction are tested; provenance-bearing leaves and nonterminal paths remain held, and the public entry point is pending
SC-5.5-1	5.5	The flat prefix of a hybrid history holds its manifests densely; its content blobs may be elided by F-card classification.
SC-6.1-1	6.1	A cone-scoped pull or clone adds one pragma cone card per inclusion member, encoded exactly as an F-card filename, and one pragma cone-not card per exclusion.
SC-6.1-2	6.1	For check-in content a cone-scoped request asks for spines, in-cone sub-manifest nodes and in-cone blobs, and neither expects nor requests the remainder.	aware clone and pull are tested; provenance-bearing outside nodes are conservatively retained rather than fully elided
SC-6.2-1	6.2	A cone-aware server walks each check-in's tree descending only nodes whose key range intersects the cone, emits the spine, the in-cone nodes and blobs, and bounds the per-round walk as a dense clone bounds its batches.	the per-round clone walk stops at the dense batch bound; keep-set discovery on the ordinary serve path still reads the whole held store per request, refusing past a fixed budget, and the prepared index that avoids it is built by an off-path whole-store pass with no public wiring
SC-6.2-2	6.2	A cone-aware server does not serve a delta whose base is outside the keep set it computed for the request; it serves that artifact in full form.
SC-6.2-3	6.2	A recipient treats a phantom that a retained delta names as its source as a transit phantom whatever its cone classification.
SC-6.3-1	6.3	Against a cone-ignorant server the requester filters locally: it stores in-cone artifacts, records elided phantoms for the remainder and reports the counts.	ignored-pragma clone and pull filtering and counts are tested; provenance-bearing outside nodes remain held
SC-6.3-2	6.3	A cone-aware server should advertise the capability.	capability advertisement is not implemented
SC-6.4-1	6.4	An operation over a sparse store that crosses the cone resolves elided phantoms by a targeted request or by the policy form, which is recommended for lasting intent.	internal explicit-peer policy fetch is tested; public operations and saved-peer integration remain pending
SC-6.4-2	6.4	With no configured peer the operation refuses, and the diagnostic names the class (the count elided by the cone and the absence of a peer), never missing or corrupt.	internal explicit-peer refusal and cancellation are tested; public operations and saved-peer integration remain pending
SC-7-1	7	Derived caches are cone-independent: their keys do not incorporate the cone.
SC-8-1	8	The member count and member length of a cone are bounded with the same limits applied to F-card filenames.
SC-8-2	8	The server-side tree walk on cone requests carries the depth and visited-node bounds of single-name lookup.