feat(core)!: keep reading a manifest that declares a usage kind we do not know by vytautas-astrauskas-sensmetry · Pull Request #557 · sensmetry/sysand

vytautas-astrauskas-sensmetry · 2026-09-22T14:38:09Z

.project.json deserializes its usage array through an untagged enum with
no catch-all, so an entry matching no known kind fails the whole document.
The day a fourth usage kind ships, every sysand already installed stops being
able to read those projects at all — not only lock and sync, but info,
add and remove too, and with serde's own wording:

data did not match any variant of untagged enum InterchangeProjectUsageG

A version number does not reach a file format (see the PR below this one), so
that behaviour is not something a major bump can fix later. It has to be
fixed before the release, not after.

What changed

InterchangeProjectUsageG::Unknown(UnknownUsage), which keeps the
entry's JSON verbatim, and is refused in validate instead of at parse time:

`.project.json` declares a usage this sysand cannot interpret, with keys "foo", "bar";
it is either a usage kind from a newer sysand, in which case upgrading
sysand will resolve it, or a malformed entry

Tolerating the entry at the parse boundary and refusing it where a caller
acts on it as a dependency separates the two things the old behaviour
conflated. A manifest stays readable and editable: add, remove and info
leave the entry alone and write it back untouched. An unknown dependency
still can never be silently resolved around: lock, sync, build and
publish refuse by name.

The catch-all matches a JSON object, so a usage entry that is not one
remains a parse error — no future kind can explain that shape. It is the last
variant, as untagged requires.

Python gains InterchangeProjectUsageUnknown (a plain dict) and
InterchangeProjectUsageAny for reading, which is what
InterchangeProjectInfo.usage now holds. Writing still takes
InterchangeProjectUsage, restricted to the kinds sysand understands, so
add(usage=…) cannot be used to declare one.

RELEASE.md replaces the gap recorded in the PR below with what now
holds, including the part that does not change: builds released before this
one still fail to parse such a manifest. This only moves the floor. A fourth
usage kind can be introduced once those builds are out of circulation, not
today.

Breaking

InterchangeProjectUsageG gains a variant, so a match over it in Rust
needs a new arm. The crates are not published, so this is internal.
Python: InterchangeProjectInfo.usage is typed InterchangeProjectUsageAny
on the way out. Code that reads a usage as one of the three known shapes
needs a check for the unknown one — which is the point: that value can now
appear where the call used to raise.
No file format change. Nothing new is written; a manifest sysand produces
is byte-identical to before.

Signed-off-by: Vytautas Astrauskas <vytautas.astrauskas@sensmetry.com>

… not know Signed-off-by: Vytautas Astrauskas <vytautas.astrauskas@sensmetry.com>

andrius-puksta-sensmetry · 2026-09-23T06:25:01Z

A manifest stays readable and editable: add, remove and info
leave the entry alone and write it back untouched.

I don't want to rely on this; manifest should be validated on any command that reads it, and I consider it an oversight that we don't do it already.

To achieve the goal of this, PR, I suggest:

accept anything for deserialization
on validation:
- warn about unknown keys (for simplicity, ignore if extra keys are present for a known usage type; keeping track of them would require a rather large refactoring)
- use Unknown usage variant if they are not extra keys for a known type
error out if Unknown usage kind is present when resolving or modifying dependencies (otherwise we can't ensure no duplication)

andrius-puksta-sensmetry · 2026-09-23T06:43:33Z

+// The catch-all `Unknown` variant is what keeps `.project.json` readable
+// across versions: a manifest declaring a usage kind only a newer sysand
+// knows still parses, so every command that does not have to interpret that
+// usage keeps working and rewrites it untouched. Interpreting one is refused
+// in `validate`, so an unknown dependency can never be silently dropped.
+//
+// It must stay the last variant: `untagged` tries variants in order and this
+// one matches any JSON object.


Move this to Unknown variant to not repeat the same.

andrius-puksta-sensmetry · 2026-09-23T12:50:45Z

+            InterchangeProjectUsageRaw::Unknown(unknown) => {
+                log::info!("{header}{removed:>12}{header:#} {unknown}");
+            }


This is unreachable!() by definition; we don't know how to interpret this usage, so for sure can't remove it.

andrius-puksta-sensmetry · 2026-09-23T12:52:29Z

+                // Never a standard library, which is all `excluded_iris`
+                // holds, and worth seeing: it is the one usage `info` can say
+                // nothing else about.


No need for this comment.

andrius-puksta-sensmetry · 2026-09-23T12:54:39Z

+            // `validate` refuses a usage this build cannot interpret, so one
+            // never reaches the solver. Selecting nothing is the safe answer
+            // if that ever changes: it rules this candidate out rather than
+            // resolving a dependency sysand does not understand.
+            InterchangeProjectUsage::Unknown(_) => {
+                deps.push((
+                    DependencyIdentifier::Remote(usage.to_owned()),
+                    DiscreteHashSet::empty(),
+                ));
+            }


This must panic instead of failing silently.

andrius-puksta-sensmetry · 2026-09-23T12:55:31Z

+            // Unreachable in practice -- `validate` refuses an
+            // uninterpretable usage long before one is resolved -- but there
+            // is a truthful thing to print, so print it.
+            InterchangeProjectUsage::Unknown(unknown) => write!(f, "{unknown}")?,


It's an important invariant that this is unreachable!(), so use it.

andrius-puksta-sensmetry · 2026-09-23T12:56:34Z

+            // `validate` refuses a usage this build cannot interpret, so one
+            // never reaches a resolver. Reporting it as unsupported rather
+            // than resolving it is the safe answer if that ever changes.
+            InterchangeProjectUsage::Unknown(unknown) => {
+                Ok(ResolutionOutcome::UnsupportedUsageType {
+                    reason: unknown.to_string(),
+                })
+            }


Unknown usage by definition will never be resolvable, so it must be marked unreachable!() in all places related to resolution.

andrius-puksta-sensmetry · 2026-09-23T13:05:23Z

            }
