rose-ash/plans/relations-as-posts.md

Relations as posts — declared, inherited, and eventually algebraic

Principle

Everything is a post in one graph: content-posts, type-posts, relation-posts, and (later) constraint-posts. Nothing about typing is hardcoded — a type-post declares which relations it anchors, declarations are inherited down the type closure, and every candidate set / validation is a transitive graph query (lib/relations). This closes the meta-circular loop the typing plan gestured at: the type system describes itself in its own graph.

Supersedes the hardcoded :candidates "types"/"tags"/"all" field of host/blog-rel-kinds.

North star — the metamodel as a system-construction kit

The destination this is all heading toward: the host stops being "a blog" and becomes a self-describing metamodel. You define a domain — types (with schemas/refinements) and relations (with role signatures + algebra) — and a working system falls out. The blog content is one seeded configuration; clear it and define different types and you have a different system on the same engine. Framework, not application (cf. [[feedback_runtime_control]], [[project_zero_dependencies]]).

Most of the instance UI is already generic — the edit page's relation editors are generated by iterating the relations; each picker's candidates come from the relation's declares-anchor / role type; validation comes from the type's :schema. So once Slices 6–7 land, "define the types" through a UI is mostly two surfaces, plus a reset:

1. Metamodel editor — create a type-post (give it a schema/refinement); create a relation-post (give it a role signature + algebra). The thing that lets you construct a system.
2. Generic instance form — create/edit any post of any type, driven entirely by the definitions above (the relation editors + pickers + save-time validation we already have).
3. Clear-and-reseed — wipe instance data, seed only the metamodel roots (type, relation, the core relations); start from a bare kit and build a domain up from nothing.

Sequence: finish the schema language (Slices 6–7) → the two UI surfaces + reset → clear the demo data and define a real domain through the UI. The slices below are the schema language; this is what it's for.

