@loadbare/app 0.7.3 → 0.7.4

package/docs/analysis-closed-set.md

@@ -0,0 +1,203 @@
+# A closed set for the Loadbare/app vocabulary
+
+> **LLM-authored, not yet revised by a person.**  Drafted by Claude on
+> 2026-09-13, from a design session against `@loadbare/app` 0.7.3 while
+> building a chart of accounts page.  Treat it as a proposal, not as the
+> author's statement.
+
+## The question
+
+Relational algebra is closed: every operation takes relations and returns a
+relation.  CRUD is closed in the same way on the write side.  Closure is what
+makes both easy to program against.  Combinations do not explode, the cases
+are finite, and nothing falls outside the model.
+
+Loadbare/app maps three data shapes (cell, row, list) and three relational
+operations (insert, update, delete) into HTML.  This document asks whether
+recent iterations have shown enough to state a **closed** vocabulary and set
+of behaviors: one where every combination of shape, operation, position,
+nesting and timing is defined, so application code never meets an edge case
+outside the model.
+
+Author note: a page can of course define invalid combinations, but their
+lack of validity must be intelligibly reported as a failure to stick to the
+closed set.
+
+"Closed" is tested four ways:
+
+1. **Shapes are closed.**  Everything a page receives is one of the shapes,
+   or a patch on a list.
+2. **Operations are closed over shapes.**  Each operation yields a defined
+   result in the same vocabulary.
+3. **Composition is closed.**  Nesting, many scopes bound to one name, scopes
+   that appear late, and several names in one response all stay inside the
+   rules.
+4. **Anything outside the spine is justified.**  It either reduces to the
+   spine or is a separate, deliberately bounded axis.
+
+## The model in one sentence
+
+> **A page holds named relations.  Every read and every write answers with
+> new values for those names.  Every scope is a view of one name.**
+
+Every rule below follows from it.
+
+## 1. Shapes: three, plus identity
+
+| Shape    | Attribute                                   | Relational                                                        |
+| -------- | ------------------------------------------- | ----------------------------------------------------------------- |
+| list     | `lb-list`                                   | a relation, as a variable that holds rows                         |
+| row      | `lb-row`                                    | a single row, read-only; a writable single row is a list of one   |
+| cell     | `lb-cell`                                   | a column value                                                    |
+| identity | `lb-key` written, `lb-key-value` stamped    | the primary key                                                   |
+
+## 2. What every answer is made of: three forms
+
+Every query, CRUD operation, declared action and refresh answers with
+`{ name: result }`, and each result is one of:
+
+- **a whole list** (an array), which replaces the relation, membership and
+  order included;
+- **a patch** (`{ rows, drop }`), which upserts rows by key and drops keys;
+- **a row** (an object), which replaces the single row.
+
+This is the closure property.  No operation answers with HTML, a redirect, or
+instructions.  Declared actions are open-ended, like stored procedures, but
+their results are still in these three forms, so the landing side stays
+closed.
+
+## 3. Operations: three, plus one open door
+
+| Operation        | Takes from position    | Carries                                      | Answers      |
+| ---------------- | -------------------    | -------------------------------------------- | ------------ |
+| `lb-row-insert`  | list                   | values, gathered from the record             | patch rows   |
+| `lb-row-update`  | list, key              | values, gathered or supplied by a widget     | patch rows   |
+| `lb-row-delete`  | list, key              | nothing                                      | patch drop   |
+| a declared name  | list or row, key, cell | value                                        | any names    |
+
+### Proposed: fold `lb-cell-change` into `lb-row-update`
+
+A cell change is an update whose `values` holds one entry, and the hub
+already keeps `values` a widget supplies.  SQL has one UPDATE whether it sets
+one column or many.  On the server, `cellChange` and `rowUpdate` merge into
+one `update(key, values)`, where a column absent from `values` is left as it
+is.
+
+### Reordering is not an operation
+
+Position is not a relational concept; order is a column.  A drag is an update
+to an ordering column such as `display_order`, which the wire already
+carries in `values`.  No move operation is needed, and no field for "where
+the row went".
+
+## 4. Position: taken from the page, never written in the request
+
+- An element's own attributes say what it displays.  Its ancestors say where
+  it belongs.
+- A nested scope begins a new scope.
+- A request is an action plus a position.  The hub supplies the position;
+  only an interaction supplies a value.
+
+These are the rules [Theory](./theory.md) already states.  They are listed
+here because closure depends on them.
+
+## 5. Landing: every combination defined
+
+| Result → target | list scope   | row scope                         | no scope yet               |
+| --------------- | ------------ | --------------------------------- | -------------------------- |
+| whole list      | reconcile    | error: one name has one shape     | stored                     |
+| patch           | upsert, drop | error                             | applied to the stored copy |
+| row             | error        | fill                              | stored                     |
+
+A result lands on every scope bound to its name, at any depth of nesting.
+0.7.3 already does this: a patch to `groups` reaches a picker in every row of
+an outer table, and the outer list's reconciliation does not mistake the
+picker's rows for its own.
+
+### The missing rule: timing
+
+In 0.7.3 a scope that appears after its name has landed stays empty.  A row
+added to an outer list by a patch starts with every nested list empty, and a
+widget's scaffolding built during landing, such as a ghost row holding a
+picker, starts empty too.  Pages work around it by ordering their queries so
+the outer list lands first, which only covers the first load.
+
+The closed rule:
+
+> **The hub holds each name's current value.  A scope shows that value
+> whenever it appears.**
+
+In relational terms a name is a relation variable, results are assignments to
+it, and scopes are views of it.  Whether a scope existed before or after its
+data arrived stops mattering.
+
+It also settles several things that were not worked on directly:
+
+- The blocker in [TECHREF-1.0](./TECHREF-1.0.md), "Decide how a new row
+  fills a nested list".
+- Pickers in newly created rows, and pickers in ghost rows built after the
+  first load.
+- Query order in a page's queries file stops mattering.
+- **What a partial patch row means.**  A patch row upserts by key, and a
+  column it does not name is left unchanged, as an SQL UPDATE leaves it.
+  The reference is silent on this today.
+- "No scope for a name" becomes an ordinary state rather than a console
+  warning, since a scope may simply not exist yet.
+
+#### Mechanism
+
+- The hub fills a cloned row, nested scopes included, before inserting it.
+  This extends the rule it already follows of filling before insertion.
+- After each landing, it sweeps for scopes that have never received data.
+  For a list, an absent `lb-row-count` already marks one.  A row scope would
+  need an equivalent mark.
+- A widget that builds scopes outside a landing, at some later time, would
+  need a `MutationObserver`.  No widget built so far does that.
+
+#### What would prove it wrong
+
+A case where the stored copy and the document legitimately disagree.  The
+only candidate is a control holding an edit not yet sent, and landing already
+overwrites that in 0.7.3, so the rule introduces nothing new.
+
+## 6. State attributes: four, stamped by the hub, read by CSS
+
+`lb-value`, `lb-row-count`, `lb-pending`, `lb-error`.
+
+## 7. Outside the algebra, deliberately bounded
+
+- **Composition at build time:** `lb-slot`, `lb-template`.
+- **The host channel:** `lb-page`, `lb-nav-link`, `lb-unknown-page`, and the
+  hub's own `lb-navigation` row.  That row already shows the hub's own state
+  landing through the same three forms.
+- **The widget protocol:** the `lb-request` event, which an ancestor may
+  stop, and the `lbPlaceRow` and `lbRowsLanded` hooks.
+
+## What this changes in 0.7.3
+
+1. The hub holds each name's current value and fills scopes that appear
+   late.
+2. `lb-cell-change` folds into `lb-row-update`, with widget-supplied
+   `values`, and the server's `cellChange` and `rowUpdate` merge.
+3. The reference states the patch row rule: upsert by key, unnamed columns
+   unchanged.
+
+Everything else is the current vocabulary, now justified as closed.
+
+## What the evidence has not settled
+
+Everything above is backed by pages already built.  These are not:
+
+1. **Parameters and view state:** a filter, a selection, a collapsed
+   section.  The likely closed answer is that URL query parameters become
+   columns of the `lb-navigation` row and reach queries as arguments, as
+   `<form method="get">` puts its fields in the query string.  No page needs
+   it yet, so this is a prediction rather than evidence.
+2. **Checkboxes and data types:** probably HTML's presence-or-absence
+   convention, still undecided.
+3. **Concurrent writers:** staleness is a property of the stored copy, so
+   the rule in section 5 makes this question easier to state without
+   answering it.
+4. **Error content:** `lb-error` records that a round trip failed, not why.
+   A closed answer would deliver the message as a result like any other,
+   perhaps as a hub row.  Untested.