Comprise OES

Edition 0.7.0 · revised 2026-11-13 · cosmoes.org home: https://comprise.cosmoes.org/

This edition describes the comprise/1 MiniCOSM: a catalog declaring oes: comprise/1, with P files headed cosm: 0.3, the isotype comprise-isotype/0, the outside chart comprise-paratype/0, the backup comprise-bundle/0, and the sealed package as a thym/1 package.

Comprise OES is the MiniCOSM for companies: the format of a Holotype, one company described in plain-text .cosm files that are at once a file system and a relational database. Every part of the company the format knows (its legal bodies, roles, markets, products, representations, inventories, systems and people) has a place in both readings.

A MiniCOSM is a domain's OES with a specification of its own, and there are two: Comprise OES, for companies, and Ascribe, for a person. Both are written in MacroCOSM OES (https://macro.cosmoes.org/), an OES: the shared grammar and its core, which holds the formats built into every reader, the densities and the dialectic, the one way of asking a person what a source means. Thym (https://thym.cosmoes.org/), the transcognition language that connects OESes, is the language of the programs this text names.

Comprise OES replaces COSM 0.3, the earlier specification of the product tree, as the description of the format; COSM 0.3's product tree is chapter P below, whole. Where this specification sits among the OES specifications, and why any of them exists, is said at https://cosmoes.org/.

Status. Normative. Comprise OES is stewarded by Verroes (Graham Smith). Comprise, the product, is the reference implementation: its reader and writer read and write this format, and the python -m core … lines quoted in this text are its command line, given as examples of how a check is run, never as the rule. Where an implementation and this text disagree, one of them is in error; the Changes appendix (section 14) records which was corrected. Not checked marks a rule the checks do not enforce (section 13.3).

The format does not change. A Comprise OES file is a .cosm file: the COSM YAML subset (section 2.5) and, for sketches, the one-line shorthand (P.6), exactly as Holotypes were written before the format had a name. comprise/1 names the format and maps it; it adds one line to the catalog (section 2.3) and one way to address things (section 6). Every Holotype written before the declaration existed is a comprise/1 Holotype as it stands.

Contents

1. The map: a file system that is also a relational database
2. The volume
3. Concerns and relationships
4. The envelope
5. The eight modules
6. Paths
7. References
8. Open questions
9. Checks
10. Versions
11. The private/public split
12. Renderers
13. Conformance
14. Changes

How to read this

Words. The words a person reads on screen come first; they are the product's, and this text borrows them. Where the spec must be exact, the model's own term follows in parentheses, because it is the one the files, the ids and the command line use: those words are this text's. Details, in the table below, is the disclosure on a page that shows ids, files and paths.

Must and may. Must is a rule a conforming reader or writer keeps. May is a permission. Should is advice the checks do not enforce.