Endgame — the whole platform as a typed domain (the strangler's finish line)

Not just the blog: the entire rose-ash platform — store, events, orders, cart, … — is expressible as type + relation definitions in this one metamodel. Product, Event, Order, Ticket are types; "cart has line-items", "order for an event", "ticket of an event" are relations with signatures (cardinality = a cart has many line-items, a ticket belongs to one event). This is the completion of the host-on-sx strangler off Quart ([[project_host_on_sx]]): define the domain schema as data instead of porting each service's bespoke models.

Three honest additions store/events surface (the blog didn't need them):

1. Typed scalar ATTRIBUTES, not just entity relations. A Product needs price: Money, sku: String, stock: Int; these are values, not edges to posts. We've built RDF object properties (edges to resources); this needs datatype properties (literals with value-types + validation). So a type declares fields {field, value-type, card, required, validation} alongside relations; instances carry typed values; value-types (Money, Int, DateTime) are primitive types. Same shape as a role — a role points at a type, a field holds a value-type. This is a real addition to a/b/c+d and likely Slice 8.
2. Behaviour / lifecycle (order pending→paid→shipped) is NOT structure — it's the substrate loops: [[project_flow_on_sx]] (durable workflows), [[project_commerce_on_sx]], [[project_events_on_sx]]. The metamodel attaches behaviour to types by composing those, not reinventing them.
3. Integrations (SumUp payments, ActivityPub federation, artdag media) — types reference these services; they don't dissolve into posts.

So the complete picture: the metamodel expresses structure + validation of the whole platform's domain model uniformly; behaviour composes from the substrate loops; integrations stay referenced services. It's the convergence point of every loop in the repo.

Behaviour as data — lifecycles + ECA over an effect vocabulary (DESIGN — Slice 9)

Structure is inert; "place an order / ship goods" is the dynamic part. The principle: behaviour is data-defined orchestration over a small fixed vocabulary of effects. Only two layers stay code — the effect primitives (the irreducible ops that touch the world) and the interpreter that runs the data. Everything between is editable posts. The system defines its own behaviour down to the effect boundary ([[feedback_runtime_control]]).

Shape. A type declares a lifecycle (a state machine) as data, plus standalone ECA rules for reactions that aren't state transitions:

Order: cart --place--> placed [guard: stock-available ∧ total>0] [effects: reserve-stock]
       placed --pay--> paid   [guard: payment-ok]               [effects: charge-card, confirm-stock]
       paid --ship--> shipped [guard: address-valid]            [effects: create-shipment, notify]
ECA:   when stock(product) < threshold  =>  notify(buyer:owner, "restock")

• States/transitions/rules/effect-invocations are all posts — meta-circular: Lifecycle, Transition, Rule, Effect are themselves types in the metamodel; a behaviour is instances you edit in the same UI as the schema. A transition = {from, to, on-event, guard, [effects]}.
• Guards are PURE — predicates over the instance's attributes/relations, i.e. type-system queries (Datalog). No side effects, analysable, you can diagram a lifecycle.
• Runs on [[project_flow_on_sx]] because it's durable + long-running: placed→paid waits for a SumUp webhook, paid→shipped waits days. flow's suspend/resume IS this. Failures → compensation (saga) — commerce-on-sx already does "refund as a flow".
• "Place an order" / "ship" = attempt transition T; the button/webhook just fires the event.

The effect vocabulary (sketch — store + events)

An effect is a named, parameterised op (itself an Effect post: name + params + binding). Behaviours reference effects by name with args bound to instance/context. Four tiers:

Tier	Effect	Notes
Pure guard (read-only, not an effect)	is-a? / attr-cmp / count / relation-exists?	type-system queries (Datalog); compose the transition guards
Data (internal, transactional on the graph)	create(type, attrs), set-attr, set-state, relate / unrelate, incr / decr, append-ledger(entry)	the durable post-graph mutations; decr stock is atomic-with-check
Domain (composed from data, named for atomicity/meaning)	reserve-stock, release-stock, confirm-reservation, book-seat, issue-ticket	small compositions the vocabulary blesses; events-on-sx has the capacity-safe versions
Integration (external services — the code edge)	charge-card, refund (SumUp), create-shipment / track, notify(recipient, template, data), federate(activity) (ActivityPub), process-media(asset) (artdag)	the irreducible primitives; keep this list SMALL and composable (artdag's S-expression effects is the model)
Control (durable orchestration — flow primitives)	wait-for(event), wait-until(time) / after(dur), emit(event), transition(instance, state)	wait-for = the SumUp webhook / shipment-delivered; after = reservation-expiry / event-reminder; emit chains ECA rules

So place order = guard stock-available ∧ total>0 → effects reserve-stock, set-state placed, emit order-placed; the webhook later fires pay → charge-card, confirm-reservation, set-state paid. Events reuse the same machinery: ticket reserved →(after 15m, no pay)→ released, event --remind(after)--> notify digests. Almost all of it is the same vocabulary.

The one fork (same shape as the type-system line)

• Declarative core — lifecycles + ECA + the effect vocabulary: safe, analysable, diagrammable, editable by non-programmers, verifiable. Covers ~95%.
• Guarded code escape-hatch — a Scheme/Smalltalk snippet stored on a post and eval'd for the rare bespoke guard/effect ([[project_content_on_sx]] is Smalltalk message-passing, [[project_flow_on_sx]] is guest Scheme — the homoiconic door exists). Turing-complete, unsafe, fenced — exactly the decidable-core / fenced-frontier split we drew for types.

Where to start: pin down the effect vocabulary above (the real design artifact), build the generic interpreter on flow-on-sx with pure (Datalog) guards, and lift commerce-on-sx / events-on-sx from guest-code into lifecycle+effect DATA — they already implement exactly this, just not editably.

Why (the wrinkle that started this)

Candidates for is-a/subtype-of were instances-of("type") — the instances that are types, but NOT the type-defining posts themselves (type, tag, article are wired with subtype-of, no is-a edge, so they're not instances of type). So the picker offered tutorial (is-a tag) but never tag/article/type — the things you most want to say a post is-a. The fix is to ask the right question: a candidate is anything that inherited the relation's object-end declaration from the anchor, which includes the roots.

Model

• A declaration is an edge T --declares--> R: type-post T anchors relation R at its object end ("you may point at T with R"). Seed: type declares is-a, type declares subtype-of, tag declares tagged. related has no declaration.
• Candidate set for relating under R = the down-closure of R's anchors through inverse(is-a) ∪ inverse(subtype-of) (a post is a candidate iff it is, transitively, an instance-or-subtype of an anchor — or IS one). No anchors ⇒ every post (related).
  • is-a/subtype-of: anchors {type} ⇒ the whole type closure (roots + subtypes + instances). Wrinkle fixed.
  • tagged: anchors {tag} ⇒ the tags.
  • related: no anchor ⇒ all posts.

Roadmap

Slice 1 — declarations + candidate-by-inheritance — DONE

• Seed declares edges; add host/blog--reach-down (down-closure) and rewire host/blog--candidate-pool to be declaration-driven. :candidates becomes vestigial.
• Wrinkle fixed: the type roots now appear as is-a candidates.

Slice 2 — relations as first-class posts — DONE

• relation root + is-a/subtype-of/tagged/related seeded as posts (each is-a relation) owning their metadata in a :rel slot (:symmetric :label :inverse-label). host/blog-rel-kinds / kind-spec / kind-symmetric? now read it; the static registry is gone. host/blog--rel-slugs = host/blog-in "relation" "is-a" (cheap, flat).
• Perform budget under http-listen (the hard lesson): a durable read inside the render VM raises VmSuspended, and too many per request 500s the page. Two fixes: (1) relation metadata is loaded into an in-memory cache at boot (host/blog-load-rel-kinds!, like load-edges!) so kind-spec is pure; (2) the initial edit page renders its pickers EMPTY (the load trigger fills each) — only the relate/unrelate FRAGMENT server-renders candidates (with-cands flag), so one page render doesn't do candidate-get × every picker. Benign single-perform suspend/resume still logs VmSuspended but returns 200.
• Live JIT gotcha (cost real time): the serving-mode JIT drops all-but-first when map/for-each-ing a function-produced list — building rel-kinds that way rendered only 1 of 4 editors live, while conformance + the ephemeral server passed. So host/blog-rel-kinds is a VALUE the boot populates and the cache loads are UNROLLED. Conformance green ≠ correct live — verify the rendered edit page. (Re-fold the enumeration once plans/jit-bytecode-correctness.md lands.)

Slice 2.5 — picker title reads are O(page), not O(pool) — DONE

• relate-candidates computes the available candidate SLUGS (slug-sorted, no per-candidate read), then reads titles ONLY for the page it returns. On the unfiltered path (q="" — the initial picker load AND every editor server-fill, the common case) that's ~limit reads instead of one-per-post — killing the durable-read churn under http-listen. A filter (q≠"") still resolves titles across the pool (it matches on the title), but that's the interactive path.
• A boot-time slug→title cache would make even the filter O(1)-perform, BUT it's blocked for now: there's no bulk KV read, and a per-post host/blog-get loop at boot hits the JIT bug (a durable read inside a boot loop drops all-but-first — load-edges! only works because its loop body is perform-free). Revisit with a bulk read or once the JIT lands.

Remaining follow-ups: subject-end declarations (who may be the source); a proper relation-subtype closure when relations get subtyped; the boot title cache above.

Slice 3 — typed relations (target-type constraints) — DONE

• The declaration's declares-anchor IS the target-type constraint: is-a/subtype-of (anchored by type) require a type object; tagged (anchored by tag) a tag. A new wrote relation needs only a Work declares wrote edge — fully data-driven.
• host/blog--valid-object?(kind, other) = other ∈ candidate-pool(kind) — the SAME set the picker offers, so picker and validation agree by construction. relate-submit now enforces it (an invalid target is a silent no-op, like the other guards); related (no anchor) accepts any post. The picker never offers an invalid target, so this guards crafted/API requests — the jump from "candidate set" to an enforced relation schema.
• NOTE: host/blog-relate! (direct/seed) stays UNVALIDATED — the seed needs to write X is-a relation where relation isn't under type. Validation is a handler boundary.

Slice 4 — type algebra — DONE (intersection ∧ union)

• An algebraic type is a post with operand edges: conj edges (intersection members), disj edges (union members). host/blog-instances-of-expr computes its EXTENT from the operands' extents by set intersection / union, RECURSIVELY — so operands can themselves be algebraic (meta-circular; tested with (tag ∧ article) ∧ tag). host/blog-is-a-expr? generalises is-a? to type expressions. host/blog-make-and! / make-or! build them.
• Binary today (nth 0/1, no fold over operands — robust on the serving JIT); n-ary fold is a follow-up once iteration-with-perform is JIT-reliable.
• Operand edges are KV-only (host/blog--add-edge-kv!, read via host/blog-out), NOT in lib/relations — feeding extra kinds into the Datalog graph blows up its per-query re-saturation; load-edges! skips conj/disj on replay for the same reason.
• Refinement {x : T | φ(x)} (a type-post with a :constraint predicate) → Slice 5, with constraints-as-posts. (Process note: a sibling loop running heavy conformance saturates the box; host conformance can EXIT 124 purely from CPU contention — use timeout 1200.)

Slice 5 — refinement types (schemas ON the type-post) — DONE

• A type-post carries its schema in a :schema slot (a list of {:block :msg} rules — a refinement {x : T | x has these blocks}). host/blog-schema-of reads it off the post; the hardcoded host/blog-type-schemas table is gone. A NEW refinement type is pure data: give a type-post a :schema (host/blog--set-schema!) and its instances are validated on save against it — no code. Tested with a guide type requiring a pre block.
• Save-time validation (type-issues/type-valid?, the only callers, in the SAVE request) unions the schemas of a post's full transitive type set — unchanged, just sourced from the posts. schema-of reads the post (a durable read) — fine in the save request, never render.
• host/blog-put! now MERGES over the previous record, so editing a post's title/content doesn't nuke its :schema / :rel metadata (also closes the Slice 2 "edit drops :rel" gap).
• article's schema migrated onto the article post (set-schema! at boot — a single read+write, not a loop, so boot-JIT-safe; idempotent, handles the already-seeded article).
• FUTURE: arbitrary predicate constraints (not just required blocks); constraints as their own posts; relation cardinality (is-a single-valued?) as a declared constraint.

Parameterised relations (DESIGN — Slices 6 & 7)

The next axis: Relation<…>. The key reframe is that the obvious parameters aren't separate <N>s — they split into two halves, and they compose into one coherent thing:

1. The role SIGNATURE (the shape of a tuple) — Slice 6 (a + b + c).
2. The relation's ALGEBRA (how it behaves) — Slice 7 (d).

A relation is Relation<signature>, where a signature is an ordered list of roles, each role carrying a type and a cardinality; the signature's length is the arity. Today's binary typed relations are the degenerate 2-role case — backward-compatible, nothing gets thrown away. Prior art to borrow (and stay decidable within): Codd / ER reified relationships (signature), OWL property characteristics (algebra), Datalog / relation algebra (derived relations — the undecidable frontier; fence it). Decidability rule of thumb: concrete

• algebraic role-types and counts stay decidable; arbitrary predicates / recursive rules don't.

Slice 6 — the role signature (a + b + c)

Generalise the relation-post's :rel slot from {:symmetric :label} to a :roles list — {:roles [{:name :type :card} …]} — driving picker candidates, validation, and arity per-role:

• (a) per-role type — each role's :type is a type-expr (so it can be algebraic: Relation<Work ∧ Published>). The object-role's type IS today's declares-anchor — make it explicit. valid-object? becomes per-role is-a-expr? against :type.
• (b) arity = (len roles). Binary stays the fast src|kind|dst edge path; n-ary needs reification: a relation instance becomes its own post with role edges (subject→X, object→Y, recipient→Z) — on-brand (we made relation kinds posts; now instances too), but a SECOND representation alongside the binary edges, not a tweak. Qualifiers (Wikidata- style) then come free as extra roles.
• (c) cardinality — :card per role (min/max; functional = max 1, required = min 1), enforced on relate by counting. Composes with Slice 5 validation. No model change for binary.
• Siblings: ordered roles (set vs list), keys/identity (which roles identify a tuple).
• Layering (cheapest → deepest): (c) cardinality on the binary object-role → (a) explicit role-type + the 2-role signature abstraction → (b) reified n-ary (the real lift).
• Variance: nominal, none initially — no structural subtyping of Relation<…> (covariance of parameterised types is a research project). JIT caveat: 2-role signatures are unrollable; n-ary role-iteration with per-role reads needs the cache/unroll treatment (Slice 2/5 lesson).

Slice 7 — relation algebra / characteristics (d)

The behaviour half — and (d) transitivity is special because we ALREADY hardcode it (is-a/subtype-of closure via lib/relations); declaring it generically removes code.

• Algebraic properties declared on the relation-post (:transitive :symmetric :reflexive :antisymmetric :irreflexive), with the closure derived generically from them — OWL's property characteristics. subtype-of becomes "a declared transitive + antisymmetric relation" (a partial order), not a special case. :symmetric (already stored) folds in here.
• Inverse relations — a real :inverse (not just the :inverse-label display hint): relating one auto-derives the converse, the way :symmetric writes both directions.
• Sub-relations — relations subtyping relations (wrote subPropertyOf created): X wrote Y ⟹ X created Y. Same subtype-of machinery, over the relation root — meta-circular.
• Decidable core stops here. Beyond-d, FENCED: defined-by-rule relations (composition, grandparent = parent ∘ parent — straight onto the Datalog substrate, but gate to stratified/bounded rules) and cross-role refinement predicates (start < end) — both need the predicate-language-vs-embedded-code decision first.

Open design questions (track as we go)

1. Subject-end declarations — who may be the source of a relation (a root Thing?).
2. Inheritance path — through is-a AND subtype-of downward (current choice); revisit if instances-of-instances as candidates surprises.
3. Bootstrap / meta-circularity — is-a needs is-a; seed relation-posts + Type is-a Type(?) idempotently, as the type seed already is.
4. Cost — reach-down is a BFS of direct-edge scans; fine for a small blog, revisit with a lib/relations transitive query if the graph grows.