Delta Index Spec - #6500
Conversation
This comment was marked as outdated.
This comment was marked as outdated.
There was a problem hiding this comment.
🟡 Changes recommended
The spec does not fully conform to the required spec template/conventions (issue id/link and filename format), which should be corrected before approval.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Adds a new WinGet specification describing “delta index” support for the pre-indexed package source, outlining generation, retrieval, and merge (ATTACH + TEMP VIEW) mechanics to reduce recurring full-index downloads.
Changes:
- Introduces a detailed spec document for delta index publishing and client consumption.
- Updates the spelling allowlist for new SQLite-related terms referenced in the spec.
File summaries
| File | Description |
|---|---|
| doc/specs/Delta Index.md | New spec describing delta index design, flows, schema, merge views, and rollout considerations. |
| .github/actions/spelling/expect.txt | Adds expected spellings for new technical terms used in the spec. |
Review details
Suppressed comments (2)
doc/specs/Delta Index.md:9
- Per the spec template, the title should be followed by a “For #” line linking to the tracking issue. This spec currently omits the issue link.
# Delta Index
## Abstract
doc/specs/Delta Index.md:7
- Spec filenames are expected to follow the repository convention
doc/specs/#<issue-id> - <Short Description>.md. This file name ("Delta Index.md") doesn’t include the issue id prefix.
# Delta Index
- Files reviewed: 2/2 changed files
- Comments generated: 3
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| @@ -0,0 +1,955 @@ | |||
| --- | |||
| author: JohnMcPMS, GitHub Copilot <Copilot> | |||
| --- | ||
| author: JohnMcPMS, GitHub Copilot <Copilot> | ||
| created on: 2026-09-01 | ||
| last updated: 2026-09-01 | ||
| --- |
| [Feature gating](#feature-gating), which is removed once the feature graduates — that is a | ||
| maturity progression rather than a deprecation, and it removes no user-visible surface. | ||
|
|
||
| ## Resources |
| Whether to roll the baseline is a **service policy decision**, not a client or index concern. | ||
| The index code is told what the baseline is; it does not choose. | ||
|
|
||
| A baseline roll is expensive: every delta client pays a full-index download at their next |
There was a problem hiding this comment.
This is probably out of scope for now, but I wonder if we could find a way to avoid paying the full cost for baseline rolls. I'm thinking of MSIX deltas, but IIRC you've said that wouldn't help because we download the full .msix for source updates.
There was a problem hiding this comment.
MSIX deltas might work for this as the baseline can be immutable. We would have to see how well deltas actually work for us though. If the service doesn't remove old ones, we can survey them after a few baseline rolls.
We might also want to consider if things like not vacuuming the database would produce better binary diffs. That could mean larger baselines but could be worth it if the binary diff was smaller.
| function: | ||
|
|
||
| 1. Validates the index is a legitimate baseline candidate: post-`PrepareForPackaging`, schema | ||
| V2.1 or higher, and not itself a delta. |
There was a problem hiding this comment.
not itself a delta
That just means it has the identity for the full index, not the identity for the index delta, right?
There was a problem hiding this comment.
No, identity is not known here. Deltas will be "tagged" with metadata and a different schema.
|
|
||
| ##### Designation is an explicit act | ||
|
|
||
| Being a baseline is **not** an implicit property of any prepared index. The service calls a |
There was a problem hiding this comment.
Why would we not designate all indexes as potential baselines? Couldn't we just choose to not use them for future deltas even if they have a designated GUID?
There was a problem hiding this comment.
We could, but it is wasted space (albeit a tiny amount).
| | `BaselineGuid` | TEXT | GUID of the baseline this delta was built against | | ||
| | `BaselineRelativePath` | TEXT | Publish location of the baseline, relative to the source root | | ||
| | `BaselinePackageVersion` | TEXT | MSIX package version of the baseline package | | ||
| | `MinimumBaselineSchemaVersion` | TEXT | Lowest baseline schema version this delta can be applied to | |
There was a problem hiding this comment.
Aren't deltas applied to a single baseline with a fixed schema version?
| - **`PrepareForPackaging` is not byte-reproducible.** It ends in a VACUUM and stamps fresh | ||
| timestamps, so regenerating a logically identical baseline yields a different file. A hash | ||
| would force the service to archive the exact published bytes for as long as any delta | ||
| references them, and would break the moment a baseline was repackaged or re-vacuumed. |
There was a problem hiding this comment.
Why would we ever regenerate a baseline, or discard it while a delta is still available?
| **Affinity is not integrity, and does not need to be.** The GUID proves the delta and baseline | ||
| were built as a pair; it does not prove the baseline is uncorrupted. Corruption and tampering |
There was a problem hiding this comment.
One thing a GUID doesn't prove is that the assignment was unique, whereas a hash does. (Both are possible with low probability; I mean that with a hash there is no risk of a programming error assigning the same ID to the same baseline.
| ### Accessibility | ||
|
|
||
| No impact. The feature adds no new console output, no new prompts, and no new interactive | ||
| elements. Existing source update output — which is already screen-reader compatible — is |
There was a problem hiding this comment.
which is already screen-reader compatible
Neat. I did not know this
📖 Description
Spec for delta index support; see spec for many more details.
Microsoft Reviewers: Open in CodeFlow