@unoverse-platform/studio 0.1.96 → 0.1.98

package/vendor/base/src/definitions/model.ts

@@ -11,6 +11,12 @@ export interface UnoverseDefinition {
    *  `template` is the Template Model kind (UNOVERSE_TEMPLATE_MODEL.md). */
   kind: "component" | "app" | "atom" | "template";
   name: string;
+  /** APPS: the places the app's layouts declare, in the order first drawn. The screen puts
+   *  interfaces into them by name (docs/unoverse/design/screen/UNOVERSE_SCREEN.md §2.2). */
+  places?: { name: string; holds: "one" | "many" }[];
+  /** COMPONENTS AND TEMPLATES: the place each state names. An interface entering a state
+   *  that names a place moves there (UNOVERSE_SCREEN.md §2.3). */
+  statePlaces?: Record<string, string>;
   /** TEMPLATES (§9b RULED 2026-08-29): the compiled SECTIONS of each state's
    *  layout — one entry per `static:` / `copywriter:` / `director:` line, in
    *  arrangement order. `static`/`copywriter` link a component (face = its
@@ -89,8 +95,8 @@ export interface UnoverseDefinition {
    *  `defaultState` seeds it so the SDK renders that face on arrival (merged beneath
    *  live data). Server-composed from the manifest, never hand-written. */
   state?: Record<string, unknown>;
-  /** COMPONENTS: projected capability flag — true iff the component folder carries a
-   *  manifest.json (spatial-capable). Derived from presence, never authored in a def. */
+  /** COMPONENTS and TEMPLATES: projected capability flag — true iff the folder carries a
+   *  manifest (offerable to the map by its switch). Derived from presence, never authored. */
   spatial?: boolean;
   /** Display icon URL (from the manifest; catalogs/drawers only). */
   icon?: string;
@@ -147,16 +153,6 @@ export interface UnoverseDefinition {
    *  ladder and arrival-scan order, from the manifest's `stateOrder`. First entry
    *  outranks all below it; no name is special. Absent → legacy recency semantics. */
   stateOrder?: string[];
-  /** THE LATCH, PER STATE (MCP guide §The Component Latch, moved here from the manifest
-   *  2026-08-31): the states whose wearer the conversation may be ADDRESSED AT, keyed by
-   *  state name. Compiled from each state's own `latch:` block and stamped beside
-   *  `stateOrder`, because states themselves are compiled away into `layouts`.
-   *
-   *  A state absent from this map can never hold the latch, so the SAME instance
-   *  retracted from its page state to an inline one drops the pill by construction —
-   *  which is the thing a manifest-level declaration could not say. `resolveLatch` reads
-   *  this map; nothing about the latch travels on the wire with a render. */
-  latches?: Record<string, { title: string; icon?: string }>;
   /** COMPONENTS (STATE_MODEL v2 §5 rule 2): the PUBLIC MENU — the top-level state
    *  names of the authored `state.view` tree, compiled at serve time. What hosts may
    *  place at spawn and templates may react to; nested substates never appear here. */

package/vendor/base/src/definitions/registry/agents.ts

@@ -0,0 +1,111 @@
+/**
+ * AGENTS, READ (docs.unoverse.ai/design/tasks; docs/unoverse/data/objects/elements/task.md, ruled 2026-09-06).
+ *
+ * An Agent is a workflow with no interface of its own, listed on the map so a conversation
+ * can reach for it. It is the ONE thing authored for the map alone: every other asset (a
+ * component, a template, an app) is offered to the map by its Available switch and keeps
+ * its meta on its own manifest, never written twice. One file per Agent:
+ *
+ *   design/<org>/agents/<name>.yaml   type: agent, the discovery meta, the door
+ *
+ * The door is a canvas in the org, its Input Trigger, and the node whose output is the
+ * result; all three, always. The face while it runs is the shared agent-card unless the
+ * file names another. The input schema is the trigger's, declared on the canvas.
+ *
+ * Like the identity reader beside it, this is NOT a definition kind: nothing here composes
+ * a UI tree. It only reads, so Studio can list and the registry lane can project.
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { listOrgs, projectDir } from "./homes.js";
+
+export const AGENT_CARD = "unoverse://components/agent-card";
+
+export interface AgentFile {
+  /** `<org>/<name>`: the identity every registry row and toggle keys on. */
+  name: string;
+  org: string;
+  /** The bare file name, which is also the tool's name on the wire. */
+  id: string;
+  title?: string;
+  description?: string;
+  whenToUse?: string;
+  /** What to do: the steps the Agent follows. Rides the tool description. */
+  instructions?: string;
+  /** The skills the Agent needs, by name. */
+  skills?: string[];
+  category?: string;
+  version?: string;
+  /** What the face says while the Agent runs. */
+  message?: string;
+  /** The face while it runs. Defaults to the shared agent-card. */
+  app: string;
+  /** The door. */
+  workflow?: string;
+  trigger?: string;
+  output?: string;
+  /** Where it lives, relative to design/<org>/. */
+  path: string;
+}
+
+/** design/<org>/agents/ */
+export const agentsDir = (root: string): string => join(root, "agents");
+
+const isDef = (f: string): boolean => /\.ya?ml$/.test(f) && !f.startsWith(".");
+
+/** One Agent file, by its bare name. Null when the file is missing or is not an Agent. */
+export function readAgent(root: string, org: string, id: string): AgentFile | null {
+  const dir = agentsDir(root);
+  const file = [join(dir, `${id}.yaml`), join(dir, `${id}.yml`)].find((f) => existsSync(f));
+  if (!file) return null;
+  const json = (parse(readFileSync(file, "utf8")) as Record<string, any>) ?? {};
+  if (json.type !== "agent") return null;
+  const str = (v: unknown): string | undefined => (typeof v === "string" && v.trim() ? v : undefined);
+  return {
+    name: `${org}/${id}`,
+    org,
+    id,
+    title: str(json.title),
+    description: str(json.description),
+    whenToUse: str(json.whenToUse),
+    instructions: str(json.instructions),
+    ...(Array.isArray(json.skills) ? { skills: json.skills.filter((x: unknown): x is string => typeof x === "string" && !!x.trim()) } : {}),
+    category: str(json.category),
+    version: str(json.version),
+    message: str(json.message),
+    app: str(json.app) ?? AGENT_CARD,
+    workflow: str(json.workflow),
+    trigger: str(json.trigger),
+    output: str(json.output),
+    path: `agents/${file.slice(dir.length + 1)}`,
+  };
+}
+
+/** Every Agent an org authored, sorted by name. */
+export function listAgentsIn(root: string, org: string): AgentFile[] {
+  const dir = agentsDir(root);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isFile() && isDef(e.name))
+    .map((e) => readAgent(root, org, e.name.replace(/\.ya?ml$/, "")))
+    .filter((a): a is AgentFile => a !== null)
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Every Agent across the workspace, or one org's. */
+export function listAgents(org?: string): AgentFile[] {
+  const orgs = org && org !== "all" ? [org] : listOrgs();
+  return orgs.flatMap((o) => listAgentsIn(projectDir(o), o));
+}
+
+/** An Agent by its qualified ref (`<org>/<name>`), the form every toggle and row carries. */
+export function loadAgent(ref: string): AgentFile | null {
+  const slash = ref.indexOf("/");
+  if (slash <= 0) return null;
+  const org = ref.slice(0, slash);
+  return readAgent(projectDir(org), org, ref.slice(slash + 1));
+}
+
+/** The door is three fields, always. */
+export const hasDoor = (a: AgentFile): boolean => Boolean(a.workflow && a.trigger && a.output);

package/vendor/base/src/definitions/registry/catalog.ts

@@ -100,8 +100,12 @@ export interface AppManifest {
    *  NOT `type`, which is the legacy full-surface/inline ROUTER word (`type: "template"`
    *  means a fluid-height app, and says nothing about where its definition lives). Two
    *  meanings on one field is how a template app would come to be loaded as a component and
-   *  fail with a resolver error nobody could read. */
-  kind?: "component" | "template";
+   *  fail with a resolver error nobody could read.
+   *
+   *  "app" joined the union when APPS started naming themselves as their own deliverable
+   *  (`loadAppManifest`): an app's definition lives in the app tier, so the same rule that
+   *  keeps a template from loading as a component keeps an app from doing it too. */
+  kind?: "component" | "template" | "app";
   /** Human display name; falls back to `name`. */
   title?: string;
   description?: string;
@@ -171,12 +175,6 @@ export interface AppManifest {
    *  the CONVERSATION (not the turn) so every re-call hydrates the same slice, and the
    *  client's new-turn reset skips it — it stays on screen until replaced or closed. */
   lifetime?: "turn" | "conversation";
-  /* NO `latch` HERE (moved 2026-08-31, MCP guide §The Component Latch). It was a manifest
-   * field seeded onto the slice with every render, which said one thing about a component
-   * for the whole of its life; a page is addressable when it is THE PAGE and not when it
-   * is a summary in the flow, and the state is what knows that. It is now declared on the
-   * app's state and compiled to `def.latches` — a fact the client looks up, not one the
-   * server has to send. */
   /** Workbench MOCK: what each STATE's preview seeds — `{ "<state>": ["course-card",
    *  "course-card"] }` (a repeated name = several instances, e.g. a card rail). The
    *  author decides per state; the seeded instances are written INTO that state's view
@@ -287,7 +285,24 @@ export function loadAppManifest(ref: string): AppManifest | null {
     m.autoTrigger === undefined && typeof m.binding?.autoTrigger === "boolean"
       ? { autoTrigger: m.binding.autoTrigger }
       : {};
-  return normalizeMode({ ...lifted, ...bindingAuto, ...m, id, org: hit.org, states: listStates("app", `${hit.org}/${id}`) });
+  // THE DELIVERABLE IS THE APP, and saying so is what lets a called app open.
+  // Both siblings below already default this to themselves (`loadComponentApp`,
+  // the template loader); the app loader never did, so `app.previewComponents?.[0]`
+  // was undefined and the app tool's whole render block — gated on that ref — was
+  // skipped. The call returned cleanly, nothing reached /stream, and the model told
+  // the person to use a surface that had never appeared (SAB sab-voice, 2026-09-07).
+  // `kind` rides along for the same reason it does on a template: the render path
+  // resolves the definition in the tier `kind` names, and an app is not a component.
+  return normalizeMode({
+    ...lifted,
+    ...bindingAuto,
+    ...m,
+    id,
+    org: hit.org,
+    kind: m.kind ?? "app",
+    previewComponents: m.previewComponents?.length ? m.previewComponents : [`${hit.org}/${id}`],
+    states: listStates("app", `${hit.org}/${id}`),
+  });
 }
 
 /** Load a COMPONENT as a native MCP app (UNOVERSE_MCP_APP_PROTOCOL §0.1 path B): a
@@ -352,9 +367,10 @@ export function loadTemplateApp(id: string, org?: string): AppManifest | null {
     // Template manifests carry `title`, never `name` (the folder is the name).
     name: m.name ?? m.title ?? lower,
     kind: "template",
-    // A DURABLE SURFACE by nature: a composed page is refined across turns, and every
-    // refinement must hydrate the same instance rather than stack a new page per message.
-    lifetime: m.lifetime ?? "conversation",
+    // TURN unless the manifest opts in (docs.unoverse.ai/design/state, "Arrival and
+    // lifetime"). A durable slice is exempt from the same-state replace, so a template
+    // defaulted durable was never replaced by the next arrival in its state.
+    lifetime: m.lifetime ?? "turn",
     // The deliverable IS this template — the render path resolves the definition from this
     // ref, in the tier `kind` names.
     previewComponents: m.previewComponents?.length ? m.previewComponents : [org ? `${org}/${lower}` : lower],

package/vendor/base/src/definitions/registry/datasetSql.ts

@@ -0,0 +1,149 @@
+/**
+ * A DATASET'S TABLE, AS SQL (docs/unoverse/data/objects/dataset.md, PROPOSED 2026-09-18).
+ *
+ * The declaration in an object's folder is the schema, so nobody writes SQL and nobody edits a
+ * schema by hand. This turns that declaration into a migration: a file a person reads, approves
+ * and can reverse. Nothing here runs anything.
+ *
+ * WHERE IT GOES. Beside the declaration, as `dataset.sql`, and never into the migrations folder:
+ * a dataset's table is made at publish by the platform's one door, and a file kept where the
+ * migration runner finds it would be a step someone has to run. This is what ran, written down,
+ * so a schema change can be read and compared and is never invisible.
+ *
+ * THE POLICIES ARE PART OF THE TABLE, not a later step. They are written in the same statement
+ * block, so a table cannot exist without them. A table created today and secured on Thursday is
+ * a table that was open until Thursday.
+ */
+import type { DatasetColumn, DatasetDefinition } from "./objects.js";
+
+/** What each declared type becomes. `number` is NUMERIC: exact decimal, never floating point,
+ *  so a total that must reconcile against a stated figure does not drift. */
+const SQL_TYPE: Record<string, string> = {
+  string: "TEXT",
+  number: "NUMERIC",
+  integer: "BIGINT",
+  date: "DATE",
+  datetime: "TIMESTAMPTZ",
+  boolean: "BOOLEAN",
+};
+
+/**
+ * THE TABLE A DATASET IS STORED IN. Built here, never taken from input, and never able to name a
+ * table the platform already owns: every one begins `dataset_`.
+ *
+ * THE ORG IS PART OF THE NAME. Two organisations may each declare an object called the same
+ * thing, with different columns, and without the org in the name the second would find the
+ * first's table already there and quietly write into it. A marketplace object, belonging to no
+ * org, keeps the bare name.
+ *
+ * The squeeze to letters, digits and underscores is what makes the name safe; it is also what
+ * would let "my-thing" and "my_thing" become one table, so the lint refuses two objects whose
+ * names arrive at the same table (rules.mjs).
+ */
+const squeeze = (s: string): string => s.replace(/[^a-z0-9]+/gi, "_").toLowerCase();
+export const tableNameOf = (object: string, org?: string | null): string =>
+  org ? `dataset_${squeeze(org)}_${squeeze(object)}` : `dataset_${squeeze(object)}`;
+
+// THE DESCRIPTION GOES ABOVE THE COLUMN, never after it: a trailing `-- comment` swallows the
+// comma that separates one column from the next, and the statement stops parsing.
+// A WORD THAT IS THE LANGUAGE IS CHECKED BY THE DATABASE. Without this, "exposure", "Exposure"
+// and "exposures" are three measures that never add up with each other, and nothing says so: the
+// rows are all there, and every total is quietly short. The list is quoted here and comes from a
+// declaration the lint already refused if it was malformed.
+const allowedList = (c: DatasetColumn): string =>
+  (c.enum ?? []).map((v) => `'${v.replace(/'/g, "''")}'`).join(", ");
+
+/**
+ * THE WORDS A COLUMN ALLOWS, as the database will hold them. Named here and nowhere else, so the
+ * table a migration makes and the table the one door brings forward are checked the same way: a
+ * check written twice is a check that drifts, and drift here is a word that passes in one table
+ * and is refused in another.
+ *
+ * EMPTY IS NOT A WORD, and that is the point: a column whose words are closed still takes nothing
+ * at all, so a reading we have no word for yet is kept with the document's own wording and no word
+ * of ours (dataset.md, "The language"). `IN` passes NULL of its own accord, which is why this does
+ * not have to say so.
+ */
+export const checkOf = (c: DatasetColumn): string | null =>
+  c.enum?.length ? `(${c.name} IN (${allowedList(c)}))` : null;
+
+/** What that check is called on a table. One name per column, so bringing it forward replaces it. */
+export const checkNameOf = (table: string, column: string): string => `chk_${table}_${column}`;
+
+/**
+ * ONE ROW PER THING MEASURED. The identity a declaration gives its rows, as the index that
+ * enforces it. NULLS ARE DISTINCT here, as Postgres has it by default: a row whose identity is
+ * partly unknown collides with nothing, and two readings we have no word for yet are two rows.
+ */
+export const uniqueIndexOf = (object: string, d: DatasetDefinition, org?: string | null): string | null => {
+  if (!d.uniqueBy?.length) return null;
+  const t = tableNameOf(object, org);
+  return `CREATE UNIQUE INDEX IF NOT EXISTS idx_${t}_item ON ${t} (COALESCE(org, ''), of_id, ${d.uniqueBy.join(", ")})`;
+};
+
+/** The columns that index is over, in order, as bare names: what it is compared against. */
+export const uniqueColumnsOf = (d: DatasetDefinition): string[] => ["org", "of_id", ...(d.uniqueBy ?? [])];
+
+const column = (c: DatasetColumn): string => {
+  const said = c.description ? `  -- ${c.description.replace(/\s+/g, " ")}\n` : "";
+  const only = checkOf(c) ? ` CHECK ${checkOf(c)}` : "";
+  return `${said}  ${c.name} ${SQL_TYPE[c.type]}${c.required ? " NOT NULL" : ""}${only}`;
+};
+
+/**
+ * The migration for one dataset. Idempotent: every statement is IF NOT EXISTS, so applying it
+ * again does nothing, which is what lets a migration be re-run safely after a failure.
+ */
+export function datasetMigration(object: string, d: DatasetDefinition, org?: string | null): string {
+  const t = tableNameOf(object, org);
+  const cols = d.columns.map(column).join(",\n");
+  const indexed = d.columns.filter((c) => c.indexed);
+  const lines: string[] = [];
+
+  lines.push(`-- THE ${object.toUpperCase()} DATASET (docs/unoverse/data/objects/dataset.md).`);
+  lines.push(`-- Generated from ${org ? `design/${org}` : "design"}/objects/${object}/dataset.yaml. Do not edit by hand:`);
+  lines.push(`-- edit the declaration and generate it again, so the folder and the database never disagree.`);
+  if (d.description) lines.push(`--\n-- ${d.description.replace(/\s+/g, " ")}`);
+  lines.push("");
+  lines.push(`CREATE TABLE IF NOT EXISTS ${t} (`);
+  lines.push(`  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),`);
+  lines.push(`  -- WHOSE IT IS, and what it belongs to. Not the author's to name, and not optional:`);
+  lines.push(`  -- these are what the access policies stand on and what makes a delete complete.`);
+  lines.push(`  org VARCHAR(64),`);
+  lines.push(`  of_id TEXT NOT NULL REFERENCES dictionary_need_states(universal_id) ON DELETE CASCADE,`);
+  lines.push(`  -- WHAT IT WAS READ FROM. A row outlives neither the thing it belongs to nor the`);
+  lines.push(`  -- document it came from: delete either and it goes, with no sweep to remember.`);
+  lines.push(`  document_id TEXT REFERENCES dictionary_need_states(universal_id) ON DELETE CASCADE,`);
+  lines.push(cols + ",");
+  lines.push(`  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),`);
+  lines.push(`  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()`);
+  lines.push(`);`);
+  lines.push("");
+  lines.push(`-- THE POLICY'S OWN COLUMNS ARE INDEXED, or the policy filters every row of every query.`);
+  lines.push(`CREATE INDEX IF NOT EXISTS idx_${t}_of ON ${t} (org, of_id);`);
+  lines.push(`CREATE INDEX IF NOT EXISTS idx_${t}_document ON ${t} (document_id);`);
+  for (const c of indexed) lines.push(`CREATE INDEX IF NOT EXISTS idx_${t}_${c.name} ON ${t} (${c.name});`);
+  const unique = uniqueIndexOf(object, d, org);
+  if (unique) {
+    lines.push("");
+    lines.push(`-- ONE ROW PER THING MEASURED: a read again replaces its rows rather than adding a second`);
+    lines.push(`-- set beside them, so a total never counts one reading twice.`);
+    lines.push(`${unique};`);
+  }
+  lines.push("");
+  lines.push(`-- ACCESS IS THE DATABASE'S, NEVER THE QUERY'S (dataset.md). A read function of an object`);
+  lines.push(`-- may be called by a component, and a component is a browser: a filter written inside`);
+  lines.push(`-- that function is one missed condition from leaking. A policy is not.`);
+  lines.push(`--`);
+  lines.push(`-- The context is set PER TRANSACTION (SET LOCAL), never per connection: with a pooler,`);
+  lines.push(`-- a setting that outlives its transaction hands the next request the last one's org.`);
+  lines.push(`-- And the application must not own this table: an owner ignores every policy silently.`);
+  lines.push(`ALTER TABLE ${t} ENABLE ROW LEVEL SECURITY;`);
+  lines.push(`ALTER TABLE ${t} FORCE ROW LEVEL SECURITY;`);
+  lines.push(`DROP POLICY IF EXISTS ${t}_org ON ${t};`);
+  lines.push(`CREATE POLICY ${t}_org ON ${t}`);
+  lines.push(`  USING (org IS NOT DISTINCT FROM NULLIF(current_setting('app.org', true), ''))`);
+  lines.push(`  WITH CHECK (org IS NOT DISTINCT FROM NULLIF(current_setting('app.org', true), ''));`);
+  lines.push("");
+  return lines.join("\n") + "\n";
+}

package/vendor/base/src/definitions/registry/homes.ts

@@ -9,7 +9,7 @@ import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { packagedDesignSystem } from "../dsPackage.js";
 import { defPath } from "../fsCache.js";
-import { NODES_HOME, DESIGN_HOME, INSTALLED_HOME, databaseOnly, designDir } from "../../paths.js";
+import { DESIGN_HOME, INSTALLED_HOME, databaseOnly, designDir } from "../../paths.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -63,8 +63,8 @@ const INSTALLED_DESIGN = designDir(INSTALLED_HOME);
  * or nodes, all of which are rows". A dead path that would silently adopt an npm tree if
  * one ever appeared is worse than no path. */
 const MARKETPLACE = join(DESIGN, "marketplace");
-const DS_BUNDLE_CANDIDATES = [join(NODES_HOME, "marketplace", "definitions")];
-function marketplaceDir(kind: "components" | "atoms" | "templates"): string {
+const DS_BUNDLE_CANDIDATES: string[] = [];
+function marketplaceDir(kind: "components" | "atoms" | "templates" | "objects" | "pipelines"): string {
   const onDisk = join(MARKETPLACE, kind);
   // Under the switch the authored tiers are skipped, so what a deployed universe would
   // resolve is what a developer resolves.
@@ -95,7 +95,15 @@ export const SHARED_DIR = {
   get template() {
     return marketplaceDir("templates");
   },
-} as Record<"component" | "atom" | "template", string>;
+  // `object` (2026-09-08): the kinds of thing that live on the map, docs/unoverse/data/objects/README.md.
+  get object() {
+    return marketplaceDir("objects");
+  },
+  // `pipeline` (2026-09-09): the source side of ingestion, docs/unoverse/data/pipelines/README.md layer 1.
+  get pipeline() {
+    return marketplaceDir("pipelines");
+  },
+} as Record<"component" | "atom" | "template" | "object" | "pipeline", string>;
 
 // rx-root entries that are NOT projects: the marketplace, the schema, and the legacy
 // orgs/ container itself. Everything else at the root is a flat project (the target model).
@@ -124,7 +132,8 @@ export function projectDir(name: string): string {
 export function listOrgs(): string[] {
   const isProject = (dir: string) =>
     existsSync(join(dir, "styles")) || existsSync(join(dir, "apps")) || existsSync(join(dir, "components")) ||
-    existsSync(join(dir, "templates"));
+    existsSync(join(dir, "templates")) || existsSync(join(dir, "agents")) ||
+    existsSync(join(dir, "objects")) || existsSync(join(dir, "identity")) || existsSync(join(dir, "pipelines"));
   const flat = existsSync(DESIGN) && !databaseOnly()
     ? readdirSync(DESIGN, { withFileTypes: true })
         .filter((e) => e.isDirectory() && !RESERVED_DESIGN.has(e.name) && isProject(join(DESIGN, e.name)))
@@ -178,6 +187,30 @@ export function templateDirs(refOrg: string | null): { org: string | undefined;
   return refOrg === null ? [shared, ...orgDirs] : [...orgDirs, shared];
 }
 
+/** The OBJECT homes a ref resolves against (docs/unoverse/data/objects/README.md): the same two
+ *  tiers as components, the marketplace (`design/marketplace/objects`, the platform's kinds,
+ *  and `need`, the atom every object extends) and the org packs (`design/<org>/objects`, an
+ *  org's own kinds). An org-qualified ref searches its org first, then the marketplace, so
+ *  `extends: need` resolves from an org's object; a bare ref searches the marketplace first. */
+export function objectDirs(refOrg: string | null): { org: string | undefined; dir: string }[] {
+  const shared = { org: undefined as string | undefined, dir: SHARED_DIR.object };
+  const orgDirs = (refOrg === null ? listOrgs() : [refOrg])
+    .filter((o) => existsSync(join(projectDir(o), "objects")))
+    .map((o) => ({ org: o as string | undefined, dir: join(projectDir(o), "objects") }));
+  return refOrg === null ? [shared, ...orgDirs] : [...orgDirs, shared];
+}
+
+/** The PIPELINE homes a ref resolves against (docs/unoverse/data/pipelines/README.md layer 1): the marketplace
+ *  (`design/marketplace/pipelines`, the sources everyone gets: website, spreadsheet, images) and
+ *  the org packs (`design/<org>/pipelines`, a source nobody else has). Same order as objects. */
+export function pipelineDirs(refOrg: string | null): { org: string | undefined; dir: string }[] {
+  const shared = { org: undefined as string | undefined, dir: SHARED_DIR.pipeline };
+  const orgDirs = (refOrg === null ? listOrgs() : [refOrg])
+    .filter((o) => existsSync(join(projectDir(o), "pipelines")))
+    .map((o) => ({ org: o as string | undefined, dir: join(projectDir(o), "pipelines") }));
+  return refOrg === null ? [shared, ...orgDirs] : [...orgDirs, shared];
+}
+
 /** The component homes a ref resolves against. Components live in TWO tiers: the
  *  marketplace (`rx/components`, generic, every org may use) and the org packs
  *  (`rx/orgs/<org>/components`, the client's own microapps — org-private). Names are
@@ -210,6 +243,37 @@ export function componentHit(dir: string, lower: string): boolean {
   return !!defPath(dir, lower) || !!defPath(join(dir, lower), lower);
 }
 
+/**
+ * WHOSE item this is, from the homes ALONE — nothing is parsed, expanded or compiled.
+ *
+ * A catalogue that is scoped to one org must never READ another org's items and drop
+ * them at the end: loading a definition expands its includes and inlines every Ref, and
+ * an app manifest opens its binding, so a universe carrying five clients paid five
+ * clients' worth of work to answer one client's question (the Content Library's Studio
+ * list, seen doing exactly that). This answers the only question the scope needs —
+ * whose is it — with a directory probe, so an out-of-scope item is skipped BEFORE it
+ * is read.
+ *
+ * Returns the owning org, `undefined` for the marketplace tier (everyone's), and `null`
+ * when no home carries the name: the caller must load it to find out, which is the same
+ * thing it did before.
+ */
+export function refOwnerOrg(kind: "component" | "template" | "app", ref: string): string | undefined | null {
+  const { org: refOrg, name } = parseRef(ref);
+  const lower = name.toLowerCase();
+  // An org-qualified ref already says whose it is, as long as the org is a real pack —
+  // a qualifier naming no org is a template-local part, which componentDirs resolves.
+  if (refOrg !== null && listOrgs().includes(refOrg)) return refOrg;
+  const dirs = kind === "app" ? appDirs(refOrg) : kind === "template" ? templateDirs(refOrg) : componentDirs(refOrg);
+  // Either authored form, plus the manifest-only folder an app may be.
+  const hits = dirs.filter(({ dir }) => componentHit(dir, lower) || !!defPath(join(dir, lower), "manifest"));
+  // The marketplace wins a bare name (an org may never shadow it), which is the
+  // precedence resolveComponentDirs applies; two orgs and no marketplace copy is
+  // ambiguous, and guessing here would hide an item from its owner.
+  if (hits.some((h) => h.org === undefined)) return undefined;
+  return hits.length === 1 ? (hits[0].org as string | undefined) : null;
+}
+
 /** The dirs a component ref may actually load from. Qualified refs pass through
  *  untouched. A bare ref narrows to the ONE home that carries the name: the CONTEXT
  *  org first when given (the org of the definition/app doing the asking — a cloned