cosmoes.org

comprise.cosmoes.org · specification · v1 · one line per section

Comprise OES 1

The code in core/ is the reference reader and writer

Outline

  1. Contents — Contents, in Comprise OES 1
  2. How to read this — The words a person reads on screen come first (they are MO.md's)
  3. 1 The map — A Holotype is a file system that is also a relational database
  4. 2 The volume — The volume: Layout, The catalog: holotype.cosm, The declaration: oes: comprise/1, Module files
  5. 2.1 Layout — A module folder's letter is read case-insensitively (p/ loads as P/)
  6. 2.2 The catalog: holotype.cosm — One YAML mapping
  7. 2.3 The declaration: oes: comprise/1 — A Holotype says which MiniCOSM it is written in with one line in its catalog
  8. 2.4 Module files — A module file is a .cosm file anywhere under atoms/<concern>/<letter>/, at any depth
  9. 2.5 Reading a file — UTF-8, with or without a byte-order mark; CRLF and LF read the same
  10. 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
  11. 2.7 Other folders — vendors/ (3.5) and snapshots/ (10) are read-only to the app
  12. 2.8 The local database — store.sqlite, one per Holotype
  13. 3 Concerns and relationships — Concerns and relationships: Concerns (atoms), Relationships (bonds), Outside organizations (stubs), Groups
  14. 3.1 Concerns (atoms) — A concern is one bounded whole, described on its own
  15. 3.2 Relationships (bonds) — A relationship is a typed, dated, sourced tie between two concerns
  16. 3.3 Outside organizations (stubs) — An outside organization is one the Holotype names but does not model
  17. 3.4 Groups — A group (atom group) is a named set of concerns
  18. 3.5 Vendor-published atoms — A vendor may publish one of its concerns at https://<domain>/.well-known/comprise/<slug>/
  19. 4 The envelope — Every item carries the same envelope: the system columns of every table
  20. 4.1 P is different — Items in P (chapter P) carry COSM's identity instead
  21. 4.2 Visibility — A hidden item is absent, not refused
  22. 4.3 Provenance — Sources or it didn't happen
  23. 5 The eight modules — Every concern has the eight modules, C · O · M · P · R…
  24. Chapter C · Corporation — The legal body: ownership, contracts, filings, money
  25. Chapter O · Organizations — Roles, teams, seats and who decides
  26. Chapter M · Markets — Chapter M · Markets, in The eight modules
  27. Chapter P · Products: the product tree — What it offers, and why that matters
  28. P.1 What P describes — P describes what a concern offers as a tree under its brand
  29. P.2 Levels (strata) — Five levels
  30. P.3 The nine questions (aspects) — Every item answers nine questions
  31. P.3.1 identity — identity, in The nine questions (aspects)
  32. P.3.2 flow — flow, in The nine questions (aspects)
  33. P.3.3 substrate — substrate, in The nine questions (aspects)
  34. P.3.4 rules — A rule is written as "<actor> <aim> <object>" under must, may or must-not
  35. P.3.5 principles — principles, in The nine questions (aspects)
  36. P.3.6 economics — Every offering has a price, none, or an open question (rule 3)
  37. P.3.7 vocabulary — vocabulary, in The nine questions (aspects)
  38. P.3.8 affect — Offerings must declare affect; other items may
  39. P.3.9 mattering — The aspect the rest exist for
  40. P.4 Roles, not people — People never appear in P
  41. P.5 Relations and inheritance — Relations and inheritance: Relations, Externals, Inheritance
  42. P.5.1 Relations — Six relations
  43. P.5.2 Externals — In a Holotype, P declares no externals of its own
  44. P.5.3 Inheritance — Three aspects flow down the tree; six do not
  45. P.6 The sketch (shorthand) — For whiteboards, interviews and chat
  46. P.7 The files of P — cosm: 0.3 heads each file
  47. P.8 Drawings — Every drawing is a view over the same items, never drawn by hand
  48. P.9 P's checks — Two levels
  49. P.10 How P renders for an audience — The internal rendering holds everything
  50. P.11 What COSM 0.3 described that Comprise OES 1 does not build — Kept as the map of where P can go
  51. P.12 Where COSM 0.3's text and the code disagree — The code wins in every row
  52. Chapter R · Representations and reflections — Chapter R · Representations and reflections, in The eight modules
  53. Chapter I · Inventories — SKUs a feed brings in live in the local database, not the files
  54. Chapter S · Stacks — Chapter S · Stacks, in The eight modules
  55. Chapter E · Employees — The people: counted here, never named
  56. 6 Paths — Every concern, module, kind, item and field has a path
  57. 6.1 Properties — A respelling
  58. 6.2 Grammar — A kind segment must be a kind of that module in the manifest
  59. 6.3 From an id to a path, and back — The module and kind levels have no id today; the path is their only name
  60. 6.4 Edge cases, settled — Edge cases, settled: P's brand item, Kinds that share a file, Relationships, Outside organizations
  61. 6.4.1 P's brand item — The brand's id has no kind: P:<slug>
  62. 6.4.2 Kinds that share a file — The kind level is a table, not a file
  63. 6.4.3 Relationships — A relationship between two concerns is written in both (3.2), with one id
  64. 6.4.4 Outside organizations — An outside organization is an ordinary item of C: mozilla-corporation/C/counterparty/google
  65. 6.4.5 Vendor-published atoms — A vendor-published atom's path is its id, vendor/<domain>/<slug>, and nothing below it
  66. 6.4.6 Fields — The field path is the one the checks already write for open questions
  67. 6.4.7 The qualified form — For use outside one install, a path is qualified with the MiniCOSM and the Holotype
  68. 6.4.8 Case, characters and what has no path — Ids and paths are case-sensitive and keep their case: meadow/O/role/Founder
  69. 6.5 Where paths are accepted — Beside ids, never instead of them
  70. 6.6 Scope and safety — A path to something the reader may not see answers exactly as its id would
  71. 6.7 Examples — Every example in this document resolves on the fixtures
  72. 7 References — A reference is an id written in a field: a foreign key
  73. 7.1 Forms — An item's own id is written bare in its concern's files
  74. 7.2 Where references are checked — The envelope's reference fields (section 4) and each kind's reference fields
  75. 7.3 Resolution — A bare id resolves in its own concern's module
  76. 7.4 Scope — A reference to an item the reader may not see stays as the id…
  77. 7.5 Named relations — plan/comprise-model.md names the cross-module relations (owner, holds, serves, sold-through, priced-by, maps-to or entitles, listed-on, runs-on…
  78. 8 Open questions — An open question (pending) is a value nobody has yet given
  79. 9 Checks — The checks (lint) are the constraints of the database, run on the whole Holotype
  80. 9.1 What runs — What runs, in Checks
  81. 9.2 The envelope's checks — The envelope's checks, in Checks
  82. 9.3 The fourteen rules — Each rule reports one of: pass, fail, unverifiable, finding
  83. 9.4 The verdict — ok: no error and no failed rule
  84. 10 Versions — A saved version (snapshot) is an immutable copy of the model files at a moment
  85. 11 The private/public split — Two formats, not one format with a setting
  86. 11.1 The private side — The files stay on the subject's machine
  87. 11.2 Renderings for an audience — Renderings for an audience, in The private/public split
  88. 11.3 The isotype: a view, default-deny — The isotype (comprise-isotype/0) is a separate document with a fixed schema
  89. 12 Renderers — A renderer turns a Holotype into another form
  90. 13 Conformance — Conformance: A reader must, A writer must, What the checks verify
  91. 13.1 A reader must — A reader must, in Conformance
  92. 13.2 A writer must — A writer must, in Conformance
  93. 13.3 What the checks verify, and what they do not — the load, the oes: declaration included (2.3); the id grammar; kinds per module
  94. 13.4 Where the code wins — Besides chapter P.12
  95. 14 Decisions in this version — Made by the writer of slice 30b, 2026-10-20, without asking, as the brief required

Glossary

ATTEST: allowed
ok, and no rule unverifiable — defined in §9.4 The verdict
checks
lint, equilibrium rules — defined in How to read this
concern
one bounded whole, described on its own — defined in §3.1 Concerns (atoms)
export for agents
export for agents, called pack in the files — defined in How to read this
group
a named set of concerns ("the group", a reporting segment), declared in the catalog's groups — defined in §3.4 Groups
item
item, called node in the files — defined in How to read this
kind
kind, called type in the files — defined in How to read this
ok
no error and no failed rule — defined in §9.4 The verdict
open question
a value nobody has yet given, written where the value would go — defined in §8 Open questions
outside organization
one the Holotype names but does not model — defined in §3.3 Outside organizations (stubs)
relationship
a typed, dated, sourced tie between two concerns — defined in §3.2 Relationships (bonds)
renderer
turns a Holotype into another form — defined in §12 Renderers
saved version, signed version
saved version, signed version, called snapshot, attestation in the files — defined in How to read this
the local database
the local database, called store in the files — defined in How to read this