This is a draft specification for review, dated 2026-09-24. It describes what a complete, portable Lolly tool is made of, so that any shell can open one and do the same things with the tool. If you build a shell, write tools at scale or review how Lolly records its work, read the chapter that touches your work and send what you find. Nothing in it is normative until the status chapter records that the review happened.
What the draft says
A Lolly document is a complete tool: its typed interface, the content someone authored, its dependencies, rules and behaviour, and the operations it offers. The glossary defines a tool as a directory holding a manifest, a template and optional hooks. A document is that material plus the state a person authored and the results of running the tool.
Four records carry a document: a definition, an instance, an evaluation and an artifact. Each carries its own schema version, and a reader may upgrade a record when it reads one. Records and identity shows the contract in this repository that already holds each one today.
An operation is what a tool can do: render, transform, extract, inspect, present or perform an authorised action. One tool may offer several, and the operation is the shared interface whatever produces the result underneath. A valid tool never needs a canvas. The on-device utilities take a file in and hand bytes out. Unpack, Prepare, Batch, Lolly Verify and the Lolly Rebrand review are web app routes rather than manifest tools; each gets a typed operation adapter with a typed outcome, and none of them needs a drawing surface.
Compositions, timelines and recorded sessions are optional. An authored instance and one evaluation of it keep separate identities, so a new organisation policy never rewrites what someone authored. Rules travel with a tool and may also arrive from a Lolly Work instance, which supplies the applicable rules and the authority that accepts a result. Governance never decides what a render or an operation means, because that meaning belongs to the definition. Outside a governed instance, the person at the keyboard holds the acceptance authority.
Status
| State | What it covers |
|---|---|
| Decided | Thirteen confirmed directions (D1 to D13), fifteen resolutions from evidence (R1 to R15) and six answered questions (Q1 to Q6). Nine corrections from the final review (C1 to C9) are folded in. |
| Open | The review of the chapters themselves. The draft notice stays until the status chapter records that people have read them. |
| Not built | Every type, every schema and every fixture. This draft adds nothing to packages/core and nothing to schemas/. |
The chapters cite each point by an id. A D id is a confirmed direction. An R id is a resolution proposed from evidence, which stands unless the review overturns that resolution. A C id is a correction the final review made before drafting started. A Q id is a question the maintainer answered on 2026-10-16, accepting the recommended defaults for Q1 to Q5 and recording Q6 as decided: the specification is public from its first draft.
A focused review of digital asset management on 2026-10-15, and a production review after it, added requirements: exact source files, imported evidence, review scope, current source and processing authority, typed content and locale bindings, explicit action targets and asynchronous readiness among them. The four records and the Lolly Design, Lolly Chart and Agenda pilots stay as they are. Cases 30 to 44 describe the new requirements, which are not yet contract fixtures. The status chapter records the review's scope and the remaining work.
Where to read the specification
The specification is its own web document, twelve chapters long. Read it in the app, with the chapter list, the headings and a search field beside the text. The same chapters are on this site:
The model
- Constitution: the thesis, the four records, the vocabulary and the thirteen invariants.
- Records and identity: which contract holds each record today, with its file path.
- Source rows, payloads and patches: flat rows, one owner pointer, typed payload records and the patch envelope (R1).
- Operations and outcomes: the six operation shapes, one outcome vocabulary and the output target a render satisfies (R5).
- Values, expressions, code and time: typed values, the expression language, the eight hook protocols, the execution classes and the five clocks (R2, R3).
- Evaluation and receipts: the pipeline, the three recording axes and what a receipt records about one run (R15).
Rules, trust and status
- Constraints, authority and local choice: rule classes, the three attributed layers and the effective policy an evaluation ran under (R6, R7).
- Conformance and fidelity: conformance suites, core and extended features, the three-check comparator and acceptance (R8, R9).
- Capabilities, trust and extensions: capability limits, extension declaration, dependency scopes and refusal by name (R10).
- Packaging, identity and migration: the container, retained package state, migrations and the frozen wire order (R11).
- Proof cases: every counterexample the model has to answer, each to be built after review.
- Status and open points: decided, corrected, open and not built, with a dated change log.
The twelve chapters are also written out in order as one file, document-model.md, for reading offline or handing to an agent.
How to review a chapter
Read a chapter, then send what you found, quoting the chapter and heading. Open an issue on the repository.
What this draft does not claim
- No conformance for any shell. A conformance suite produces a measured report and an authority records an acceptance; the two are never merged (R8).
- No threshold. The comparator probe in the conformance chapter shows only that one whole-image number cannot separate a lost caption from a half-pixel shift. Calibration comes after review (R9).
- No frozen type. The counterexamples in the proof cases must pass as contract fixtures before anything is added to
packages/coreorschemas/. The shared core typesDependencyGraphV1,ComponentDefinitionV1,OutcomeV1andFindingV1follow the same rule: they may be added after those fixtures pass, and not earlier. - No determinism or reproducibility claim beyond the ones Determinism and Reproducibility already make.
- No cloud dependency. The core evaluates on the device. A governed client that loses its connection must keep enforcing the policy it holds (R7). The web app does not do that yet: once its cached copy is 24 hours old and the server cannot be reached, it fails closed (policy chapter).
- Nothing about spatial output or fabrication beyond an extension boundary. Both stay written explorations, and this draft commits to building neither (D5).