feat(server): default a package's discovery surface to its index.malloy

[mlennie]

What this does

A package whose root holds an index.malloy now takes its discovery surface from that file, with no explores key in publisher.json. Listings return that file and whatever it exports; the other models become building blocks. An explicit explores still wins, and when a package has both and they disagree, the explicit key is used and the package carries a load-time warning rather than the server guessing. create-malloy-package now scaffolds an index.malloy, so a new package is curated from its first boot.

This is the convention described under Open questions in docs/malloyyo-dashboards-design.md, and it matches what Malloyyo does: its project entry point is the same hardcoded filename, and export { ... } inside it selects what consumers may query.

Where this departs from the design note, and why

The note also defaults queryableSources to "declared". I did not do that, and the reason is that it would not have been additive.

queryableSources is already "declared" by default. The query boundary is inert today only because explores is undeclared, and Package.exploresDeclared() was the single predicate driving both the listing curation and the boundary. So defaulting explores on its own switches the boundary on. That boundary denies with a 404 that is deliberately indistinguishable from "does not exist" (errors.ts, to avoid an enumeration oracle). A package that merely happened to contain a file with that name would have lost query access to every other source by name, with no config edit and no error the author could act on. Malloyyo can be absolute here because every project is greenfield and --develop is its escape hatch; Publisher has packages in the wild and no mode split.

So the convention curates discovery only. exploresDeclared() is split in two: the listing predicate counts a surface from either source, and a new boundaryDeclared() counts only an explores the author wrote. The rule stays teachable: writing an index.malloy curates your listings, and declaring explores is what gates access. Adding an index.malloy can hide a source from listings; it can never make one unreachable.

This is not a preference. Reverting that split fails four tests in query_boundary.spec.ts, and two of them are pre-existing backward-compatibility tests, one of which is the injection test. That is the evidence the split was required rather than chosen.

Happy to change this if you would rather match the note exactly, but it should be a deliberate call, because the failure mode is silent.

Deprecation is accept-with-warning, not removal

Removing explores / queryableSources would be a breaking REST and config change across api-doc.yaml and its four generators, for no gain over defaulting. Instead the keys keep working and earn a warning where the convention now covers them, following the precedent resolvePackageScope already sets in the same file for the deprecated root-level scope: a pure resolver returning { value, warnings }, riding the existing manifestWarnings channel.

The warning fires only when a package has an index.malloy and declares the legacy keys. A blanket warning on every explores user would fire on our own examples/governed-analytics, which curates a two-file surface the convention cannot express. That is a warning with no available fix, which is how deprecation warnings get ignored. Three cases, mutually exclusive: the explicit set omits the index file (disagreement), the explicit set names it (now redundant, safe to delete), or the convention is driving and a declared queryableSources is therefore inert and says so.

Implementation notes worth a reviewer's eye

• The origin flag is a constructor parameter, not a post-construction assignment. Package's constructor runs both policy pushes, so assigning it afterwards the way manifestWarnings is assigned would compute the boundary as if the surface were explicit, for exactly the packages this protects.
• It lives on the Package, not in packageMetadata, because setPackageMetadata replaces that object wholesale. A name-only PATCH would otherwise promote a convention-derived surface into a declared one and start returning 404s. The PATCH path preserves it, clears it when the body carries its own explores, and restores it on the reject path.
• File listing now runs before the manifest read in the load worker, since the convention is a fact about the tree. Both still sit in the setup region excluded from the compile timing.
• Only a root-level index.malloy counts. A nested reports/index.malloy is an ordinary model; the convention only helps if there is one place to look.
• An explicit explores: [] counts as explicit and does not trigger the convention. It reads as a deliberate "do not curate", and today it means everything is listed.
• The design note's "publisher.json is absent" branch is unreachable in Publisher: the manifest is mandatory, so only the "has no explores" half applies.

Verification

Gate: typecheck clean, unit 2312/0, integration 250/0. prettier:check reports the six standing failures, all confirmed git-ignored generated files that CI never sees. Regenerating skills_bundle.json was needed because the skill text changed.

The Malloy re-export syntax in the scaffolded template was compiled through the real worker rather than assumed.

Verified live against a freshly built bundle, not just tests. A package with an index.malloy and no explores lists only that file and its export closure, and a source hidden by it still answers 200 when queried by name. The same package with an explicit explores that omits the index file lists the declared set, 404s the hidden source, and carries the disagreement warning. A package scaffolded by create-malloy-package and served on a running server lists index.malloy, exposes its one exported source, and queries successfully.

Coordination

This touches no listing path. It edits applyQueryBoundaryToModels and the two predicates only, so discoverDashboards and the other exploreSet() call sites are untouched and the slice 6 work on dashboard curation is unaffected. Worth knowing there: exploreSet() can now return a convention-derived set, so gating dashboards on it will gate them on an index.malloy surface too, which is almost certainly what you want.

[Sha-Bang]

Closing this as stale rather than rejected — the idea is sound and the design note behind it stands.

The blocker is drift. 23 of this PR's 30 files have been rewritten on main since it was opened on 2026-08-13, including model.ts, package.ts, package_manifest.ts, api-doc.yaml, and all three files of the package_load worker. Rebasing that isn't a rebase; it's a reimplementation against a codebase that moved underneath it, and no one has reviewed the original to inherit a verdict from.

The core of it is also a live design decision rather than a mechanical one. Splitting exploresDeclared so the convention curates discovery without switching on the query boundary is the right instinct — and the reasoning for it in the description, about packages in the wild and the 404 that's deliberately indistinguishable from "does not exist", is the most valuable thing here. exploresDeclared is still a single undivided predicate on main today, so that decision is genuinely open and should be made deliberately, not inherited through a conflict resolution.

The convention is still described under Open questions in docs/malloyyo-dashboards-design.md, so nothing is lost by closing this. Anyone picking it up should start from that note and current main.

[jswir]

Revived as #1206, reimplemented against current main rather than rebased: zero commits from this branch are in it, and the base is one day off main instead of 147 commits behind.

It also resolves the open decision this PR's closing note called out, in the opposite direction. The convention arms the query boundary rather than curating listings only, because the population that split was protecting turns out to be empty (checked across malloy-samples, the bundled examples, and the Malloyyo example repos). That reversal deletes most of the machinery here: no exploresFromConvention, no boundaryDeclared, no post-load warning channel, no PATCH origin rule.