Merge pull request #17 from galaxyproject/kind-companions

The kind catalog renders the layout the instances declare

Author: jmchilton

content/pattern/astro-stack-glossary.md

@@ -77,7 +77,14 @@ summarized paper). Three consequences worth stating outright:
 Each declaration carries a **requirement level** (`required` / `recommended` / `optional`) and a
 **disposition** — whether casting may carry the file into a skill artifact (`foundry-only` never
 leaves; `cast-input` is read by the caster but does not appear in the output; `bundled` is copied
-in).
+in). The disposition is enforced, not descriptive: a cast's forbidden-file list is derived from
+it rather than restated beside it.
+
+> A second collision worth naming, like the one above. An instance may also carry a per-*note*
+> `companions:` field, and it answers a different question — not *what may sit beside this note*
+> (layout, the kind's to declare) but *what does this note carry into a cast* (membership, which
+> stays declared per note precisely so that no file ships because of where it was saved). Both
+> senses are legitimate; a page using either should say which.
 
 **Collection** — a *location*: a base directory plus the pattern selecting which files under it are
 notes, and the kind those notes are. Collections and kinds are deliberately not one-to-one — one

content/pattern/kind-catalog.md

@@ -67,21 +67,30 @@ artifact. Both terms are pinned in the [[astro-stack-glossary]] — they belong
 than to the pattern — and specified in Part 3 of the
 [[standing-up-a-foundry|Astro-stack worked example]].
 
-Two things that declaration makes visible for the first time:
+Three things that declaration makes visible for the first time:
 
 - **`pattern` is a directory in one instance and a flat file in the other.** Same kind, same
   layer, different physical form. That difference used to live inside each instance's collection
   glob and reached no manifest, so this page could not have reported it however carefully you
   read the tables.
 - **An open companion set is not an empty one.** A kind may declare that files it has not
-  enumerated are legitimately present — vendored sources beside a research note, acquisition
-  files beside a book chapter. That says *unbounded*, not *none*. They are opposite claims, and
-  only one of them is checkable.
-
-**Not in the tables below yet.** The declarations landed in the instances first. The snapshots
-this page renders predate them, and this site's manifest reader is still the version that drops
-the new fields on the way in. So the section above describes what the instances now declare, not
-what is rendered below — deliberately stated rather than left for a reader to discover as a gap.
+  enumerated are legitimately present — vendored sources beside a research note. That says
+  *unbounded*, not *none*. They are opposite claims, only one of them is checkable, and the table
+  below marks the open one rather than leaving a blank to be read either way. Exactly one kind
+  across both instances declares it. A book chapter looked like the second case and is not: its
+  acquisition files sit at the *book* level, one directory above the chapter that is the note, so
+  declaring the chapter open would have claimed unboundedness where the truth is those files
+  belong to a container that is not a note at all.
+- **The declaration is load-bearing, not documentation.** One instance's casting pipeline kept a
+  hand-written list of files a skill artifact may never carry; it named two of the eight its kinds
+  declare. Deriving that list from the dispositions instead is what turned the metadata this page
+  reports into something a check answers to — and the size of the gap is the argument for it.
+
+Each substrate kind below carries a companion table with one row per file and one column per
+instance, reading *requirement · disposition*. A file both instances declare at the same
+requirement and the same disposition is highlighted: that is the layout transferring, and it is
+the strongest claim on this page. A file one instance declares and the other does not shows as a
+dash — an extension inside a shared kind, which is a real difference and not a gap in the data.
 
 For where these kinds live inside a repository, and what a new instance should copy first, see
 [[anatomy-of-an-instance]] and the [[standing-up-a-foundry|Astro-stack worked example]]. For the

content/pattern/standing-up-a-foundry.instructions.txt

@@ -65,6 +65,12 @@ deduced:
 - **Commit the probe.** One instance carried three comments claiming its typecheck caught a
   hazard; measured, it caught neither of the two. Zero errors is what success and total erasure
   both look like.