+            // `usage` passed `validate` above, which refuses an
+            // uninterpretable entry, so there is no merge path to take here.
+            InterchangeProjectUsageRaw::Unknown(_) => {}


unreachable!(); all such places must panic.

andrius-puksta-sensmetry · 2026-09-23T13:06:51Z

 }
+
+#[test]
+fn add_leaves_a_usage_it_cannot_interpret_alone() {


I would prefer to fail in this case, as no merging/duplicate detection can be performed, so the manifest may become invalid.

andrius-puksta-sensmetry · 2026-09-23T13:10:50Z

+            // `validate` refuses a usage this build cannot interpret, so one
+            // never reaches a resolver. Reporting it as unsupported rather
+            // than resolving it is the safe answer if that ever changes.
+            InterchangeProjectUsage::Unknown(unknown) => {
+                Ok(ResolutionOutcome::UnsupportedUsageType {
+                    reason: unknown.to_string(),
+                })
+            }


unreachable!()

andrius-puksta-sensmetry · 2026-09-23T13:11:56Z

                .usage
                .iter()
-                .map(|u| Identifier::from_interchange_usage_unchecked(u).into_string())
+                .filter_map(|u| Identifier::from_unvalidated_usage(u).map(Identifier::into_string))


Something already went wrong if this is reached, so this must panic on Unknown.

andrius-puksta-sensmetry · 2026-09-23T13:12:20Z

                .usage
                .into_iter()
-                .map(|u| Identifier::from_interchange_usage_unchecked(&u).into_string())
+                .filter_map(|u| Identifier::from_unvalidated_usage(&u).map(Identifier::into_string))


Must panic on Unknown.

andrius-puksta-sensmetry · 2026-09-23T13:12:49Z

+            | InterchangeProjectUsage::KparPath { .. }
+            | InterchangeProjectUsage::Unknown(_) => false,


unreachable!()

andrius-puksta-sensmetry · 2026-09-23T13:13:41Z

                    None,
                    InterchangeProjectUsage::Directory { .. }
                    | InterchangeProjectUsage::KparPath { .. }
+                    | InterchangeProjectUsage::Unknown(_)


unreachable!()

andrius-puksta-sensmetry

I guess supporting this cleanly would require introducing a new type, for which there is no time now. Current implementation is fine functionality-wise, but silently accepts incorrect behavior.

andrius-puksta-sensmetry · 2026-09-30T09:59:44Z

We decided to go in the opposite direction with #566.

vytautas-astrauskas-sensmetry added 3 commits September 22, 2026 16:06

feat(py)!: settle the usage API before typed usages arrive

64db42f

Signed-off-by: Vytautas Astrauskas <vytautas.astrauskas@sensmetry.com>

docs(release): say what the version number actually promises

67f928f

Signed-off-by: Vytautas Astrauskas <vytautas.astrauskas@sensmetry.com>

feat(core)!: keep reading a manifest that declares a usage kind we do…

81353f3

… not know Signed-off-by: Vytautas Astrauskas <vytautas.astrauskas@sensmetry.com>

vytautas-astrauskas-sensmetry marked this pull request as ready for review September 22, 2026 14:52

vytautas-astrauskas-sensmetry requested a review from andrius-puksta-sensmetry September 22, 2026 14:52

andrius-puksta-sensmetry reviewed Sep 23, 2026

View reviewed changes

Comment thread core/src/model.rs

andrius-puksta-sensmetry reviewed Sep 23, 2026

View reviewed changes

andrius-puksta-sensmetry requested changes Sep 23, 2026

View reviewed changes

andrius-puksta-sensmetry marked this pull request as draft September 24, 2026 08:17

andrius-puksta-sensmetry closed this Sep 30, 2026

		\| InterchangeProjectUsage::KparPath { .. }
		\| InterchangeProjectUsage::Unknown(_) => false,

Conversation

vytautas-astrauskas-sensmetry commented Sep 22, 2026

What changed

Breaking

Uh oh!

andrius-puksta-sensmetry commented Sep 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andrius-puksta-sensmetry left a comment

Choose a reason for hiding this comment

Uh oh!

andrius-puksta-sensmetry commented Sep 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

andrius-puksta-sensmetry commented Sep 23, 2026 •

edited

Loading