Sources. The rules here were drawn from Comprise, the reference implementation (its schema: kinds, references, closed lists and the id grammar; its loading and resolution; its paths; its checks, the envelope and the fourteen rules; the product-tree tooling behind chapter P's checks; its public projection), from the Comprise model document, and from COSM 0.3, the earlier specification of the product tree, which this text supersedes and whose nine aspects survive as P.3. The machine-readable form of everything here that a program needs is the MiniCOSM's manifest, comprise-oes.manifest.cosm: a .cosm file outside every Holotype, which a Holotype never embeds, since it names its MiniCOSM by the declaration alone (2.3). The manifest's fields per kind are the reference fields of section 5, exactly, plus the fields a check reads; every other field is open. The word manifest has two senses in Comprise: this declaration of a language, and the hash list of a saved version, a backup or a published atom; they never meet on screen.

1. The map

A Holotype is a file system that is also a relational database. Every part of Comprise OES has a place in both.

What is real in each reading. The file system is the Holotype itself: plain text, on the subject's machine, canonical. The relational database is real in part. store.sqlite holds a nodes table (one row per item, keyed by concern and id, with its envelope columns and the whole item as JSON), an edges table (one row per resolved reference: source, field path, target) and a full-text index, all rebuilt from the files by python -m core index; and it holds the tables that are canonical and never in a file (the people, feed rows, series, accounts, releases). The "table" of a kind is the set of items whose id carries that kind; SQL views over the local database, one per kind, are reserved for a later edition.

The two readings agree because one rule holds: a path names the same thing a primary key does (section 6).

2. The volume

2.1 Layout

<holotype>/                              the volume
  holotype.cosm                          the catalog (2.2): `oes: comprise/1`, id, concerns, sources, grants
  atoms/<concern>/                       one folder per concern declared in the catalog
    C/ O/ M/ R/ I/ S/   *.cosm           module files (2.4), at any depth under the module's folder
    P/  brand.cosm nodes.cosm doc.cosm   the product tree (chapter P.7)
    E/  README  or  none.cosm            people are never in a file (2.6)
  vendors/<domain>/<slug>/               a vendor-published atom, fetched and verified; read-only (3.5)
  snapshots/<stamp>/                     saved and signed versions; read-only (10)
  store.sqlite                           the local database (2.8)
  people.yaml  people.proposed.yaml      the people file, imported once into the local database
  feeds/<slug>/runs/  scans/  bindings/  reports/   kept payloads, replay pages, reviewed sources, report definitions
  codebases/<name>.fabulac.cosm          optional: the fabulacs the codebases point at (chapter S)
  logo.svg | logo.png                    optional: replaces the drawn company mark

A module folder's letter is read case-insensitively (p/ loads as P/); a writer must write the capital. A folder under atoms/ that the catalog does not declare is a load error. A declared concern without a folder is a load error.

A logo.svg or logo.png in the volume replaces the drawn company mark (section 12). An SVG so supplied is served so that no script in it runs: it is only ever a picture.

2.2 The catalog: holotype.cosm

One YAML mapping. Its keys:

Unknown keys are kept and ignored. A writer must not invent keys the catalog does not list without a version change.

A sample holds no person's name anywhere, and every rendering of it is marked (sample).

2.3 The declaration: oes: comprise/1

A Holotype says which MiniCOSM it is written in with one line in its catalog:

oes: comprise/1

The value is <MiniCOSM>/<version>: the MiniCOSM's name (lowercase), a slash, its major version (an integer).

1. Read. A reader must accept oes: comprise/1.
2. Default. A catalog with no oes: key is read as comprise/1, silently. This covers every Holotype made before the declaration existed, which says comprise: 0.1. The legacy key is read and kept; it is never an error.
3. Both. When a catalog has both, oes: decides and comprise: is ignored.
4. Write. A writer creating a Holotype must write oes: comprise/1 as the first line of the catalog. It must not rewrite the line of a Holotype it did not create: no migration.
5. Refuse. A catalog declaring a MiniCOSM or a version the reader does not know (oes: industry/1, oes: comprise/2), or an oes: with no value, is refused with a plain error (declaration) naming what it declares and what the reader knows. Nothing is loaded from it: the checks report the error (in Comprise, python -m core lint exits 1, the app will not register it, and a registered Holotype whose catalog is changed to such a line answers 409 until it is changed back).

The P files keep their own header, cosm: 0.3 (chapter P.7). It names the product tree's format, not the MiniCOSM.

2.4 Module files

A module file is a .cosm file anywhere under atoms/<concern>/<letter>/, at any depth (R/reflections/*.cosm is legal). Every such file is one YAML mapping with one of two shapes:

nodes:                         # the items, each a mapping with a string id
  - id: C:charter/articles
    type: charter
    …

module: none                   # this module is empty on purpose
reason: people are not imported in a public sample; the model records seats, not holders

• File names are free. The convention is one file per family of kinds (C/entity.cosm, C/bonds.cosm, M/markets.cosm), and a file may hold items of several kinds: Mozilla Foundation's C/entity.cosm holds its entity, two charters, a policy, four filings and an event. No id and no path names a file (section 6.4.2).
• Order. Files are read in path order, case-insensitively; items keep their file order.
• Duplicates. An id already loaded in the same module of the same concern is a load error; the first wins.
• module: none must carry a reason. Without one it is a warning, and the reason reads "no reason given".
• An empty module (no folder, or a folder with no items) is legal: every concern has all eight modules.

2.5 Reading a file

• UTF-8, with or without a byte-order mark; CRLF and LF read the same.
• YAML 1.2 booleans only: true and false, in lower, title or upper case. yes, no, on and off are strings. (A claim's on: field depends on it.)
• The COSM subset: no anchors, no aliases, no tags, no multi-document streams. A writer must not produce them.
• A file that does not parse, or whose top level is not a mapping, is a load error; the rest still loads. The reader never stops at the first problem: load problems are collected and reported by the checks as errors.

2.6 E: people are never in a file

atoms/<concern>/E/ holds a README saying where the people are, or a none.cosm with module: none and a reason. The people of a concern live only in the local database (2.8), imported from people.yaml. A Holotype's files hold counts and roles, never names. Not checked: the checks do not refuse an item written into an E file; a writer must not write one (section 13.3).

2.7 Other folders

vendors/ (3.5) and snapshots/ (10) are read-only to the app. feeds/, scans/ and bindings/ hold what sources brought in and what a person reviewed. reports/ holds report definitions (<slug>.report.yaml). codebases/ holds the fabulacs that S:codebase items name in their fabula field (chapter S); a fabulac is read there, never written by Comprise OES. None of them is part of the model; none is read by the checks except where a section says so.

2.8 The local database

store.sqlite, one per Holotype. Two kinds of table:

• Derived (rebuilt from the files by python -m core index): nodes, edges, nodes_fts.
• Canonical, never in a file: the people (people_meta, persons, assignments, memberships, credentials, access), their personal fields sealed field by field (chapter E); series; feed runs, synced SKUs, listings, levels and drift; scan runs, the scan log and candidates; logins, invites, tokens, keys (public halves only) and the audit; standing statements and evidence; isotype settings and releases.

No export of a Holotype includes the canonical tables, and no .cosm file ever holds what they hold. A member of the team is named by an account id in the logins, the invites and the audit, never by an email address.

3. Concerns and relationships

3.1 Concerns (atoms)

A concern is one bounded whole, described on its own. It is usually a company: the branded face of a corporation, sometimes a sub-brand, sometimes the corporation itself. Its id is atom/<slug>; its folder is atoms/<slug>/; its slug is lowercase ASCII letters, digits, dots and hyphens, starting with a letter or digit.

The test. A candidate is a concern when it has ownership distinct from the perspective concern's (the concern the Holotype is written from, below): outside owners, a partner, a franchisee, a licensee, a public float; or when it has its own legal shell and its own offerings. Otherwise:

Never nest. No concern contains another. What looks like nesting is a relationship (owns, member-of, operates), drawn as a derived tree (3.2). The perspective (holotype.cosm perspective:) is the concern a reader stands in by default.

A concern's display name is its anchor entity's name (C:entity with anchor: true), else its brand's name, else its id.

3.2 Relationships (bonds)

A relationship is a typed, dated, sourced tie between two concerns, or between a concern and an outside organization, a group or a vendor-published atom. It is an item of kind C:bond. Holding structures, licences, supply, regulation and franchising are all relationships. The rules named below are the fourteen of section 9.3. From the Mozilla sample Holotype, built from public sources, abridged:

- id: C:bond/foundation-controls-org
  type: bond
  name: Foundation controls Mozilla.org
  kinds: [controls]
  from: atom/mozilla-foundation
  to: atom/mozilla-org
  control: full
  accounting: consolidated
  inherits: [principles]
  status: active
  visibility: public
  provenance: {mode: net-scan, sources: ['https://wiki.mozilla.org/Mozilla_org'], confidence: 0.8, state: known}

Kinds: owns · controls · licenses · operates · makes-for · distributes-for · supplies · franchises · funds · guarantees · shares-services-with · succeeded · affiliated · competes-with · member-of · hosts · manages · commits · pledges · co-invests · sponsors · leases-to · regulated-by · accredited-by · builds-on · bargains-with · common-control.

Mirrored. A relationship between two concerns of the same Holotype is written in both, with the same id, in each concern's C module. Rule 8 fails when the copy is missing, and warns when the copies disagree on kinds, from or to. A relationship to an outside organization lives only in the concern that names it.

The derived tree. Concerns never nest, so the tree a group reads as is computed from the owns relationships every time and never stored (python -m core tree): roots are concerns nobody owns that own something; a concern owned two ways appears under each owner with the share on each edge and is counted once; a cycle is cut where it closes and said. Effective ownership is computed over owns, cycle-safe (rule 11).

3.3 Outside organizations (stubs)

An outside organization is one the Holotype names but does not model: a bank, a platform, a supplier, a former company. It is an item of kind C:counterparty in the concern that deals with it, and the index of everything that names it: relationships, contracts, channels, feeds, vendors, surfaces.

• It should carry a global-id where one exists (an LEI, a company-registry number, a domain), so two Holotypes that name the same outsider name the same thing.
• A platform's terms go in platform-terms (take rate, merchant of record, who owns the customer, payout cadence).
• atom: names the concern it is, when it is modelled in this Holotype.
• It can be promoted to a concern without changing any id that points at it.

In the file-system reading it is a mount point: a named place where something outside the volume would attach.

3.4 Groups

A group (atom group) is a named set of concerns ("the group", a reporting segment), declared in the catalog's groups:. A group may be a relationship's end. Its id is free text. Groups as perspectives, rollup scopes and Holotype roots are reserved for a later edition.

3.5 Vendor-published atoms

A vendor may publish one of its concerns at https://<domain>/.well-known/comprise/<slug>/: its public files, a manifest of hashes, an attestation and the public keys (python -m core publish). A customer fetches it (python -m core fetch) into vendors/<domain>/<slug>/, verified file by file; its id is vendor/<domain>/<slug>.

• It is the vendor's, never the customer's: loaded as a separate input, never edited, never linted as the customer's (its problems are notes).
• A C:counterparty whose global id matches is upgraded: the relationships that pointed at the outside organization now point at the vendor id, and the stub stays as each relationship's counterparty.
• A reference to a vendor id that has not been fetched is a warning (vendor-missing), never an error.
• Only the vendor as a whole has an id in the customer's Holotype. Its items have ids only in the vendor's own Holotype (section 6.4.5).

4. The envelope

Every item carries the same envelope: the system columns of every table. Outside P:

The envelope's reference fields are owner, at, attributed-to, counterparty, shared-with and links. Every other field is the kind's own (section 5). Unknown fields are allowed, and a reader must keep what it does not understand.

4.1 P is different

Items in P (chapter P) carry COSM's identity instead: confidence and sources at the top level rather than a provenance block, owner required (P's identity-min), consensus optional, and kind on the brand. Their sources must be declared in the catalog's sources: or a P doc.cosm sources: (a warning otherwise). P's own checks (P.9) check the rest of a P item's identity and its visibility. The envelope's status list and its reference fields are not checked on P items; instead every id-like string in a P item that points outside P must resolve (P.5.2).

4.2 Visibility

A hidden item is absent, not refused: lists leave it out, its page answers as one that does not exist, renderers never draw it, and a reference to it from a visible item keeps the id but gains no name. An id is an address, not a secret.

A pointer to an E:person from outside E is legal only in a restricted item (an error otherwise).

4.3 Provenance

Sources or it didn't happen.

not-disclosed is a fact, not a question: the subject declined to say.

5. The eight modules

Every concern has the eight modules, C · O · M · P · R · I · S · E. Each is a chapter: its kinds, what each holds, and which of its fields are references (checked as references, section 7) or read by a check (section 9). A module may be empty, or module: none with a reason.

The reference fields below are normative, exactly as listed. A dotted field (rows.sku) walks into lists and mappings: the sku of every row.

Chapter C · Corporation

The legal body: ownership, contracts, filings, money. The shell, whatever its legal form.

Chapter O · Organizations

Roles, teams, seats and who decides. People appear in the files only as roles.

Chapter M · Markets

Who it serves, through what, at what price.

Chapter P · Products: the product tree

What it offers, and why that matters. Chapter P is COSM 0.3, the product tree, rewritten in Comprise OES's terms. Everything normative in COSM 0.3 is kept, as this chapter states it. What COSM 0.3 described beyond the description of a tree (simulation, an editing API, exports and imports, the tree written back as a sketch) is reserved for a later edition; where COSM 0.3's text and this chapter differ, this chapter holds, and the Changes appendix (section 14) records the differences.

P.1 What P describes

P describes what a concern offers as a tree under its brand: the whole it sells under one face. Every item in the tree answers the same nine questions (P.3). The brand does no work of its own; it is the name for the state its parts settle into when their flows balance and their rules agree. The tree points at roles, never at people.

P describes things that matter to people as the sum of their parts. Three kinds of people are in scope: those who work on it (inside), those who have already chosen it (chosen), and those who may one day (prospective). People who will never meet it are out of scope on purpose: a model that claimed to matter to them would be marketing.

P.2 Levels (strata)

Five levels. An item may directly contain anything strictly below it, so a level may be skipped: a brand may hold a service directly.

P has one more kind, release (P:release/<unit>@<version>: date, channels, build, notes, listings), which stands outside the levels. A release is one version of a unit put out, not a part of the tree: it holds no parts, is no item's part, and names the product or service it releases in unit (and, in build, the S:codebase it was built from, when there is one). It carries P's identity like every P item (P.3.1). The invariants below are the tree's and pass over a release; P's checks know the kind and hold it to these rules (release, P.9), and the seven conditions leave it out.

Invariants, checked except where marked:

1. A direct part sits at a strictly lower level, except that a suite may contain a suite and a function a function (strata).
2. Containment is acyclic (acyclic).
3. Every item reaches the brand through parts (orphan).
4. The brand holds no flow, substrate, economics or affect (brand-holds-nothing). It should hold at least one part (not checked).
5. Products and services hold no parts (strata).
6. The level is declared by the kind, never inferred from depth.
7. An item has exactly one parent (single-parent). Shared use is feeds or depends-on, never a second parent.

The lower the level, the more description an item carries; the higher, the more it relates and the less it says.

P.3 The nine questions (aspects)

Every item answers nine questions. A field left out means not yet asked, never none: write none when that is the fact. A band is an ordinal the concern defines (small | medium | large), used wherever an exact number would go stale or leak.

1. identity: what is it?
2. flow: what does it take in and put out?
3. substrate: what does it run on?
4. rules: what must it, may it, must it not?
5. principles: what is it for, and what does it trade off?
6. economics: what does it cost and earn?
7. vocabulary: what do its words mean here?
8. affect: how is it meant to feel?
9. mattering: to whom does it matter, and why?

P.3.1 identity

P.3.2 flow

P.3.3 substrate

P.3.4 rules

A rule is written as "<actor> <aim> <object>" under must, may or must-not. The actor is a role (O:role/…), the reserved actor all-roles, or an external.

P.3.5 principles

P.3.6 economics

Every offering has a price, none, or an open question (rule 3).

P.3.7 vocabulary

P.3.8 affect

Offerings must declare affect; other items may.

P.3.9 mattering

The aspect the rest exist for. Affect says how an item is meant to feel; mattering says why it counts: what would be lost, and by whom, if it stopped tomorrow.

Each entry may carry its own confidence and sources, and any entry or field may be an open question. Two people who choose the same thing for different reasons are two entries. Mattering does not inherit and does not sum. The question that draws it out is always the same: if this stopped tomorrow, who would notice first, and what would they lose?

P.4 Roles, not people

People never appear in P. Names, emails, pronouns and personality words must not be written; the checks flag personal pronouns and pairs of capitalized words that look like a name (P.9). People appear only as roles, O:role/<Slug>, which live in O (chapter O): a name, duties, decision rights, an escalation path, the items it governs, and variance for behaviour that matters to the business.

When a person's behaviour matters, it is recorded in one of three systemic forms: variance on the role (execution, cadence drift), a rule's threshold and a flow's latency, or divergent vocabulary between items that feed each other.

P.5 Relations and inheritance

P.5.1 Relations

Six relations. None is a separate edge object: each lives in the aspect it belongs to, so an item is self-contained and the graph is derived.

feeds is declared at both ends: the provider says where its output goes, the consumer where its input comes from. An edge only one end declares is a warning (flow-mirror), except where either end is a brand, suite, offering or function, whose flows are derived from their parts.

P.5.2 Externals

In a Holotype, P declares no externals of its own. Every reference out of P is an external, and its kind is derived from what it names:

A reference out of P that resolves to nothing is an error (ref-unresolved).

P.5.3 Inheritance

Three aspects flow down the tree; six do not.

A child may redefine an inherited word, but must say so with overrides: true (or map it with maps-to); silent redefinition of a brand word is an error (override-explicit). A child may add rules and may narrow a may; it must not weaken an inherited must or must-not (not checked, section 13.3). The effective item, with every inherited line marked with the ancestor it came from, is what an item's card shows.

P.6 The sketch (shorthand)

For whiteboards, interviews and chat. One item per line; indentation is containment; the first line is the brand. Expanding a sketch writes the canonical YAML with an open question on every aspect the sketch did not fill (python -m core align sketch, which runs the product-tree tooling's expand and adds the Comprise namespaces).

meadow @Founder ! "must-not store card numbers"
  suite/books
    offering/ledger @Founder $49/mo :) relief, trust
      function/ingest ~ext/banks
        service/bank-sync > service/reconcile
        product/csv-importer > service/reconcile
      service/reconcile > offering/ledger
  offering/payroll @Payroll-Owner $4/seat :) fairness
    service/tip-out > offering/payroll
offering/ledger > offering/payroll, service/tip-out

A cross-tree edge is written at column zero. Nothing the sketch does not say is guessed.

P.7 The files of P

atoms/<concern>/P/
  brand.cosm      cosm: 0.3, then brand: (the L4 item, id P:<slug>)
  nodes.cosm      nodes: (every other item of the tree)
  doc.cosm        reading:, history:, findings:, sources: (the document, not the model)

• cosm: 0.3 heads each file. A file without it loads; opi: (the oldest key) is read the same way.
• brand: holds the root item. A COSM 0.2 firm: block is read as brand:; a writer must write brand:.
• reading (how to read the draft: date, author, mode, perspective, note), history (dated events that explain the shape), findings (what the structure already shows: check, nodes, finding, proposal) and sources (the P items' sources) carry the document. The export renders them; nothing is assembled by hand.
• roles:, externals: and contracts: inside P are legacy: read, never written. Roles live in O, contracts in C, externals are derived (P.5.2).
• Ids in P files are namespaced (P:offering/ledger, O:role/Founder); the tooling strips and restores the namespace when it hands the tree to the product-tree checks.
• type: firm loads as brand, and type: stack as function, with a note. A writer must write the current kinds.
• P may be module: none with a reason. A concern whose P has neither a brand nor module: none is an error.

P.8 Drawings

Every drawing is a view over the same items, never drawn by hand. The text is canonical; the drawing is derived.

The views (the product-tree tooling's render): map (the tree with feeds over it), tree, flow, affect, mattering; a substrate view and a rules view are reserved for a later edition. The app draws P in its own renderers (section 12); the card (card) and the text tree (ascii) are the product-tree tooling's.

P.9 P's checks

Two levels. The per-item checks run on every write; the seven conditions judge the whole tree, and rule 1 (section 9) reports them. Severities: an error blocks, a warning is recorded, a note is advice.

The seven conditions (equilibrium). The tree is in equilibrium only when all seven are ok:

1. flow-balance. Every internal input with a rate is supplied, within 10%, by its providers' rated outputs for the same resource. No internal flows: ok. Any internal edge whose rate is missing or open: unverifiable.
2. rule-consistency. No must and must-not share an aim.
3. closure. No orphan, external-exists, role-exists, brand-holds-nothing or mattering-refs error.
4. vocabulary-closure. Two items joined by a feeds edge never define the same word differently.
5. role-coverage. Every role of the concern owns an item of the tree, has a governs list, or is a pool.
6. affect-declared. Every offering has an affect audience and at least one feeling.
7. mattering-declared. The brand and every offering name all three constituencies; every other item says what the whole loses without it. An open question makes it unverifiable, not a violation.

Equilibrium is a property of a description, not a promise about the business. A concern can be in equilibrium and losing money. It means the description is closed: nothing dangles, nothing contradicts, nothing points outside without saying so.

P.10 How P renders for an audience

The internal rendering holds everything. The external rendering keeps the shape of the whole (the brand, the suites, the offerings, the public units, the words, the externals, mattering to the chosen and the prospective) and drops substrate, costs, margins, settlements, role details, open questions, findings, checks and every item that is not public by P.3.1. The top of the tree looks the same to a customer as to an employee; only the depth differs. The pack, a published atom and the isotype's offers all use this rule.

P.11 (withdrawn)

Chapter P.11 was withdrawn in edition 0.5.4; its content, where it survives, is in the Changes appendix (section 14).

P.12 (withdrawn)

Chapter P.12 was withdrawn in edition 0.5.4; its content, where it survives, is in the Changes appendix (section 14).

Chapter R · Representations and reflections

What it says, and what others say back.

Chapter I · Inventories

What exists, is stocked or is listed.

SKUs a feed brings in live in the local database, not the files; a mapping row may name one (section 7.4).

Chapter S · Stacks

The systems and vendors it runs on.

A codebase's fabulac. A codebase may point at a fabulac, the fabula of a folder of source code, as MacroCOSM OES (https://macro.cosmoes.org/), its section 18.4.7, defines it, in its fabula field: the path of a .fabulac.cosm file inside the Holotype, relative to its root and written with /, conventionally under codebases/ (fabula: codebases/firefox.fabulac.cosm). The field is a path, not a reference (section 7): it names a file of the volume, never an item, and it never leaves the Holotype.

• Checked (codebase-fabula): the file must be there, inside the Holotype, load, and declare oes: fabula/1 with flavour: fabulac (an error otherwise). When the source folder the fabulac describes is present (the folder its source.path names, relative to the fabulac's file), the fabulac must be fresh against it, its tree digest unchanged (a warning when it is stale). With no folder present, freshness is not judged.
• Shown. A reader shows the fabulac's atem line beside the codebase, under the codebase's visibility (4.2). No other part of the fabulac is rendered from the Holotype.
• Read, never built. Comprise OES reads a fabulac; it does not build one. A fabulac is made by decompiling the folder, as MacroCOSM OES defines it, and one a Holotype holds was made elsewhere and copied in.

Chapter E · Employees

The people: counted here, never named. Every person with a position, a membership or a credential. E is the only module with personal data, and it is never in a file (2.6). Its kinds are tables in the local database:

Pages show E as counts. Rules 6, 12 and 13 read it from the local database; without it they are unverifiable, unless E is module: none (or the database says people: none) with a reason.

6. Paths

Every concern, module, kind, item and field has a path: its id respelled as a location.

mozilla-foundation/P/offering/creative-futures      ⇄   atom/mozilla-foundation//P:offering/creative-futures

A path is <concern>/<module>/<kind>/<slug>, with #<field> for a field. The shorter prefixes name the folder levels. Paths are accepted beside ids, never instead of them.

6.1 Properties

• A respelling. A path is computed from an id, and an id from a path, with no lookup. Every item of the reference implementation's sample Holotypes has a path, and every path turns back into its id.
• Slug-based. It is built from slugs, which never change when an item is renamed.
• Absolute. It always starts with the concern. There are no relative paths: a bare id inside a concern becomes a path by adding that concern.
• ASCII, and one spelling. No colon, so it is safe as a file name on Windows; no percent-encoding, no .., no leading or trailing slash. A path has exactly one spelling, and a reader refuses any other rather than guessing.
• An address, never a door. A path never touches the disk by itself. It names a row; it is never joined to a folder to open a file.

6.2 Grammar

path         = concern-path / vendor-path
concern-path = concern [ "/" module [ "/" kind [ "/" slug [ "#" field ] ] ] ]
vendor-path  = "vendor/" domain "/" concern                    ; a vendor-published atom, as a whole
concern      = alnum *( lower / DIGIT / "." / "-" )            ; ATOM_RE's slug: [a-z0-9][a-z0-9.-]*
domain       = concern                                          ; the vendor's domain, lowercase
module       = "C" / "O" / "M" / "P" / "R" / "I" / "S" / "E"
kind         = lower *( lower / DIGIT / "-" )                   ; a kind the module declares, or "brand" in P
slug         = alnumx [ *( alnumx / "." ) alnumx ]              ; [A-Za-z0-9]([A-Za-z0-9._@-]*[A-Za-z0-9_@-])?
alnumx       = ALPHA / DIGIT / "_" / "@" / "-"
field        = key *( "." key / "[" 1*DIGIT "]" )
key          = ( ALPHA / DIGIT ) *( ALPHA / DIGIT / "_" / "-" )

A kind segment must be a kind of that module in the manifest; brand is accepted in P (6.4.1). A field may follow only an item. Segments are case-sensitive: module letters are capitals, kinds and concerns lowercase, slugs as written.

6.3 From an id to a path, and back

The module and kind levels have no id; the path is their only name. The reverse is the same table read right to left. The concern of a bare id is the concern whose files hold it.

6.4 Edge cases, settled

6.4.1 P's brand item

The brand's id has no kind: P:<slug>. Its path puts the kind in: <concern>/P/brand/<slug>.

mozilla-foundation/P/brand/mozilla-foundation    ⇄   P:mozilla-foundation   (in atom/mozilla-foundation)
mzla/P/brand/thunderbird                         ⇄   P:thunderbird          (in atom/mzla)

This is one-to-one because P:brand/<slug> is never a valid id: the checks require the brand's id to have no kind and every other P item's kind to match its type. <concern>/P/brand is the brand's table, with one row. The brand's slug need not equal the concern's (mzla's brand is thunderbird). <concern>/P/<slug> is not a path: the third segment is always a kind. R:brand/… is an ordinary R item (mozilla-foundation/R/brand/mozilla-foundation).

6.4.2 Kinds that share a file

The kind level is a table, not a file. mozilla-foundation/C/charter/articles names the charter wherever it is written; it happens to be in C/entity.cosm, beside the entity, a policy, filings and an event. Moving an item to another file changes neither its id nor its path. The file is metadata, shown in Details and in messages.

6.4.3 Relationships

A relationship between two concerns is written in both (3.2), with one id. Each copy has a path in its own concern, and both name the same relationship:

mozilla-foundation/C/bond/foundation-controls-org    the copy in the from concern (cite this one)
mozilla-org/C/bond/foundation-controls-org           the mirror in the to concern

Cite the copy in the from concern. A relationship to an outside organization has one copy, in the concern that names it.

6.4.4 Outside organizations

An outside organization is an ordinary item of C: mozilla-corporation/C/counterparty/google. Its global id is a field (#global-id), not a path: a path addresses the volume, never the world.

6.4.5 Vendor-published atoms

A vendor-published atom's path is its id, vendor/<domain>/<slug>, and nothing below it. Its items have no address in the customer's Holotype in comprise/1: they belong to the vendor's own Holotype, where they are an ordinary concern, and the qualified form (6.4.7) addresses them there. vendor/<domain>/<slug> never collides with a concern named vendor, because a concern path's second segment is a module letter, a capital, and a domain never is. The examples in this section are placeholders, not items of a sample Holotype.

6.4.6 Fields

# and a field path name a field of an item. The field path is the one the checks already write for open questions: keys joined by ., list positions as [n], counted from zero.

mozilla-foundation/C/contract/artists-make-technology#terms
mozilla-foundation/P/offering/mozilla-festival#economics.price
meadow/P/offering/ledger#flow.outputs[0].to
mozilla-foundation/C/bond/foundation-licenses-corporation#scope[0]

A field path names a value that is there; a path to a missing field names nothing. An open question on a whole item (a pending: key on the item) is addressed by the item's path with no field. A key outside the key rule (one with a slash or a space) has no field path. In a URL, # is the fragment: the browser keeps it across the redirect, so /h/{key}/at/<path>#<field> opens the item's page (the item, not the field); the command line and MCP address fields (6.5).

6.4.7 The qualified form

For use outside one install, a path is qualified with the MiniCOSM and the Holotype:

oes:comprise/<holotype>/<path>
oes:comprise/mozilla/mozilla-foundation/P/offering/creative-futures
oes:comprise/meadow/meadow/P/brand/meadow
oes:comprise/mozilla                                    the Holotype itself

<holotype> is the Holotype's id without holotype/ (holotype/mozilla → mozilla). The form carries no version: a path keeps its meaning across versions of a MiniCOSM, and a change that would alter a path's meaning must be a new MiniCOSM. A Holotype's id is unique within one install's registry, not in the world; a globally unique Holotype name and a resolver for qualified paths across installs are reserved for a later edition. A qualified path names a private address; it opens nothing to a reader who may not see it.

6.4.8 Case, characters and what has no path

• Ids and paths are case-sensitive and keep their case: meadow/O/role/Founder. Two ids that differ only in case are two items, and a case-insensitive file system (Windows, macOS by default) would merge them if a writer ever used paths as file names. comprise/1 never does; a tool that does must refuse such a pair. Not checked: the checks do not warn about ids that differ only in case (section 13.3).
• A slug uses ASCII letters, digits, ., _, @ and -, and never ends in . (Windows drops a trailing dot). This is the set the tooling already reads in bare P ids, and it holds P:release/<unit>@<version>. No segment is a Windows reserved name, alone or before a dot (6.6).
• An id whose slug falls outside that set (one with a slash, a colon, a #, a space or a non-ASCII letter) parses as an id but has no path in comprise/1; the command line says so. Not checked: the checks do not warn about such ids (section 13.3).
• The catalog's own entries (sources, sessions, grants, groups, attestations) have no path in comprise/1.

6.5 Where paths are accepted

Beside ids, never instead of them:

The app's own links stay id-based (/h/{key}/node/<concern>/<id>); /at/ is how a path opens. A browser never sends #<field> to the server, so /at/ opens items and folders, and the CLI and MCP address fields. /at/ takes the path only, never the qualified form: it already knows the Holotype.

6.6 Scope and safety

• A path to something the reader may not see answers exactly as its id would: the same 404, no name, no link. A path is never a way around visibility.
• Refused, never normalized: .. and .; an empty segment; a leading slash (an absolute path) or a trailing one; percent-encoding, an encoded slash included (the app checks the path exactly as it was sent); a backslash; whitespace, control characters and anything outside ASCII; a colon; a segment ending in a dot; a segment that is a Windows reserved name (con, prn, aux, nul, com0 to com9, lpt0 to lpt9, in any case, wherever it stands), alone or before a dot (con.txt, NUL.tar.gz: Windows reserves those too); a second #; a kind its module does not declare; more than four segments.
• A path is resolved against the loaded Holotype, never against the disk.

6.7 Examples

Every example in this document resolves on the reference implementation's sample Holotypes.

7. References

A reference is an id written in a field: a foreign key.

7.1 Forms

An item's own id is written bare in its concern's files; an item id that names another concern is an error (id-atom). References to items of the same concern are written bare too.

7.2 Where references are checked

The envelope's reference fields (section 4) and each kind's reference fields (section 5) are checked as references: each value must be an id string of one of the forms above that resolves, or a sentinel, or an open question. In P every string that looks like an id outside P is checked the same way (P.5.2). A path is not a reference: files hold ids.

7.3 Resolution

A bare id resolves in its own concern's module; a qualified id in the named concern; atom/<slug> to the concern; vendor/… to the fetched vendor. Anything else resolves to nothing, and that is an error (ref-unresolved), with three exceptions:

• a vendor id not yet fetched is a warning (vendor-missing);
• a SKU named by a mapping row, a price-book rate or an exclusion that a feed brought in resolves against the local database; before any feed has been pulled it is a warning (sku-unverified);
• a typed link with neither to nor id is skipped.

7.4 Scope

A reference to an item the reader may not see stays as the id with no name (4.2). Resolution never depends on the reader; display does.

7.5 Named relations

The cross-module relations have names (owner, holds, serves, sold-through, priced-by, maps-to or entitles, listed-on, runs-on, presents, about, bound-by, shared-with, feeds, attributed-to, at, twin, counterparty, licensed-by, requires-credential, member-of). In comprise/1 each is a field; the relation's name is the field's, and the checks know them only as reference fields. A typed link's rel is free text.

8. Open questions

An open question (pending) is a value nobody has yet given, written where the value would go:

terms: {pending: "funding amount and term are not published"}
pending: After the 2026 transfer the FAQ says Mozilla.org owns the trademarks; which entity is the licensor now?

• Pending beats plausible. A writer must never guess a value; it writes the question instead.
• Who answers. The item's owner; a role answers for itself; otherwise "unassigned". The checks list every open question with its item, its field path and who can answer it (python -m core pending).
• Its address. The item's path plus the field path (…/C/contract/artists-make-technology#terms); an open question on the whole item is the item's path.
• What it does to the checks. An open value is never an error. It makes a rule unverifiable where the rule needs the value (a price, a rate, a reporting line, a counterparty), and an unverifiable rule refuses signing.
• Not the same as "not disclosed". provenance.state: not-disclosed says the subject declined to say: a fact.
• Not the same as "to fill in". To fill in counts the details the question banks (below) would still ask about an item, its open questions included; an item with nothing left to fill in is complete. The three health figures (open questions, to fill in, complete) come from one place.

Asking (elicitation). Comprise OES fills a Holotype by asking with the dialectic, the core's one way of asking a person what a source means and recording what they say, as MacroCOSM OES (https://macro.cosmoes.org/), its section 18.6, defines it. What Comprise OES adds to it:

• The banks. Comprise OES's question banks are the dialectic banks of its manifest (its dialectic: key, read as the core reads every manifest's banks), each kept in a file of Comprise OES's own that the bank names in from:, so a reader without those files reads banks with no questions: one bank per module, each question about a field of one or more kinds, asked of the item with the most left to fill in. A bank may also hold a counter per check: the question to put when that check refuses an answer.
• The sitting. One elicitation sitting is one session of the dialectic, written as a D:session record in the catalog's sessions: (2.2). Its id keeps the spelling elicit-<date>-<hex> (D:session/elicit-2026-11-02-a3f9), and the catalog's sources: declares the same id as a source, as before; the record sits beside that declaration and does not replace it. The record holds at (when the sitting began), with: {to, who} (to the role answering or owner; who a plain description, never a name), through (person or agent), model (the model that parsed or rephrased answers, when one did), covers: {part, module} (the concern, and the module's letter; a sitting across the Holotype is {module: '*'}, with no part), and asked, answered and skipped: the fields put to the person, each as atom/<concern>//<id>#<field path>.
• Ask, check, commit. A question is put to one field. The answer becomes the field's value, and the write goes through the checks (section 9): a write that would add an error is undone, and the bank's counter for that check is put instead. Outside P, the item written takes provenance.mode: dialectic, the session's id among its sources and the answer's confidence; in P, the session's id joins the item's sources (4.1). The bare id elicit-… names the session wherever it is written, so provenance: {mode: dialectic, sources: [elicit-…]} reads as it always has.
• "I don't know" stays an open question, in the person's own words: the field is written {pending: "<their words>"}, and the question waits for the next sitting.
• Who is asked. A question goes to the item's owner by default, as every open question does (above): a role, never a person.
• No question items. A Holotype holds no D:question items: a question asked in a sitting is a bank's question put to one field, and one left open is an open question where the value would go.

9. Checks

The checks (lint) are the constraints of the database, run on the whole Holotype: python -m core lint <dir>. Every write the app makes goes through them, and a write that adds an error is undone.

9.1 What runs

1. Load problems: every file that would not parse or did not fit (errors).
2. The envelope on every item (section 4), and the reference checks (section 7).
3. P's checks per concern (P.9), reported with a P prefix.
4. The fourteen rules per concern.
5. Notes: each fetched vendor-published atom; items still exactly as an archetype gave them.

9.2 The envelope's checks

9.3 The fourteen rules

Each rule reports one of: pass, fail, unverifiable, finding. The bold titles below are in this document's words. The names the checks print (the CLI, the checks page, the export, MCP's lint rules[].name) are the manifest's, which keep the model's words where the two differ: rule 1 is product tree in equilibrium, rule 7 claims about real nodes, rule 8 bonds two-ended and sourced, rule 9 no stale synced nodes. One line each:

1. The product tree in equilibrium. P's seven conditions all ok, and no P error (module: none passes).
2. SKUs map to P units. Every stock item maps to at least one P unit, by maps-to or entitles, or is excluded with a reason.
3. Offerings priced. Every offering has a price or none, and every price-book rate agrees with it.
4. Systems owned and referred. Every system has an owner and something that refers to it; otherwise a finding (orphan spend).
5. Positions, roles, owners. Every position reports to a position (one none at most); every role governs or owns something, or is a pool; every owner resolves.
6. Employed persons assigned. Every active person of an employment kind holds at least one current assignment, to a position that exists.
7. Claims about real items. Every claim is about something that exists, and no claim restates a must-not; partial, contested or unsupported evidence is a finding.
8. Relationships two-ended and sourced. Both ends are concerns, outside organizations, vendors or groups; mirrored where both are modelled; with sources.
9. No stale synced items. No item marked stale or past its max-age, no active feed never pulled or overdue, no reflections grant overdue.
10. Counterparties resolve. Every channel, feed, vendor, platform and platform surface names one C:counterparty (a direct channel, or a feed read from a file, by hand or from an MCP source, may say none).
11. No double-counted rollups. Effective ownership over owns is cycle-safe, and no C:finance consolidates a concern held at equity or cost.
12. Credentialed positions. A position that requires a credential is held by someone who holds it.
13. Bus factor. A person holding more roles than the limit (default 3) is a finding.
14. Shell records to promote. A non-anchor entity or a template instance with its own owners or offerings is a finding: promote it to a concern.

Rules 6, 12 and 13 read the local database; without it they are unverifiable, unless the people are none with a reason.

9.4 The verdict

• ok: no error and no failed rule. This is the exit code.
• ATTEST: allowed: ok, and no rule unverifiable. Findings never block. This is "can this version be signed?"

10. Versions

• A saved version (snapshot) is an immutable copy of the model files at a moment, at snapshots/<stamp>/: the catalog, everything under atoms/, the fabulacs under codebases/, the bindings and the fetched vendors; never the local database, the people file, feed payloads or scan runs. Its manifest.yaml holds when and by whom, every file's sha256, each concern's content hash and item count, the export's hash, the checks' verdict, the people counts, the perspective concern's standing, and its own hash. Taking one changes nothing and is always allowed.
• The diff is item by item, between two saved versions or one and now: concerns and items added and removed, items changed with the field paths that moved, an open question answered, a value reopened. A reader's hidden items stay out.
• As of. A saved version opens read-only (as_of), and reports run against it. snapshot timeline is the change across all of them.
• A signed version (attestation) is a saved version the checks allowed, whose files still match their hashes, signed by the holders of the roles that govern it: one Ed25519 signature per signer over a canonical statement (the Holotype, the stamp, the manifest hash, the export hash, the signer, the roles, the time), in attestation.yaml beside it. Signers are person ids, never names. Signing needs a first-party perspective concern. A signed version is a signed snapshot; never "legally equivalent" to anything.
• Hashes. A concern's content hash is the sha256 of its module files in path order. The export's hash moves with its content.

11. The private/public split

The Holotype is private by construction; the isotype is public by construction. Two formats, not one format with a setting.

Standing is whether the people keeping a Holotype speak for its subject, and to what proven level: the domain, the legal entity, the person acting for it. First-party standing is proven at one of those levels by Comprise Connect; a claim in the catalog (alignment, 2.2) is never proof; an outsider's standing is third-party (11.4).

11.1 The private side

• The files stay on the subject's machine. Nothing leaves unless a person set up where it goes.
• People are only in the local database, sealed field by field under a key kept in the keychain: encrypted (AES-256-GCM) when the optional cryptography package is present, tamper-evident only (HMAC) without it, and plaintext when there is no key at all, which people list says plainly.
• Credentials are in the keychain, never in a file; private keys under the home folder, never in a Holotype.
• A backup (comprise-bundle/0) is encrypted on the machine before it leaves; Comprise Connect stores ciphertext and holds no key.
• Inside, visibility (4.2) decides who reads what: restricted items reach only their module's editors.

11.2 Renderings for an audience

11.3 The isotype: a view, default-deny

The isotype (comprise-isotype/0) is a separate document with a fixed schema, computed from the Holotype by rules, one rule per field. It is a view with fixed columns: a field added to the model later never flows into it by itself.

{isotype, hid, epoch, cadence, sample, identity, shape, offers, seeks, open_to}
identity:  name, domains, jurisdiction, founded, kind
shape:     employees (some | none), structure (single | group), markets
offers[]:  name, summary, kind (suite, offering, function, product, service, audience)
seeks[], open_to[]:  kind (the aim kinds), summary
optional:  program, trace, bonds, policies, and the optional keys of items (below)

The rules that bind it:

• Assertions, not measurements. No counts of anything internal; the only number is the founded year.
• Withhold, never falsify. What is not public is left out and leaves no mark. An offer whose summary holds a digit keeps its name and loses the summary; an aim or a market with a digit is left out.
• Verified and stated. Identity, shape and offers are derived from the Holotype (verified); seeks and open to are the company's own words (stated), and so are bonds and policies when a release carries them.
• Epochs and bands. The date is the epoch (2026-Q4, 2026-10, 2026-W43), never the day of an edit; lists are sorted so file order leaks nothing; a banded number moves only after 90 days past the boundary.
• One release per epoch, signed. Quarterly by default; monthly or weekly by choice. A release needs a first-party concern, unless the Holotype is a sample, whose isotype says sample: true and is signed by the install's sample key.
• Opt-indexed. Nothing is listed on the Index as its subject unless the subject released it and chose to list it. An outside chart (11.4) is listed under Outside View, and never as the subject. Comprise Connect charges fees for what it does, and its terms page states them; a promoted entry on the Index is always labelled as promoted.
• Beside the Index, the Allograph Registry. Comprise Connect also serves Ascribe's Allograph Registry, where people and agents list what they can do for others, with the Index's accounts, passkeys and rate limits (Ascribe, its section 14.7, https://ascribe.cosmoes.org/). A company listed on the Index may own an agent listed there and may attest work a person or an agent did for it, by a statement signed with the key that signs its current isotype (Ascribe, its sections 14.9 and 14.10). The registry names the company by its Index handle, and holds nothing of its Holotype.

What a release may also carry. Each of these is optional and the version stays /0, so a stored isotype stays valid and an older one reads as it always did. Default-deny still holds: anything not named here is refused, never filtered. A text is at most 600 characters, a list 50 items, and a document 64 KB. The numbers rule holds: the words in these keys hold no digit, and a digest's digits count nothing.

The dial: a release is a program's projection. A projection is an entailment made by rule: the Holotype entails its isotype, and what is projected holds by construction (MacroCOSM OES, its section 18.1). project calls the rules in the table above, then narrows to what a Thym program emitted and withheld, so a program only chooses: it can keep more back, and it can't add a row, word one or ask a model. Three presets ship with Comprise: minimal, which reproduces those rules byte for byte; fuller, with entailed and a word for shape.markets; and house, which adds the rest of the table. A subject with first-party standing may write its own program, and a program that breaks a rule is refused, with the line. A first release states a market word, and after that it moves only after 90 days past its boundary. The moves are declared in a sidecar, comprise.moves.cosm, and never in the manifest. The move that writes entailed is entailment; its earlier name, telling, is read for good as the same move, and a program written now says entailment. The language a program is written in is Thym (https://thym.cosmoes.org/), the transcognition language that connects OESes.

Further isotype fields a subject may open one at a time, each opt-in and marked verified or stated, are reserved for a later edition.

11.4 The outside chart: comprise-paratype/0

An outsider's isotype of a subject, at third-party standing and never the subject's word. On a screen it is an outside chart, in full.

{paratype, standing, submitter, of, hid, epoch, program, trace, identity, shape, offers, seeks, open_to}
optional:  bonds, policies, and the optional keys of items (11.3)
refused:   isotype, sample, cadence, agreement

Every other key, and every limit on it, is comprise-isotype/0's. Comprise and Comprise Connect check a chart against one and the same contract, and reach one verdict on it.

• Signing. Ed25519 over the canonical JSON, sent as {paratype, signature, public_key}, by a chart key kept per holder in the keychain (comprise/chart), and never the key that signs an isotype, which would link the person to the company in a public document.
• A chart can't become an isotype. It never carries sample, is never listed as the subject, and nothing an outsider derives is marked verified.
• The handle. A holder's handle is words and digits joined by hyphens, so it never reads as a subject's handle, and names no one. It changes at most once in 90 days; at 365 days Connect replaces it at the holder's next visit; every handle a holder has had stays on their public history page. A line beside a handle saying what Connect has verified of the holder's organization shows only when something was checked, and never names the organization.
• The monthly limit. Connect takes 3, 10 or 30 new charts a month from a holder, by what the holder's organization has proven: 3 with nothing proven, 10 with a proven domain, 30 with the entity or its representative verified. A replacement counts, the same chart sent again does not, and a withdrawal gives none back.
• On the Index. One live chart per holder per subject: a new one replaces it. Agreement is computed by Connect, is never in the document, and counts only closed or banded fields and sets of kinds. Prose is never merged. A count says what these holders say, not that the thing is so, and since one person may hold many accounts it can be farmed. Counts stop once the subject picks among its charts or deletes one, and do not come back.
• Once the subject lists. A listing that has proven the domain demotes its charts, computed at read, and the owner chooses what shows.

11.5 The sealed package: a cryptotype

The owner's encrypted package of a Holotype, or of a program's projection of it, handed with a key to a chosen party. It is a Thym package (Thym, its section 15, https://thym.cosmoes.org/) in its encrypted form. On a screen it is a sealed package, and a projection in one is a reduced copy.

<name>.thym/           the folder form, with its catalog package.cosm
<name>.package.cosm    the single file: the same catalog, with each file's bytes on its row
<name>.thym.enc        the sealed file: the single file, encrypted
catalog:   oes: thym/1, kind: package, id: thym/<name>, name, contents: [{path, sha256, role}], made: {program?, trace?, at, by}, notice, nodes: []
roles:     holotype, projection, program, trace

• Two kinds. The whole Holotype is one holotype row per model file, at its own path. A projection is projection (projection.json, a comprise-isotype/0 document with its program and trace digests, unsigned), program (program.thym, its source) and trace (trace.cosm, the cleaned trace). Nothing else is a package: no local database, no store key, no people file, and no chart key. A reduced copy's record still shows counts: the trace holds the steps and how many items each went through, which can be more than the copy says.
• Text. A file that isn't text, or that YAML would change, goes under a row's base64, with sha256 still over its bytes.
• The seal. The bundle's cipher (comprise-bundle/0: AES-256-GCM chunks and an encrypted manifest) under a fresh data key for the package, never the Holotype's, with one recovery-code keyring entry. The sealed file is a thym/1 catalog with encrypted: {cipher: comprise-bundle/0, aead: a256gcm, key: shown-once, hid, bundle, keyring, manifest, chunks}, its id is thym/<hid>, and hid is a random id of its own. Its manifest also holds clear, the sha256 of the file's own bytes with that value taken out, so a byte changed anywhere refuses it.
• The key is a recovery code: 24 characters of A-Z and 2-7, shown once and stored nowhere. A lost key is a lost package.
• Standing. Any standing may make one, since it speaks as no one and is not signed. Below first-party its notice says it is research.
• Hosting is the owner's choice per package. Comprise Connect stores the sealed file in parts, zero-access, in a storage area of its own, with a capability it keeps only hashed, and sees its size, its times and its fetches. A withdrawal really removes it, and cannot recall a copy already fetched.
• Match tokens are the one exception to zero access, by the owner's consent: {about, token}, token being the lowercase hex HMAC-SHA256 of about, a newline and the value's normal form, under a key per package that Connect holds with a hosted copy. about is one of identity.kind, identity.country, shape.employees, shape.structure, shape.markets, offers.kind, seeks.kind and open_to.kind, and a value is a closed word or a two-letter country, so Connect can work out what each says. A package handed over directly has none. Someone who found what a package says may write to its owner: the words are plain words Connect holds, not sealed, and only the owner's yes, in the owner's own words, reaches the asker.

12. Renderers

A renderer turns a Holotype into another form. Renderers only read. Each applies the reader's scope (4.2): a hidden item is absent.

Renderers driven by a reader's own style profile, and shorts compiled for one audience (for beginners, as story problems, as narrative), are reserved for a later edition.

13. Conformance

13.1 A reader must

1. Read the catalog; accept oes: comprise/1; read a catalog without oes: as comprise/1; refuse an unknown MiniCOSM or version with a plain error (2.3).
2. Load every declared concern's eight modules from *.cosm files at any depth, as UTF-8 with an optional BOM, with YAML 1.2 booleans, never stopping at the first problem (2.4, 2.5).
3. Read P's brand: (and a legacy firm:) with nodes:, and the legacy kinds firm and stack (P.7).
4. Keep unknown fields and unknown catalog keys.
5. Resolve references as section 7 says; treat a path as a respelling of an id (section 6), resolved against the loaded Holotype, never the disk.
6. Apply visibility (4.2) before showing anything: a hidden item is absent, and a reference to it keeps its id and no name.
7. Never read the local database's people into anything but counts, outside E's own pages.
8. Read through another system's tool (an MCP source) and never write through it.
9. Read told on an isotype's or a paratype's offers[], seeks[] and open_to[] as entailed, and the move telling as entailment (11.3); write only the new spellings.

13.2 A writer must

1. Write oes: comprise/1 first in a new catalog, and never rewrite another's (2.3).
2. Write only the COSM YAML subset: no anchors, aliases, tags or multiple documents.
3. Write ids bare inside their own concern, with the kind equal to type, and the brand as P:<slug>.
4. Write brand:, never firm:; roles in O, contracts in C; no externals: in P.
5. Never write a person into a file: no names, no E items, people only in the local database.
6. Write an open question, never a guess. Cite sources for every fact.
7. Write nothing a person did not accept: a model, scan, feed or agent only proposes.
8. Leave a Holotype's checks no worse: a write that adds an error is undone.

13.3 What the checks verify, and what they do not

Verified: the load, the oes: declaration included (2.3); the id grammar; kinds per module; the envelope's closed lists, required fields and provenance; owners are roles; every reference resolves (with the exceptions in 7.3); relationship kinds and bases; aims; a codebase's fabulac; P's per-item checks, releases included, and seven conditions; the fourteen rules.

Not verified (a writer must still keep them):

• that no item is written into an E file;
• that exactly one entity per concern is the anchor, and that the brand holds at least one part;
• that a restricted item's pointer to a person is lawful;
• inherited must and must-not are not weakened (P.5.3);
• that ids differ by more than case, and that every slug is path-safe (6.4.8);
• that an M:account is restricted.

13.4 (withdrawn)

Section 13.4 was withdrawn in edition 0.5.4; its content, where it survives, is in the Changes appendix (section 14).

14. Changes

Newest first. An entry records what changed in the text; where an implementation and this text had disagreed, it says which was corrected.

Edition 0.7.0 · 2026-11-13.

1. Entailment (11.3). A release is an entailment made by rule: the Holotype entails its isotype, and what is projected holds by construction. The line built by rule from an item's summary and its public children is offers[].entailed, seeks[].entailed and open_to[].entailed, and the move that writes it is entailment; told and telling, their earlier spellings, are read for good and never written (11.3, 13.1).
2. Beside the Index, the Allograph Registry (11.3). Comprise Connect also serves Ascribe's registry, with the Index's accounts, passkeys and rate limits. A company listed on the Index may own an agent listed there and may attest work a person or an agent did for it, by a statement signed with the key that signs its current isotype; the registry names the company by its Index handle and holds nothing of its Holotype.
3. Stewardship. The colophon licenses the text under CC BY 4.0 and makes the OWFa 1.0 promise for it; the names of the family are not licensed, and the author holds them for now.

Edition 0.6.0 · 2026-11-06.

1. Where Comprise OES stands. The lead says there are two MiniCOSMs, Comprise OES and Ascribe, both written in MacroCOSM OES, an OES: the shared grammar and its core, which holds the formats built into every reader, the densities and the dialectic; Thym is named the transcognition language that connects OESes (the lead and 11.3). The status paragraph names the steward.
2. Elicitation is the dialectic (section 8). The question banks are the dialectic banks of the manifest, each kept in a file of Comprise OES's own that the bank names in from:. A sitting is a session of the dialectic, written as a D:session record in the catalog's new sessions: (2.2) beside the source the catalog already declares for it, its id still spelled elicit-<date>-<hex>; ask, check and commit, "I don't know" and who is asked are said against the core's primitive. Provenance written before, {mode: dialectic, sources: [elicit-…]}, stays valid as written. Sessions join the catalog entries that have no path (6.4.8).
3. S:codebase gains fabula (chapter S): an optional path to a fabulac inside the Holotype, by convention under codebases/ (2.1, 2.7), checked by codebase-fabula (9.2, 13.3), its atem line shown beside the codebase. Comprise OES reads a fabulac and never builds one. A saved version copies codebases/ (section 10).
4. P:release is resolved. The first edition recorded a disagreement: P:release declared in the schema and rejected by P's checks as an unknown kind. In this edition P's checks know release, a kind outside the levels: no parts, in no item's parts, naming its unit, its visibility its unit's (P.2, P.3.1; in P.9, type, orphan and the new release). The reference implementation's checks were corrected.
5. access is described (chapter E): one row per person per concern holding a level, and for a steward the modules; it holds no personal data and is not sealed. Section 2.8 says it is the people tables' personal fields that are sealed.
6. The isotype's schema line (11.3) names its optional keys, program and trace among them; an outside chart still requires both (11.4).
7. Words. Section 12 names the reserved tellings for one audience as shorts; the trade's word for them is dropped.

Edition 0.5.4 · 2026-11-03, second revision. Rules the reference implementation keeps and this text had not stated are written in: the logo file served script-free (2.1); a sample's names and mark (2.2); team members named by account id (2.8); standing and its proven levels (section 11); fees and promoted entries (11.3); the holder's handle, the monthly limit and what agreement counts and never means (11.4); a reduced copy's record, what a withdrawal cannot recall, and a finder's words to an owner (11.5); reading, never writing, through another system's tool (13.1).

Edition 0.5.4 · 2026-11-03. The canonical edition, published at https://comprise.cosmoes.org/. The name carries no number: Comprise OES, describing the comprise/1 MiniCOSM; the dated introduction gives way to the status line and the lead. Comprise, the product, is named as the reference implementation in place of its code, and "the code wins" gives way to this appendix's rule. Chapter P.11 (what COSM 0.3 described and the implementation did not build), chapter P.12 (where COSM 0.3's text and the implementation disagreed) and section 13.4 (where the code wins) are withdrawn: P.11's and P.12's substance is recorded in the entry for 2026-10-20 below, 13.4's rules stand in their own sections, and its rule for at: site/… is folded into section 4. The not built markers are withdrawn and each gap is stated where it falls as reserved for a later edition (SQL views per kind, groups as perspectives, the substrate and rules views, the resolution of P:release, a globally unique Holotype name and a resolver for qualified paths, further opt-in isotype fields, style-profile renderers). The manifest's rules, formerly among the decisions of 2026-10-20, are folded into "How to read this". Status passages, decision and slice references, repository paths, pointers to planning documents and the item counts of the sample Holotypes are removed; the cross-references to Thym and to the overview are their cosmoes.org homes. Section 14, "Decisions in this version", becomes this appendix.

Edition 1 · 2026-11-03, the outside chart and the sealed package. Section 11.4, the outside chart (comprise-paratype/0), and section 11.5, the sealed package (a cryptotype: a Thym package in its encrypted form), are added, and section 11.3 gains what a release may also carry and the dial, a release as a program's projection. They write down rulings made on 2026-11-02; Comprise 0.3.0, the reference implementation that carries them, shipped on 2026-11-04.

Edition 1 · 2026-10-20. The first edition of the format under its own name, replacing COSM 0.3.

1. One document. The product tree is chapter P and the other seven modules are chapters of the same shape. COSM 0.3's normative text survives in chapter P. What COSM 0.3 described beyond the description of a tree is not part of the format: simulation (units as queues, aggregates by min-cut, role variance as jitter, rule gates, affect probes, scenarios); whatif, harmonize, propose, rank, uat, qa and hooks (the findings in doc.cosm keep harmonize's words); depersonalize (the no-humans checks find, a person fixes); export to JSON-LD, Turtle, OWL, SHACL, ArchiMate and CSV, and import; save, put, remove, where, upstream, downstream, glossary, capacity and cost as an API (the app's editor writes through the checks); sketch, the tree written back as shorthand (expand is kept). The Remote Assistance Protocol is replaced by grants in the catalog, proposals a person accepts and the audit; the State Library (history, diff, at, attest) by saved and signed versions (section 10); firms within firms by concerns and relationships (section 3). COSM 0.3's own open questions (mattering shares, an affect scale, product internals) are not taken up.
2. Where COSM 0.3's text and this edition differ, this edition holds. The tree's version is 0.3 (the brand and restricted added), and P files say cosm: 0.3. rule-syntax is a warning when the actor is not a role (an external may also be an actor) and an error only for a rule with no aim. no-humans is a warning for a pronoun and a note for a name-like pair; outside P, a pronoun in name or summary is a warning and a pointer to E:person from an unrestricted item an error. term-resolves and no-weakening are not checked. role-exists covers the owner only. Rule-consistency compares a must and a must-not with the same text. Flow balance is always within 10%. The equilibrium conditions are seven. A saved version is always taken and records the verdict; only signing is refused. Any *.cosm under P is read; brand.cosm, nodes.cosm and doc.cosm are the convention. P:release is declared in the schema and rejected by P's checks: a disagreement recorded, not resolved.
3. Paths are a pure respelling of ids (section 6): no lookup, no index; every item of the sample Holotypes round-trips.
4. The brand's path is <concern>/P/brand/<slug>, mapping to P:<slug>; one-to-one because P:brand/<slug> is never a valid id. <concern>/P/<slug> is not a path.
5. The kind level is a table, never a file. Neither ids nor paths name files; the file is metadata.
6. A relationship has one path per copy, each in its own concern; the copy in the from concern is the one to cite.
7. Outside organizations are ordinary C items. Their global id is a field, not part of a path.
8. A vendor-published atom is addressed only as a whole, vendor/<domain>/<slug>, which is also its id. Its items are addressed in the vendor's own Holotype by the qualified form. The case of the second segment keeps it apart from a concern called vendor.
9. Fields use the checks' own field paths after #: keys by ., list positions by [n] from zero. Fields only follow items. An open question on a whole item is the item's path.
10. The qualified form is oes:comprise/<holotype>/<path>, with the Holotype's id slug and no version. A path keeps its meaning across versions of a MiniCOSM; a change of meaning is a new MiniCOSM. A globally unique Holotype name is reserved for a later edition.
11. Case is kept and significant. A slug's characters are [A-Za-z0-9._@-], with no trailing dot. An id outside them has no path. A warning for such ids, and for ids that differ only in case, is not specified as a check.
12. One spelling. A reader refuses a malformed path rather than normalizing it: no trailing slash, no .., no %.
13. The catalog's entries have no path (sources, grants, groups, attestations).
14. When a catalog has both oes: and comprise:, oes: decides. An unknown version of a known MiniCOSM is refused like an unknown MiniCOSM. A new catalog carries the declaration as its first line, so a person or a tool sees it without parsing the file.
15. P files keep cosm: 0.3. It is the product tree's format version, read by P's checks, and says nothing about the MiniCOSM.
16. The manifest is a .cosm file outside every Holotype. A Holotype names its MiniCOSM by the declaration only and never embeds the manifest. The word manifest has two senses in Comprise: this declaration of a language, and the hash list of a saved version, a backup or a published atom; they never meet on screen.
17. The manifest's fields per kind are the schema's reference fields, exactly, plus the fields a check reads. Every other field is open. P lists its nine aspects. E's kinds are marked as stored in the local database.
18. An absent visibility outside P reads as internal: visible to every signed-in reader, never public.
19. Words. The text says concern, item, relationship, open question, outside organization and kind, with the model's term in parentheses where exactness needs it. Ids, file names and check names keep the model's words, because they are the format.

Colophon

Comprise OES — Copyright © 2026 Graham Smith. The text is licensed under the Creative Commons Attribution 4.0 International licence (CC BY 4.0, https://creativecommons.org/licenses/by/4.0/). A copy carries the author, Graham Smith; the text's name and edition; and a link to its home, https://comprise.cosmoes.org/. For Comprise OES, the author makes the Open Web Foundation Final Specification Agreement 1.0 (OWFa 1.0) promise (https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0). The names of the family are not licensed by either; the author holds them for now. The canonical edition is published at https://comprise.cosmoes.org/; its source and history are at https://github.com/0gsd/cosmoes-site.