+- **An upgrade can move a rule's enforcement without moving the rule.** Both instances took the
+  same major-version wave, and it changed *who* was holding two of the checklist's rules. A schema
+  library stopped making one of them compulsory, so the contract now holds it alone; a framework
+  stopped running a plugin pipeline unless asked, so a build that renders every link as literal
+  text still passes. Neither failure is loud, and a checklist that keeps the rule while its
+  original justification quietly expires is how prescription rots.
 
 That last one is the shape of the whole category: the checklist absorbed the measurement, not
 the assumption.

content/pattern/standing-up-a-foundry.md

@@ -16,7 +16,7 @@
   },
   "dependencies": {
     "@fontsource/atkinson-hyperlegible": "^5.2.8",
-    "@galaxy-foundry/kind-manifest": "^0.2.1",
+    "@galaxy-foundry/kind-manifest": "^0.3.0",
     "@galaxy-foundry/tag-registry": "^0.1.0",
     "@galaxy-foundry/wiki-links": "^0.1.0",
     "@tailwindcss/typography": "^0.5.19",

site/package-lock.json

@@ -1,23 +1,36 @@
 ---
 import {
+  companionRows,
   loadInstances,
   kindRows,
   layerDisagreements,
   sharedRequiredFields,
+  shapeDifferences,
 } from "../lib/instances";
+import type { ManifestKind } from "../lib/instances";
 
 const instances = loadInstances();
 const rows = kindRows(instances);
 const shared = rows.filter((r) => r.shared);
 const local = rows.filter((r) => !r.shared);
 const disagreements = layerDisagreements(rows);
+const differingShapes = shapeDifferences(rows);
 const base = import.meta.env.BASE_URL.replace(/\/$/, "");
+
+// A directory kind that enumerates nothing is not the same as one that declares undeclared
+// files legitimate. Both would render as an absent companion table, so `allow` is said out loud.
+const openSet = (kind: ManifestKind) => kind.additionalCompanions === "allow";
 ---
 <div class="not-prose mt-8">
   <div class="rounded-lg border p-4 text-sm" style="border-color: var(--rule); background: var(--graphite)">
     <strong>Generated</strong> from each instance's own schemas. Every required-metadata table
     below is derived from that instance's zod definitions, not transcribed — so a kind that
-    changes upstream changes here, and cannot quietly disagree.
+    changes upstream changes here, and cannot quietly disagree. A kind also declares its
+    <strong>shape</strong> and its <strong>companions</strong>: each companion carries a
+    requirement level (<code>required</code> / <code>recommended</code> / <code>optional</code>)
+    and a disposition saying where it may travel — <code>foundry-only</code> never leaves the
+    Foundry, <code>cast-input</code> is read while casting but not shipped,
+    <code>bundled</code> is carried into the artifact.
     <ul class="mt-2 space-y-0.5" style="color: var(--muted)">
       {instances.map((i) => (
         <li>
@@ -37,6 +50,17 @@ const base = import.meta.env.BASE_URL.replace(/\/$/, "");
     </p>
   )}
 
+  {differingShapes.length > 0 && (
+    <p class="mt-4 rounded-lg border p-4 text-sm" style="border-color: var(--rule); color: var(--muted)">
+      <strong style="color: var(--ink)">Same kind, different shape:</strong>{" "}
+      {differingShapes.join(", ")} — a flat file in one instance, a directory in the other. Not
+      drift, and not smoothed over: the two are the same kind carrying the same required
+      metadata, laid out differently because one domain needed files beside the note and the
+      other did not. Before kinds declared a shape this difference lived inside each instance's
+      collection glob and reached no manifest, so this page could not have reported it.
+    </p>
+  )}
+
   <h2 class="mt-10 text-2xl font-bold" style="font-family: var(--font-display)">
     Substrate kinds
   </h2>
@@ -54,7 +78,25 @@ const base = import.meta.env.BASE_URL.replace(/\/$/, "");
       <dl class="mt-3 space-y-3 text-sm">
         {row.present.map((i) => (
           <div>
-            <dt class="font-semibold">{i.title}</dt>
+            <dt class="font-semibold">
+              {i.title}
+              {row.by[i.slug]!.shape && (
+                <span
+                  class="ml-2 rounded px-1.5 py-0.5 text-xs font-normal"
+                  style="background: var(--graphite); color: var(--muted)"
+                >
+                  {row.by[i.slug]!.shape}
+                </span>
+              )}
+              {openSet(row.by[i.slug]!) && (
+                <span
+                  class="ml-1 rounded px-1.5 py-0.5 text-xs font-normal"
+                  style="background: var(--graphite); color: var(--glow)"
+                >
+                  open companion set
+                </span>
+              )}
+            </dt>
             <dd class="mt-0.5" style="color: var(--muted)">{row.by[i.slug]!.summary}</dd>
             <dd class="mt-1">
               <span style="color: var(--muted)">requires</span>{" "}
@@ -71,6 +113,54 @@ const base = import.meta.env.BASE_URL.replace(/\/$/, "");
           {sharedRequiredFields(row).map((f) => <code class="mr-1">{f}</code>)}
         </p>
       )}
+      {companionRows(row).length > 0 && (
+        <div class="mt-3 border-t pt-3" style="border-color: var(--rule)">
+          <p class="text-sm"><strong>Companions</strong></p>
+          <div class="mt-2 overflow-x-auto">
+            <table class="w-full text-left text-sm">
+              <thead>
+                <tr style="color: var(--muted)">
+                  <th class="pb-1 pr-4 font-normal">file</th>
+                  {row.present.map((i) => (
+                    <th class="pb-1 pr-4 font-normal">{i.title}</th>
+                  ))}
+                </tr>
+              </thead>
+              <tbody>
+                {companionRows(row).map((companion) => (
+                  <tr class="border-t align-top" style="border-color: var(--rule)">
+                    <td class="py-1.5 pr-4">
+                      <code style={companion.identical ? "color: var(--glow)" : undefined}>
+                        {companion.file}
+                      </code>
+                    </td>
+                    {row.present.map((i) => (
+                      <td class="py-1.5 pr-4">
+                        {companion.by[i.slug] ? (
+                          <span>
+                            {companion.by[i.slug]!.requirement}
+                            <span style="color: var(--muted)">
+                              {" · "}{companion.by[i.slug]!.disposition}
+                            </span>
+                          </span>
+                        ) : (
+                          <span style="color: var(--muted)">—</span>
+                        )}
+                      </td>
+                    ))}
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+          {companionRows(row).some((c) => c.identical) && (
+            <p class="mt-2 text-sm" style="color: var(--muted)">
+              Highlighted files are declared by both instances at the same requirement and the
+              same disposition — the layout itself transferring, not just the kind's name.
+            </p>
+          )}
+        </div>
+      )}
     </section>
   ))}
 
@@ -93,6 +183,22 @@ const base = import.meta.env.BASE_URL.replace(/\/$/, "");
           .map((row) => (
             <div class="mt-3 rounded-lg border p-4" style="border-color: var(--rule)">
               <code style="color: var(--ember)">{row.kind}</code>
+              {row.by[instance.slug]!.shape && (
+                <span
+                  class="ml-2 rounded px-1.5 py-0.5 text-xs"
+                  style="background: var(--graphite); color: var(--muted)"
+                >
+                  {row.by[instance.slug]!.shape}
+                </span>
+              )}
+              {openSet(row.by[instance.slug]!) && (
+                <span
+                  class="ml-1 rounded px-1.5 py-0.5 text-xs"
+                  style="background: var(--graphite); color: var(--glow)"
+                >
+                  open companion set
+                </span>
+              )}
               <p class="mt-1 text-sm" style="color: var(--muted)">
                 {row.by[instance.slug]!.summary}
               </p>
@@ -102,6 +208,18 @@ const base = import.meta.env.BASE_URL.replace(/\/$/, "");
                   .filter((f) => f.required)
                   .map((f) => <code class="mr-1">{f.name}</code>)}
               </p>
+              {(row.by[instance.slug]!.companions ?? []).length > 0 && (
+                <ul class="mt-2 space-y-0.5 text-sm">
+                  {row.by[instance.slug]!.companions!.map((companion) => (
+                    <li>
+                      <code>{companion.file}</code>{" "}
+                      <span style="color: var(--muted)">
+                        {companion.requirement} · {companion.disposition}
+                      </span>
+                    </li>
+                  ))}
+                </ul>
+              )}
             </div>
           ))}
       </div>