@unoverse-platform/studio 0.1.97 → 0.1.99

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

@@ -0,0 +1,413 @@
+/**
+ * OBJECTS, READ (docs/unoverse/data/objects/README.md, ruled 2026-09-08).
+ *
+ * An object is a kind of thing that lives in the world: a need, a product, a purpose. Its
+ * definition is a folder in the one grammar,
+ *
+ *   objects/<name>/<name>.yaml     the envelope, as a node's node.yaml: type: object, name, extends,
+ *                                  the row keys, and the face (title, description, whenToUse,
+ *                                  category, version) plus the credentials and hosts its calls use
+ *   objects/<name>/props.yaml      this object's OWN fields, one prop each, every prop a brief;
+ *                                  a prop written from made detail says `from: <function>.<return>`
+ *   objects/<name>/api/make.yaml    the private make function, when it has one (README 4b)
+ *   objects/<name>/api/service.yaml the object's public functions by name (getDetail, searchDetail), as a
+ *                                  service node's tools; found by name, declared nowhere else
+ *
+ * in two tiers, the marketplace's (`design/marketplace/objects/`, shared by every org) and an
+ * org's own (`design/<org>/objects/`). `extends` names another object and is resolved here,
+ * across the tiers, never as a path: the base's props compose under the object's own, later
+ * keys over earlier. `need` is the atom every other positioned object extends (owner ruling
+ * 2026-09-08): a need's fields are what every row carries. An object with no embed never
+ * sits on the map.
+ *
+ * This module only reads. Studio authors, the platform reads.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { readDefCached, defPath } from "../fsCache.js";
+import { composeIncludes } from "../load/expand/includes.js";
+import { objectDirs } from "./homes.js";
+import { envelopeFindings, propsFindings, fromFindings, functionFindings, makeFindings, firstRefusal } from "../../lint/objects/rules.mjs";
+
+/** Refuse a folder with the linter's own sentence: one spelling of every rule (README 9a). */
+const refuse = (findings: ReturnType<typeof envelopeFindings>) => {
+  const msg = firstRefusal(findings);
+  if (msg) throw new Error(msg);
+};
+
+export interface ObjectProp {
+  type: string;
+  input: boolean;
+  description: string;
+  /** The made detail this prop is written from, `<function>.<return>`: `make` for api/make.yaml, or a function of api/service.yaml (README 4b). Absent: written from the thin item. */
+  from?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * ONE CALL OF A FUNCTION, in the node's own run.yaml grammar (README 4b; owner 2026-09-09
+ * "keep in line with the core nodes API"): `name`, the `node` it runs with that node's
+ * `config`, `when` to skip it, `for` to run it once per item of a list, `inputs` for what the
+ * node takes wired on a canvas (a model's content and schema), `optional` for a best-effort
+ * call whose failure the function survives.
+ */
+export interface ObjectCall {
+  name: string;
+  node?: string;
+  config: Record<string, unknown>;
+  when?: string;
+  for?: string;
+  inputs?: Record<string, unknown>;
+  optional?: boolean;
+  /**
+   * REMEMBERED, WHERE THE CALL KNOWS SOMETHING THE NODE CANNOT. A node declares whether its kind
+   * of answer may be reused; a general model call declares `false`, and rightly, because a
+   * prompt and a model are the caller's and may be anything.
+   *
+   * A CALL is narrower than its node. This one fixes the prompt, fixes the model, and hands it a
+   * PICTURE cut from a page that cannot change. Asking the same question of the same picture
+   * twice costs the same money and the same seconds for the same answer, and only the call's
+   * author is in a position to say so.
+   *
+   * So a call may declare its own memory, and it must name what makes its input the same input
+   * (`key`) - never simply `true`, because "this call is repeatable" is a claim about the
+   * INPUT, and a claim with nothing to point at is a hope.
+   */
+  cacheable?: { ignore?: string[]; key: string[] };
+}
+
+/**
+ * A LINE AN OBJECT DRAWS BETWEEN ITS OWN ROWS (docs/unoverse/data/objects/relationships-and-labels.md):
+ * rows of one folder whose `between` fields are equal are ordered by `order`, and each draws the
+ * line to the one just before it, when `when` holds for it. The engine knows no name.
+ */
+export interface ObjectLink {
+  type: "link" | "flow" | "tree";
+  /** Among rows of this object: the fields whose equal values make one line of rows. Absent on a line to another object. */
+  between?: string[];
+  /** The field the rows are put in order by, each drawing its line to the one before it. Absent on a line to another object. */
+  order?: string;
+  when?: string;
+  /** A LINE TO ANOTHER OBJECT (relationships-and-labels.md, 2026-09-15): the object it points at... */
+  to?: string;
+  /** ...and which of this row's fields names which of that row's: `{ manager: legalName }`. One pair. */
+  match?: Record<string, string>;
+  /** Fields (of `between`, or the row's side of `match`) whose values may name one thing several ways: one question per set of names says which are the same. */
+  alike?: string[];
+}
+
+/**
+ * A COLUMN OF A DATASET (dataset.md, "the declaration is the schema"). The same words a prop
+ * uses, so an author learns one grammar: a name, a type, whether it must be there, and whether
+ * it is searched by. A number is a real numeric column and not a field of a JSON document, so a
+ * sum is a sum and a value that is not a number is refused at the door.
+ */
+export interface DatasetColumn {
+  name: string;
+  /** THE ONLY VALUES IT MAY HOLD. A column that IS the language (a measure, a unit, a side) says
+   *  its words here and the database refuses the rest: a misspelling cannot become a second
+   *  thing that never sums with the first. Absent on a column carrying a document's own words. */
+  enum?: string[];
+  /** string | number | integer | date | datetime | boolean. Nothing else: a type this does not
+   *  name is one the generated table cannot promise anything about. */
+  type: string;
+  required?: boolean;
+  /** Searched or grouped by, so the generated table indexes it. */
+  indexed?: boolean;
+  description?: string;
+}
+
+export interface DatasetDefinition {
+  columns: DatasetColumn[];
+  /** Columns that together identify one row, so a read again replaces rather than duplicates. */
+  uniqueBy?: string[];
+  /**
+   * WHICH COLUMN SAYS WHOSE THESE ROWS ARE, and which says when they speak as of. The one row a
+   * dataset leaves on the map is titled from them, and until 2026-09-20 the engine simply read
+   * the columns named "fund" and "as_of": one organisation's words, inside the platform. A
+   * dataset that names neither gets a handle titled by its document, which is always true.
+   */
+  subject?: string;
+  asOf?: string;
+  description?: string;
+}
+
+export interface ObjectFunction {
+  description?: string;
+  /** What it takes when called from outside, as a JSON schema (README 4b): the Agent's tool arguments beside the row's universal_id. */
+  input?: Record<string, unknown>;
+  calls: ObjectCall[];
+  /** `{{ }}` references or `return` expressions over `row`, `calls` and `item`; a string or a record of them. */
+  returns?: unknown;
+  /** True when every call names a node: the engine runs this from the file. */
+  runnable: boolean;
+  /**
+   * Callable from outside, by an Agent in Spatial or a component (docs/unoverse/data/objects/README.md
+   * 4b): true for a function of api/service.yaml, false for `make`, the private api/make.yaml. The
+   * file is the switch; nothing inside a function says who may call it.
+   */
+  offered: boolean;
+}
+
+/**
+ * THE KEYS AN OBJECT IS KNOWN BY, in order of trust (README 4a, 2026-09-15): a flat list is
+ * one key of one or more fields; a list of lists is several keys, tried first to last.
+ */
+export function identityKeysOf(uniqueBy: string[] | string[][] | null | undefined): string[][] {
+  if (!Array.isArray(uniqueBy) || !uniqueBy.length) return [];
+  return Array.isArray(uniqueBy[0]) ? (uniqueBy as string[][]).filter((k) => Array.isArray(k) && k.length > 0) : [uniqueBy as string[]];
+}
+
+export interface ObjectDefinition {
+  /** The object type, as a row's `object_type` names it. */
+  name: string;
+  /** The org that owns it; undefined for a marketplace object. */
+  org?: string;
+  /** The base it extends, by name. */
+  extends?: string;
+  /** Which fields make two rows the same one: one key (a list of fields), or several keys tried in order (a list of lists; README 4a). Absent on an object that is never a row. */
+  uniqueBy?: string[] | string[][];
+  /** The fields whose text makes the vector. Absent on an object that is never a row. */
+  embed?: string[];
+  /** What a search hit carries; the rest comes with getDetail. `all` = the row whole. */
+  search?: string[] | "all";
+  /** The stored `object_type` when it differs from the name (interface rows are stored as mcp). */
+  storedAs?: string;
+  /** The interface every row of this object wears, as unoverse://components/<org>/<name>; stamped on the row at save when the row has none (README 4a). */
+  app?: string;
+  /** The glyph every row of this object is drawn with, a lucide icon name in kebab-case (`file-text`); the base's unless the object says its own. */
+  icon?: string;
+  /** Which of the twelve elements this object IS (README 4a): product, content, task, ... A classification, never a shape; not inherited. */
+  element?: string;
+  meta?: "open";
+  /** The lines it draws between its own rows, by name (README 7; relationships-and-labels.md). */
+  links?: Record<string, ObjectLink>;
+  /** THE TABLE THIS OBJECT OWNS (docs/unoverse/data/objects/dataset.md, PROPOSED 2026-09-18),
+   *  from its folder's table.yaml: an object that holds many small facts read together rather
+   *  than one row read alone. Absent on every ordinary object, which stays a row. */
+  dataset?: DatasetDefinition;
+  /** Every prop, the base's composed under this object's own. */
+  props: Record<string, ObjectProp>;
+  /** The props this object declares itself, without its base's. */
+  ownProps: Record<string, ObjectProp>;
+  /** The face, read from the envelope: what this is and when an Agent reaches for it. */
+  manifest: {
+    title?: string; description?: string; whenToUse?: string; category?: string; version?: string;
+    allowedHosts?: string[];
+    credentials?: string[];
+  };
+  /** The functions by name (docs/unoverse/data/objects/README.md 4b): `make` from api/make.yaml, and api/service.yaml's own (getDetail, searchDetail). */
+  api: string[];
+  functions: Record<string, ObjectFunction>;
+  /** The folder on disk. */
+  dir: string;
+}
+
+// NO RESULT MAP (2026-09-09). The files are the one shared place, and `readDefCached`
+// already knows when one changed (its mtime). A map of composed results above it remembered
+// a definition until the process restarted: a publish or an edit was not seen. Composing an
+// object again is a few stat calls; the freshness check IS the cache.
+
+function folderOf(name: string, org?: string | null): { dir: string; org?: string } | null {
+  for (const { org: o, dir } of objectDirs(org ?? null)) {
+    const folder = join(dir, name);
+    if (existsSync(folder) && statSync(folder).isDirectory() && defPath(folder, name)) return { dir: folder, org: o };
+  }
+  return null;
+}
+
+// THE TYPES A DATASET COLUMN MAY BE, and nothing else: a type this does not name is one the
+// generated table can promise nothing about, and a promise is the whole point of having columns
+// rather than a JSON field. `number` is DECIMAL and never floating point (dataset.md): a total
+// that must reconcile against a stated figure drifts under binary floating point, and the drift
+// grows with the number of rows.
+const DATASET_TYPES = new Set(["string", "number", "integer", "date", "datetime", "boolean"]);
+
+// A COLUMN NAME IS A PLAIN WORD. Lower case, letters, digits and underscores, starting with a
+// letter. Nothing that has to be quoted, nothing that could be read as anything but a name, and
+// nothing that collides with what the platform puts on every dataset itself.
+const COLUMN_NAME = /^[a-z][a-z0-9_]*$/;
+const RESERVED = new Set(["id", "org", "of", "document", "created_at", "updated_at"]);
+
+/** The table an object owns, from its folder's table.yaml, refused when it says anything the
+ *  generated table could not keep (README 4f; dataset.md). */
+export function readDataset(name: string, file: Record<string, any>, dir: string): DatasetDefinition {
+  const findings: string[] = [];
+  const raw = Array.isArray(file.columns) ? file.columns : [];
+  if (!raw.length) findings.push("table.yaml names no columns; a dataset is its columns");
+  const columns: DatasetColumn[] = [];
+  const seen = new Set<string>();
+  for (const c of raw) {
+    const col = String(c?.name ?? "").trim();
+    const type = String(c?.type ?? "").trim();
+    if (!COLUMN_NAME.test(col)) findings.push(`column "${col}": a name is lower case letters, digits and underscores, starting with a letter`);
+    else if (RESERVED.has(col)) findings.push(`column "${col}" is one the platform puts on every dataset itself (${[...RESERVED].join(", ")})`);
+    else if (seen.has(col)) findings.push(`column "${col}" is declared twice`);
+    else seen.add(col);
+    if (!DATASET_TYPES.has(type)) findings.push(`column "${col}": type "${type}" is not one of ${[...DATASET_TYPES].join(", ")}`);
+    const allowed = Array.isArray(c?.enum) ? c.enum.map((v: unknown) => String(v)) : undefined;
+    // A LIST OF ALLOWED VALUES ONLY MEANS ANYTHING FOR A WORD. A number or a date is already
+    // constrained by its type, and a list of allowed numbers is a rule about the world, not
+    // about the column.
+    if (allowed && type !== "string") findings.push(`column "${col}": only a string column may say which values it allows`);
+    if (allowed && new Set(allowed).size !== allowed.length) findings.push(`column "${col}": its allowed values repeat`);
+    columns.push({ name: col, type, ...(allowed ? { enum: allowed } : {}), ...(c?.required === true ? { required: true } : {}), ...(c?.indexed === true ? { indexed: true } : {}), ...(c?.description ? { description: String(c.description) } : {}) });
+  }
+  const uniqueBy = Array.isArray(file.uniqueBy) ? file.uniqueBy.map((u: unknown) => String(u)) : undefined;
+  for (const u of uniqueBy ?? []) if (!seen.has(u) && !RESERVED.has(u)) findings.push(`uniqueBy names "${u}", which is not a column`);
+  if (findings.length) throw new Error(`object ${name}: ${findings.join("; ")} (${dir})`);
+  return { columns, ...(uniqueBy ? { uniqueBy } : {}), ...(file.description ? { description: String(file.description) } : {}) };
+}
+
+function readFolder(dir: string, name: string, org: string | undefined, seen: string[]): ObjectDefinition {
+  const envelope = composeIncludes(readDefCached<Record<string, any>>(defPath(dir, name)!), dir) as Record<string, any>;
+  refuse(envelopeFindings(name, envelope).map((f) => ({ ...f, msg: `${f.msg} (${dir})` })));
+  const manifest = envelope as Record<string, any>;
+  // THE TABLE IT OWNS, when it owns one (dataset.md). Absent on every ordinary object.
+  // The file is `dataset.yaml` and never `table.yaml`: an object may be NAMED table, and its own
+  // envelope is objects/table/table.yaml, which a declaration file of that name would shadow.
+  const datasetPath = defPath(dir, "dataset");
+  const dataset = datasetPath && datasetPath !== defPath(dir, name)
+    ? readDataset(name, readDefCached<Record<string, any>>(datasetPath) ?? {}, dir)
+    : undefined;
+  const servicePath = join(dir, "api", "service.yaml");
+  const service = existsSync(servicePath) ? (readDefCached<Record<string, any>>(servicePath) ?? {}) : {};
+  // THE PRIVATE MAKE FUNCTION (README 4b, 2026-09-14): api/make.yaml is one function, `make`, run
+  // only by the pipeline; api/service.yaml holds what may be called from outside.
+  const makePath = join(dir, "api", "make.yaml");
+  const make = existsSync(makePath) ? readDefCached<Record<string, any>>(makePath) : undefined;
+  refuse(makeFindings(name, make, service).map((f) => ({ ...f, msg: `${f.msg} (${dir})` })));
+  // THE BASE, FIRST (objects README 5, "Inheritance is whole", 2026-09-13): an object that
+  // extends another inherits its fields, its functions, its lines and its row keys, and a prop
+  // may be written from an inherited function, so the base is known before the props are.
+  let parent: ObjectDefinition | null = null;
+  if (envelope.extends) {
+    const base = String(envelope.extends);
+    const chain = [...seen, name];
+    if (chain.includes(base)) throw new Error(`object ${name}: extends cycle ${[...chain, base].join(" -> ")}`);
+    parent = readObject(base, org, chain);
+    if (!parent) throw new Error(`object ${name}: extends "${base}", which no tier holds`);
+  }
+  const functions: Record<string, ObjectFunction> = { ...(parent?.functions ?? {}) };
+  for (const fn of Object.keys(service)) functions[fn] = readFunction(name, fn, service[fn], true);
+  if (make != null) functions.make = readFunction(name, "make", make, false);
+  const api = Object.keys(functions);
+  // What `from` is checked against: the object's own functions over the ones it inherits.
+  const callable: Record<string, unknown> = { ...Object.fromEntries(Object.entries(parent?.functions ?? {}).map(([k, f]) => [k, { returns: (f as { returns?: unknown }).returns ?? {} }])), ...service, ...(make != null ? { make } : {}) };
+  const ownProps: Record<string, ObjectProp> = {};
+  for (const [k, p] of Object.entries((envelope.props ?? {}) as Record<string, any>)) {
+    ownProps[k] = { ...(p ?? {}), type: String(p?.type ?? "string"), input: p?.input === true, description: String(p?.description ?? "") };
+    // THE PROP PULLS THE FUNCTION: `from` names a function of this object (`make`, or api/service.yaml's)
+    // and a key of its returns. A prop that asks for detail no function makes is a lie the
+    // folder tells, and the object does not load.
+    if (p?.from != null) refuse(fromFindings(name, k, p.from, callable));
+  }
+  let props: Record<string, ObjectProp> = {};
+  let inheritedIcon: string | undefined;
+  if (parent) {
+    const base = String(envelope.extends);
+    inheritedIcon = parent.icon;
+    // RE-BRIEF (README 5): an object may say its own brief for a field it inherits, and
+    // nothing else about it. A product's title is the offering's name, not the need's outcome.
+    refuse(propsFindings(name, envelope.props ?? {}, parent.props, base));
+    for (const [k, p] of Object.entries(ownProps)) {
+      if (!(k in parent.props)) continue;
+      ownProps[k] = { ...parent.props[k], description: p.description };
+    }
+    props = { ...parent.props };
+  }
+  props = { ...props, ...ownProps };
+  // ITS LINES name only its own fields: a line grouped or ordered by a field the object does
+  // not have could never be drawn, and the object does not load.
+  const links = { ...(parent?.links ?? {}), ...((envelope.links ?? {}) as Record<string, ObjectLink>) } as Record<string, ObjectLink>;
+  for (const [ln, l] of Object.entries(links ?? {})) {
+    const mine = l?.to ? Object.keys(l.match ?? {}) : [...(l?.between ?? []), l?.order];
+    for (const f of mine) if (typeof f === "string" && !(f in props)) throw new Error(`object ${name}: link ${ln} names the field "${f}", which the object does not have (${dir})`);
+    for (const f of l?.alike ?? []) if (!mine.includes(f)) throw new Error(`object ${name}: link ${ln}: alike names "${f}", which is not one of its ${l?.to ? "match" : "between"} fields (${dir})`);
+  }
+  return {
+    name,
+    ...(org ? { org } : {}),
+    ...(envelope.extends ? { extends: String(envelope.extends) } : {}),
+    ...(envelope.uniqueBy ? { uniqueBy: envelope.uniqueBy as string[] | string[][] } : parent?.uniqueBy ? { uniqueBy: parent.uniqueBy } : {}),
+    ...(envelope.embed ? { embed: envelope.embed as string[] } : parent?.embed ? { embed: parent.embed } : {}),
+    ...(envelope.search ? { search: envelope.search } : parent?.search ? { search: parent.search } : {}),
+    ...(envelope.storedAs ? { storedAs: String(envelope.storedAs) } : {}),
+    ...(typeof envelope.app === "string" && envelope.app ? { app: envelope.app } : {}),
+    ...(typeof envelope.icon === "string" && envelope.icon ? { icon: envelope.icon } : inheritedIcon ? { icon: inheritedIcon } : {}),
+    ...(typeof envelope.element === "string" && envelope.element ? { element: envelope.element } : parent?.element ? { element: parent.element } : {}),
+    ...(envelope.meta ? { meta: envelope.meta } : parent?.meta ? { meta: parent.meta } : {}),
+    ...(links && Object.keys(links).length ? { links } : {}),
+    ...(dataset ? { dataset } : {}),
+    props,
+    ownProps,
+    manifest: {
+      title: manifest.title, description: manifest.description, whenToUse: manifest.whenToUse, category: manifest.category, version: manifest.version,
+      ...(Array.isArray(manifest.allowedHosts) ? { allowedHosts: manifest.allowedHosts } : {}),
+      ...(Array.isArray(manifest.credentials) ? { credentials: manifest.credentials } : {}),
+    },
+    api,
+    functions,
+    dir,
+  };
+}
+
+/**
+ * A function as the file declares it (README 4b): `calls` in the node's grammar, `returns`.
+ * The rules are the linter's (lint/objects/rules.mjs functionFindings): never `steps`, a
+ * name and a node per call, unique names, `for` and `when` strings. Refused here with the
+ * same sentence the linter prints.
+ */
+function readFunction(object: string, fn: string, raw: unknown, offered: boolean): ObjectFunction {
+  refuse(functionFindings(object, fn, raw));
+  const f = raw as Record<string, any>;
+  const list: any[] = Array.isArray(f.calls) ? f.calls : [];
+  const calls: ObjectCall[] = list.map((c: any) => {
+    const config = c.config != null && typeof c.config === "object" && !Array.isArray(c.config) ? c.config : {};
+    const inputs = c.inputs != null && typeof c.inputs === "object" && !Array.isArray(c.inputs) ? { inputs: c.inputs } : {};
+    // WHAT THE CALL SAYS ABOUT BEING REMEMBERED (ObjectCall.cacheable). Kept only when it names
+    // what makes its input the same input: a declaration with no `key` is not a declaration, and
+    // a call that cannot say why it is repeatable must not be treated as though it had.
+    const cacheable = c.cacheable && typeof c.cacheable === "object" && Array.isArray((c.cacheable as any).key) && (c.cacheable as any).key.length
+      ? { ...((c.cacheable as any).ignore ? { ignore: ((c.cacheable as any).ignore as unknown[]).map(String) } : {}), key: ((c.cacheable as any).key as unknown[]).map(String) }
+      : null;
+    return { name: c.name, ...(typeof c.node === "string" ? { node: c.node } : {}), config, ...(typeof c.when === "string" ? { when: c.when } : {}), ...(typeof c.for === "string" ? { for: c.for } : {}), ...inputs, ...(c.optional === true ? { optional: true } : {}), ...(cacheable ? { cacheable } : {}) };
+  });
+  return {
+    ...(typeof f.description === "string" ? { description: f.description } : {}),
+    ...(f.input && typeof f.input === "object" && !Array.isArray(f.input) ? { input: f.input as Record<string, unknown> } : {}),
+    calls,
+    ...(f.returns != null ? { returns: f.returns } : {}),
+    runnable: calls.every((c) => typeof c.node === "string"),
+    offered,
+  };
+}
+
+/** One object by name, the org's tier first then the marketplace. Null when no tier holds it. */
+export function readObject(name: string, org?: string | null, seen: string[] = []): ObjectDefinition | null {
+  const hit = folderOf(name, org);
+  return hit ? readFolder(hit.dir, name, hit.org, seen) : null;
+}
+
+/** Every object an org can see: the marketplace's and its own. Bare (no org) lists the marketplace's plus every org's. */
+export function listObjects(org?: string | null): ObjectDefinition[] {
+  const out: ObjectDefinition[] = [];
+  const seen = new Set<string>();
+  for (const { org: o, dir } of objectDirs(org ?? null)) {
+    if (!existsSync(dir)) continue;
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (!e.isDirectory() || e.name.startsWith(".")) continue;
+      const key = `${o ?? ""}/${e.name}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const def = readObject(e.name, o ?? null);
+      if (def) out.push(def);
+    }
+  }
+  return out;
+}
+
+/** The objects that are rows: those with an `embed`. */
+export function rowObjects(org?: string | null): ObjectDefinition[] {
+  return listObjects(org).filter((o) => Array.isArray(o.embed));
+}

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

@@ -1,18 +1,25 @@
 /**
- * THE ORG'S IDENTITY DOCUMENTS, READ (docs/unoverse/UNOVERSE_ORGANISATION.md section 5).
+ * THE ORG'S IDENTITY DOCUMENTS, READ (docs/unoverse/data/objects/README.md section 6, ruled
+ * 2026-09-08; UNOVERSE_ORGANISATION.md section 5).
  *
- * Four definitions in design/<slug>/identity/, each a folder like a component's:
+ * Four objects in the marketplace pack say the SHAPE, brief by brief:
  *
- *   identity/<doc>/manifest.yaml   title, description, whenToUse, category, version
- *   identity/<doc>/<doc>.yaml      type: identity, props: each with its brief and its default
+ *   design/marketplace/objects/<doc>/   organisation, brand, purpose, story
  *
- * The defaults ARE the document: this org's own words. The briefs are the instructions a
- * writer (an Agent with the create skill, or a person) follows to fill them. This module
- * only reads; Studio authors, the platform renders. Nothing here writes a byte.
+ * and the org's pack holds its ANSWERS, one instance a file, in the one grammar:
+ *
+ *   design/<slug>/identity/<doc>.yaml   type: identity, extends: <doc>, props with `default` only
+ *
+ * The instance carries nothing but defaults: the briefs, the limits, the item shapes and the
+ * manifest are the object's. This module composes the two into what every reader has always
+ * had, the props with their briefs and their values, and the manifest words. It only reads;
+ * Studio authors, the platform renders. `instanceText` is the one serializer, used by the
+ * pack writer and the Studio scaffold so a new org and a new project start identical.
  */
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { parse } from "yaml";
+import { basename, join } from "node:path";
+import { parse, stringify } from "yaml";
+import { readObject, type ObjectDefinition } from "./objects.js";
 
 export const ORG_DOCUMENTS = ["organisation", "brand", "purpose", "story"] as const;
 export type OrgDocument = (typeof ORG_DOCUMENTS)[number];
@@ -20,11 +27,11 @@ export type OrgDocument = (typeof ORG_DOCUMENTS)[number];
 export interface IdentityProp {
   name: string;
   type: string;
-  /** The brief: what belongs in the field, as direction to a writer. */
+  /** The brief: what belongs in the field, as direction to a writer. From the object. */
   description: string;
   maxLength?: number;
   maxItems?: number;
-  /** The org's own words, as they stand. */
+  /** The org's own words, as they stand. From the instance. */
   default: unknown;
 }
 
@@ -34,34 +41,67 @@ export interface IdentityDocument {
   props: IdentityProp[];
   /** prop name -> default, the document as a plain object. */
   values: Record<string, unknown>;
-  /** Where it lives in the pack, relative to design/<slug>/. */
+  /** Where the instance lives in the pack, relative to design/<slug>/. */
   path: string;
 }
 
-/** design/<slug>/identity/<doc>/ */
-export const identityDir = (root: string, doc: OrgDocument): string => join(root, "identity", doc);
+/** design/<slug>/identity/ */
+export const identityDir = (root: string): string => join(root, "identity");
+
+/** The object a document is an instance of: the marketplace's, or the org's own override of it. */
+export function identityObject(doc: OrgDocument, org?: string | null): ObjectDefinition | null {
+  return readObject(doc, org ?? null);
+}
+
+/** The props a writer fills: the object's own, `input: true` ones. Engine-assigned fields (whenToUse) are not the document's. */
+function writable(object: ObjectDefinition): Array<[string, ObjectDefinition["ownProps"][string]]> {
+  return Object.entries(object.ownProps).filter(([, p]) => p.input);
+}
+
+/** An empty value for a prop: an empty list for an array, an empty string otherwise. */
+export const emptyValue = (type: string): unknown => (type === "array" ? [] : "");
+
+/**
+ * The instance file's text for a document with these values (missing values empty). The one
+ * serializer: the org pack writer, the Studio scaffold and any regeneration go through it.
+ */
+export function instanceText(doc: OrgDocument, values: Record<string, unknown> = {}, org?: string | null): string {
+  const object = identityObject(doc, org);
+  if (!object) throw new Error(`identity/${doc}: no object named ${doc} in any tier`);
+  const props: Record<string, { default: unknown }> = {};
+  for (const [name, p] of writable(object)) props[name] = { default: name in values ? values[name] : emptyValue(p.type) };
+  const head = `# The org's ${doc}: its own words, and only those. The briefs, the limits and the shape are the\n# ${doc} object's (design/marketplace/objects/${doc}/); this file carries the answers as defaults.\n`;
+  return head + stringify({ unoverse: "1.0", type: "identity", extends: doc, props }, { lineWidth: 100 });
+}
 
-/** One identity definition as the pack holds it. Null when the folder is missing. */
+/** One identity document as the pack holds it, composed with its object. Null when the instance is missing. */
 export function readOrgDocument(root: string, doc: OrgDocument): IdentityDocument | null {
-  const dir = identityDir(root, doc);
-  const file = join(dir, `${doc}.yaml`);
+  const file = join(identityDir(root), `${doc}.yaml`);
   if (!existsSync(file)) return null;
-  const definition = (parse(readFileSync(file, "utf8")) as Record<string, any>) ?? {};
-  const manifestFile = join(dir, "manifest.yaml");
-  const manifest = existsSync(manifestFile) ? ((parse(readFileSync(manifestFile, "utf8")) as Record<string, any>) ?? {}) : {};
-  const props: IdentityProp[] = Object.entries((definition.props ?? {}) as Record<string, any>).map(([name, p]) => ({
+  const org = basename(root);
+  const object = identityObject(doc, org);
+  if (!object) throw new Error(`identity/${doc}.yaml: no object named ${doc} in any tier`);
+  const instance = (parse(readFileSync(file, "utf8")) as Record<string, any>) ?? {};
+  if (instance.type !== "identity") throw new Error(`${file}: type must be identity`);
+  if (instance.extends !== doc) throw new Error(`${file}: extends must be ${doc}`);
+  const given = (instance.props ?? {}) as Record<string, { default?: unknown }>;
+  for (const k of Object.keys(given)) {
+    if (!(k in object.ownProps) || !object.ownProps[k].input) throw new Error(`${file}: "${k}" is not a field of ${doc} a writer fills`);
+    for (const key of Object.keys(given[k] ?? {})) if (key !== "default") throw new Error(`${file}: "${k}" carries "${key}"; an instance prop carries default only, the brief is the object's`);
+  }
+  const props: IdentityProp[] = writable(object).map(([name, p]) => ({
     name,
-    type: String(p?.type ?? "string"),
-    description: String(p?.description ?? ""),
-    ...(p?.maxLength != null ? { maxLength: Number(p.maxLength) } : {}),
-    ...(p?.maxItems != null ? { maxItems: Number(p.maxItems) } : {}),
-    default: p?.default,
+    type: p.type,
+    description: p.description,
+    ...(p.maxLength != null ? { maxLength: Number(p.maxLength) } : {}),
+    ...(p.maxItems != null ? { maxItems: Number(p.maxItems) } : {}),
+    default: name in given ? given[name]?.default : emptyValue(p.type),
   }));
   return {
-    manifest: { title: manifest.title, description: manifest.description, whenToUse: manifest.whenToUse, category: manifest.category, version: manifest.version },
-    definition: { type: definition.type, name: definition.name, category: definition.category },
+    manifest: object.manifest,
+    definition: { type: "identity", name: doc, category: object.manifest.category },
     props,
     values: Object.fromEntries(props.map((p) => [p.name, p.default])),
-    path: `identity/${doc}/${doc}.yaml`,
+    path: `identity/${doc}.yaml`,
   };
 }

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

@@ -15,12 +15,14 @@
  *     styles/themes/      brand themes seeded from the marketplace foundation; base and
  *                         semantic tokens are INHERITED at resolve time (an org is a theme)
  *
- * Shapes: each definition declares its own props with their briefs (identitySeed.ts). Nothing is
- * invented: the defaults are empty until a writer fills them from the org's own sources.
+ * Shapes (ruled 2026-09-08): each identity file is an INSTANCE of its marketplace object
+ * (design/marketplace/objects/<doc>/), the one grammar with `extends: <doc>` and props
+ * carrying `default` only. The briefs are the object's. Nothing is invented: the defaults
+ * are empty until a writer fills them from the org's own sources.
  */
 import { cpSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { IDENTITY_SEED } from "./identitySeed.js";
+import { join } from "node:path";
+import { ORG_DOCUMENTS, instanceText } from "./orgDocuments.js";
 
 export const ORG_SLUG = /^[a-z][a-z0-9-]{0,63}$/;
 
@@ -39,12 +41,10 @@ export function createOrgPack(designHome: string, slug: string, name: string): s
   mkdirSync(join(dest, "components"), { recursive: true });
   mkdirSync(join(dest, "identity"), { recursive: true });
   cpSync(themes, join(dest, "styles", "themes"), { recursive: true });
-  // THE IDENTITY SEED: four definitions, briefs written, defaults empty (identitySeed.ts,
-  // mirrored by the Studio scaffold's sample-identity). The name is the org row's, not the
-  // document's: the writer fills `name` from the organisation's own site.
-  for (const [rel, text] of Object.entries(IDENTITY_SEED)) {
-    mkdirSync(dirname(join(dest, "identity", rel)), { recursive: true });
-    writeFileSync(join(dest, "identity", rel), text);
-  }
+  // THE IDENTITY: four instances, defaults empty, written by the one serializer the Studio
+  // scaffold's sample-identity is generated with, so a new org and a new project start
+  // identical. The name is the org row's, not the document's: the writer fills `name` from
+  // the organisation's own site.
+  for (const doc of ORG_DOCUMENTS) writeFileSync(join(dest, "identity", `${doc}.yaml`), instanceText(doc));
   return dest;
 }