fix(setup-preflight): the local lock parser rejects the keys install.md tells the agent to write #1491

What

For snapshot installs (method: git-branch | git-tag | svn-zip), .apache-magpie.local.lock is written by the agent following install.md (line 1038) and upgrade.md (line 241), in the format locks.md documents (lines 316-324):

source_method:    <git-branch | git-tag | svn-zip>
source_url:       <URL the snapshot was actually fetched from>
source_ref:       <branch / tag / version actually fetched>
fetched_commit:   <commit SHA on disk now>
fetched_at:       <ISO-8601 timestamp>

The pre-flight checker reads that file with the committed-lock parser (setup_preflight/core.py:128-132). That parser accepts only method, url, min_version, ref, commit and source (setup_preflight/lockfile.py:98-101) and raises on anything else:

>>> parse("source_method: git-tag\nsource_ref: v0.3.0\nfetched_commit: abc\n")
MalformedLock: unknown key: 'source_method'

core.py turns that into the snapshot-unreadable finding. Even if parsing passed, the drift check right after it (core.py:133-137) compares method / url / ref / commit, keys the documented local lock does not have.

Every other reader agrees with the documented format: upgrade.md:161-166 and verify.md:201 compare <committed-lock>.method with <local-lock>.source_method and the ref with source_ref / fetched_commit, and skills/status/scripts/collect_status.py:314-316 reads source_method, source_url and source_ref. The pre-flight parser is the one reader that expects something else.

Why it matters

snapshot-unreadable routes to sections/step-2.md, which says "Either way this is a stop, not a note". The pre-flight block runs at the top of every framework skill, so on a snapshot install that followed install.md and has the pre-flight checker installed (/magpie-setup config puts it under .apache-magpie-local/), every skill stops before doing any work. Without the checker the pre-flight block proposes installing it and carries on, so the stop starts once the checker is in place. The remedies step-2 proposes, /magpie-setup and /magpie-setup upgrade, write the local lock again in the same documented format, so they do not clear the finding.

Marketplace and method: local installs are not affected: _snapshot_findings() only runs for SNAPSHOT_METHODS (core.py:67, 181-182).

The tests miss it because tools/setup-preflight/tests/test_core.py:118-132 writes the local lock with the committed lock's keys (method: / ref:), not the documented ones.

Suggested fix

Teach the pre-flight checker the local-lock format rather than changing the docs, since four docs and collect_status.py already agree on it:

1. Parse .apache-magpie.local.lock with its own key set (source_method, source_url, source_ref, fetched_commit, fetched_at) and compare each committed-lock key with its local counterpart, following the table in upgrade.md:161-166.
2. Have collect_status.py use the same parser, so the two readers cannot drift apart again.
3. Build the test_core.py fixtures from the format in locks.md.

Changing the documented format instead would also work, but every existing local lock on adopter machines would then need rewriting.

Found via

Reading the two lock parsers side by side while mapping the setup family; reproduced on main (37670575).

Related

• 9a41522 (fix(setup): make the pre-flight checker and upgrade work for method: local #1414) fixed the same class of bug for source:, a key install.md writes and the parser rejected.
• perf(security): drop the Snapshot drift sections the pre-flight check already covers #1435 and refactor(skills): drop the Snapshot drift sections the pre-flight check already covers #1470 removed the per-skill Snapshot drift sections because the pre-flight check covers them, so on snapshot installs the checker is now the only drift check a skill runs.