Lolly Beta
Launch App

Evaluation and receipts

This chapter is a draft for review, dated 2026-09-24.

This chapter specifies how one operation is evaluated and what a run may record about itself. It restates the evaluation and recording contract in normative form. It adds R15 for the receipt, and it carries the review's correction that an unmet declaration is refused at the operation boundary. The operation shapes and the outcome a terminated run returns are specified in Operations and outcomes. The typed values, the budgets, the execution classes and the clocks this pipeline reads are specified in Values, expressions, code and time. The rule set it evaluates against is specified in Constraints, authority and local choice.

The pipeline is nine steps

The pipeline puts capability and operation selection ahead of dependent work (plan section 9). It states which step depends on which. It does not state that one run passes through every step. An operation that produces no artifact still reaches step 8, because step 8 is also where a typed result is returned. It simply terminates with a result and an empty artifacts[], which R5 keeps apart and C3 requires (R5, C3, D11).

The nine evaluation steps in order, with inspection before any document code runs and refusal raised at the operation boundary rather than at parse timeOpen this in Diagram Builder

  1. Inspect and parse. Read the package without executing document code. Validate the schema version, the integrity map, the structure, the declared limits and the extension declarations. Read extensionsRequired here and refuse later, at step 2.
  2. Select. Choose the operation, the output target and the execution class. Determine the effective policy and the permitted capability envelope. Refuse here when a declaration read at step 1 is unmet for this operation.
  3. Negotiate. Settle support and select the declared fallbacks before any dependent computation or effect. Resolve only permitted resources, against immutable revisions and digests.
  4. Snapshot. Validate and snapshot the typed inputs and the authored state. Resolve token scopes, locale, clocks, seed and environment.
  5. Instantiate. Expand components into an identity-preserving evaluation graph. Evaluate expressions and domain rules under their budgets. Reject invalid cycles and unresolved required values.
  6. Resolve. Settle layout or other domain constraints and apply the declared invalidation when state, time or a measurement changes.
  7. Validate. Check the plan or the output against the effective policy, including proposed repairs and findings.
  8. Act. Render, present, return a typed result or commit the authorised effects.
  9. Report. Return an outcome and the receipt the recording policy permits.

A host must run steps 1 and 2 before step 3, because a resource resolved for an operation that was never selected is work done outside the grant (R3). A host may merge later steps, and a host may repeat steps 5 and 6 under the invalidation rules (plan sections 9 and 8.3), so the numbering is a dependency order and never a pass count.

Inspection runs no document code

Step 1 must never execute a tool's hooks, template or expressions. validateDocument in engine/src/document-api.ts is the shape: with a manifest target it answers through validateManifest in engine/src/validate.ts and runs nothing of the tool. A host must answer an inspection from declarations alone.

compileDocument in the same file calls createRuntime, which runs the onInit hook before it hydrates the template, so a compiled document is the product of execution and never the answer to an inspection. A host must never reach for the compile verb to satisfy step 1.

The declared dependency envelope and the dependencies discovered during execution must be reported separately (R15). The declared side is already answerable from engine/src/document-api.ts without running the tool; the discovered side is what the receipt's inputs[] records. A host that merges them cannot later report which resource the document declared and which one the run discovered while executing.

Refusal happens at the operation boundary

An unmet requirement must be refused for the operation and the output target that need it, never at parse time for the whole package (R10, R11), which is the boundary the four gates in packages/core/src/host-v1/apis.ts and schemas/tool.schema.json already refuse at.

An unsupported motion extension must never prevent safe inspection of the same package. A host must therefore record the unmet declaration at step 1 and raise it at step 2, against the selected operation. The outcome for the refused operation terminates as blocked, which Operations and outcomes specifies, and the refusal must name the missing item so a caller can act on it. Capabilities, trust and extensions specifies refusal by name.

One gate already refuses by name before any document code runs, though it is scoped per mount rather than per operation. missingRequires in packages/core/src/host-v1/apis.ts compares a manifest's requires against the optional host APIs a shell actually provides, and engine/src/runtime.ts throws before any hook runs. The model keeps the public requires field with the meaning it has today and scopes the refusal to the operation (R11).

Dynamic dependencies stay inside the grant

Dynamic dependencies remain possible. A late resource or capability request must fit inside the grant the run already holds, or the run must stop and ask for an explicit additional grant (R3).

One precedent in the tree supports the first rule. schemas/tool.schema.json makes the network capability fail closed: without a network.allowlist block, or for a URL no entry matches, every host.net.fetch rejects, and createNetAPI in packages/node-shell/src/net.ts is where that rejection is raised for every shell. A late fetch to an unlisted host is refused rather than negotiated. The third rule has its own: the ComposeAPI contract in packages/core/src/host-v1/compose.ts requires the host to reject a nested render whose stack already holds the child's toolId, or that exceeds the maximum compose depth, so a child render is bounded before it starts.

The second rule has a measured cause. HOOK_BUDGET_MS in engine/src/runtime.ts races an async hook against its budget, and the comment records what the race does not do: the hook's own code keeps executing after the wait is abandoned, because there is no preemption inside the JavaScript realm it runs in. A grant that outlives the attempt would therefore let abandoned code commit an effect for a run that already terminated.

Visual intent, an amendment of 2026-11-05

Invariant 1 of the constitution asks the source to record meaning, parameters and permitted changes rather than renderer internals. A visual intent applies that invariant one step before a document exists: a caller states what a piece has to do for its reader, where it will be seen and what it has to say, and evaluation chooses the definition and the instance. This amendment records the first slice, which is built and shipped ahead of the rest of this draft. It freezes no record of this model.

VisualIntentV1 and IntentResolutionV1 live in packages/core/src/intent-v1.ts, and resolveIntent in engine/src/intent.ts is pure and takes the tools it may consider. It belongs to steps 2 and 3 of the pipeline. It selects the tool and the output target for each surface and negotiates support, and it refuses at the operation boundary. It runs no document code: like step 1, it answers from declarations alone. A host may filter the tools by effective policy before calling, so the choice can never reach a tool the caller may not use.

A resolution keeps three kinds of value apart, because they are treated differently wherever they are stored. Closed values are vocabulary and repository facts: purpose, surface, language, chosen tool and rules version. Free text is what a caller wrote about the circumstances: occasion, audience and region. The prompt is what a user first said to an agent. Nothing that decides reads the free text or the prompt, so neither can change a choice. A request that gives a prompt and no purpose is answered with the code intent.purpose-needed and the vocabulary, so the agent that can read its own user's words chooses the purpose, and no model enters this path.

A render that starts from an intent may record it in the artifact, as the tools.lolly.intent assertion in its Content Credential. Closed values read as themselves. Free text and the prompt are sha256: fingerprints, unless that run asks to record the prompt's words. The record states what was asked for and which tool answered, and a run reports it only from a readback of the finished file.

This slice adds no field to a receipt. It chooses among tools, not layouts, so locale contracts, adaptive layout and the campaign resolution of plan 338 remain unbuilt, and it does not read the result to check the choice. Its rules carry their own version, closed.rulesVersion, and a later rule change must bump that version.

Recording is three axes

Rendering, reconstruction, capture and retention are independent properties (D11). A run declares three axes together, and replay is the one that answers for reconstruction.

draft shape

  recording
    capture     unsupported | off | on     can external observations be captured, and were they
    retention   none | session | durable   may the capture be kept, and for how long
    replay      none | semantic | byte     what a replay can promise under the same conformance suite

This is a draft shape for review, not a type. No shared type is frozen until the counterexamples in plan section 17 pass, so nothing is added to packages/core or to schemas/ in this wave (plan status line; Codex recommendation).

The three must be read independently (D11). A reproducible transform may have no rendered frame. A visual interaction may retain no input recording. A recording may exist while replay is unavailable, because the executor that would replay it is missing. A host must never infer one axis from another, and a host must never treat capture: unsupported as a failure.

An outcome is immediate, a receipt is conditional

Every operation must return an immediate outcome (R5, D11). A durable receipt and any retention of raw input are conditional on the recording policy.

Adopting this model must never turn a local utility into a permanently logged one (plan section 9.1, D11). A tool that declares privacy: 'on-device' in its manifest processes the person's own content, and engine/src/runtime.ts already stamps nothing into its output: no provenance metadata and no watermark. Retention for such a run follows the recording policy and defaults to none under Q4 below.

A receipt is therefore optional on the outcome. A caller must treat an absent receipt as "no receipt was retained" and never as "the run was not evaluated".

EvaluationReceiptV1

Where the recording policy retains one, a receipt records the facts R15 names.

draft shape

  EvaluationReceiptV1
    schemaVersion
    definition        { id, version, revision digest }
    instance          { id, revision }
    inputs[]          input and resource digests, with the redaction state of each
    fonts[]           { family, weight, style, source, file?, sha256? } per resolved face
    shaping           { engine, version }
    textFallbacks[]   runs that stayed live text: { text, reason }
    emoji             { set, version, treatment }
    models[]          { id, version, licence, execution location, service identity? } for each model the run used
    kernels[]         { operation, implementation, revision, artifact sha256? } per numerical or pixel implementation that produced a result
    devices[]         { api, adapter, backend, software } per graphics device the run computed on
    conversions[]     unit and DPI conversions applied, with the site that applied each
    clocks            the clocks the run read and the value each supplied
    environment       { shell, engine, suite versions, execution class }
    policy            { version, issuer, attestedAt }, plus the rules a waiver deactivated
    fallbacks[]       the declared fallbacks this run selected
    findings[]        the same finding shape the outcome carries
    results[]         result identities, including one entry per artifact of a fan-out
    effects[]         the effects this run committed, each with its declared envelope entry and its grant, recorded where the recording policy permits (R3, C6)
    repeatability     the declared repeatability class for this run
    redactions[]      { field, reason }, one entry per field withheld or reduced
    omissions[]       { field, reason }, one entry per field this host could not observe

This is a draft shape for review, not a type. No shared type is frozen until the counterexamples in plan section 17 pass (plan status line; Codex recommendation).

Three rules hold over every field.

An effect recorded here is an observation, never a permission: a receipt that lists an effect does not authorise it on a later run.

Production bindings and observations

Where recording is enabled, retain the exact selected file and observed digest separately from metadata, policy and review observations, including their origin, observation time, mapping revision and completeness (R15; plans 314 and 315). Historical bytes with only current attributes must be reported with that limitation. A cache token cannot replace either observation.

For a campaign row, associate the result with stable row identity, input revision, resolved locale and field/fallback bindings. Keep the explicit action targets, destination write intent, remote asset/version identity and observed readiness alongside committed effects where retention permits. A retry adds evidence for its own attempt; it must never relabel an earlier output as the result of changed copy. Missing evidence remains an omission, and private context follows redaction policy.

This elaborates the draft receipt's existing inputs, results and effects. It adds no shared type or mandatory durable record to local utilities (D11).

Fonts, shaping and live text

A receipt must record the font files a run resolved, by digest, together with the shaping engine and its version (R15).

LollyFontEntry in shells/web/src/lib/lolly-pack.ts is the precedent and it already draws the distinction the receipt needs. It records a face as identity rather than bytes. It digests the whole source file rather than a subset, because a subset is a function of the text. And it allows source: 'platform' with no file and no digest, as the record of a run that drew in whatever the machine had installed. A receipt must keep that third case as a named state, because a run with no resolvable digest is a different claim from a run with one.

A receipt must record every text run that stayed a live <text> element, and a host must never claim font-independent fidelity for such a run (R15). The fact already exists and goes nowhere durable. shells/web/src/bridge/export-svg-text-runs.ts logs a warning and keeps the element when an outline cannot be produced. shells/cli/src/run.ts collects the same runs through an onTextFallback callback, reports each with its reason and refuses the export under --strict. The comparator probe in the plan's evidence hit exactly this: one caption kept live text because dominant-baseline shifted its baseline. The CLI emitted the warning to standard error and the product kept nothing, so the probe had to capture it by hand into environment.cliWarnings of pixel-comparator-results.json (F14).

docs/determinism.md already states the public limit this serves: vector export converts text to outlines, so the bytes depend on which font file was resolved, and a machine with a different font set is a different render. The receipt records that dependency so a reader can check it afterwards.

The drawing operations from plan 295 already hold most of what this section asks a receipt to record. engine/src/design-draw.ts lays every Lolly Design text block out with the engine's measure (drawDesignText in engine/src/design-text-measure.ts) and the host's shaper, and each laid-out run keeps the face it resolved: family, weight, style, font file and variation axes. outlineDesignDrawText outlines each run from that same face through host.text.toPath, so the layout and the outline cannot disagree about the font. A run the host cannot outline stays live text and is reported as the text-unoutlined finding, which is the fact this section requires a receipt to keep. The face file is still a location, not a digest, so a receipt built from the operations must add the digest (R15).

Clocks

Clocks are explicit and separate, and a receipt must name which ones fed the run and with what values (R15, plan section 8.5).

ClockWhat it decidesPrecedent
EventWhat is happening.docs/agenda.md: the event clock decides which sessions are happening.
PresentationWhich scene and which title position to show.docs/agenda.md: the presentation clock decides the scene and the title position.
ReferenceA frozen moment for review.docs/agenda.md: reference time fixes a moment for review.
MediaPosition inside one clip.shells/web/src/bridge/frame-clock.ts: a driven frame receives a normalised loop time and the clip's real length in seconds.
WallWhen the export ran.shells/web/src/lib/lolly-pack.ts: the package manifest records an export time.

A run that read no clock must record none (R15). A host must never substitute wall time for a clock the document did not read (R15).

Units and DPI conversions

Each unit and DPI conversion a run applied must be recorded with the site that applied it (R15, plan section 8.4).

engine/src/units.ts holds the conversion maths and must stay the only place that holds it (plan section 8.4). The conversion is applied at several boundaries, one per export format in each shell's export bridge, which is why a receipt records the site as well as the number. Three DPI conventions are live at once: the rebrand reference space at 96 (REBRAND_REFERENCE_DPI in packages/core/src/rebrand-v1.ts), the export default at 300 (the dpi parameter in engine/src/url-mode.ts) and a Lolly Design document's own resolution (the documentDpi input in community/design/tool.json). A receipt that records the converted number without the convention cannot be read back, so both must travel.

Pictures

A picture's placement depends on a fact the instance record does not hold: the picture's own size. Plan 295's drawing compiler places a picture as CSS places one, by object-fit from that size, object-position and the framing zoom, with the edges snapped to whole pixels as Chromium snaps a replaced element (pictureRect in engine/src/design-draw.ts). The host supplies the size and the media kind (describeDesignDrawPictures), and the media kind can decide whether a row draws at all: a row whose asset is sound leaves no mark, and an animation or a video is reported rather than drawn as a still. Both are inputs to the evaluation, so a receipt must record the digest of each picture a run resolved under inputs[], and a size the host could not supply must appear as a finding (R15).

Choosing the renderer

Plan 295 draws an admitted Lolly Design page's SVG export from the drawing operations on the web and in the CLI (designOpsSvg in shells/web/src/bridge/export-design-ops.ts, designOpsSvgNode in packages/node-shell/src/design-ops-svg.ts). The CLI also writes an admitted static Lolly Design document as an outlined RGB PDF without a browser (designOpsPdfNode in packages/node-shell/src/design-ops-pdf.ts). The engine draws the pages and the shared packages/node-shell/src/pdf-finishing.ts applies print geometry, page boxes, marks and PDF/X metadata. The browser still owns pdf-cmyk, default or live-text PDFs, composed text stories, standard-password PDFs and pages the Node host cannot admit.

The runtime passes a detached snapshot of the authored Lolly Design values to SVG, SVGZ and PDF before beforeExport runs, and keeps each page's authored dimensions rather than substituting the tool manifest's size. A story-composition hook can change the rendered pages after that snapshot. The Node path therefore refuses a document with textDocument; the browser owns composition and exports the completed pages. A snapshot of the earlier rows must never replace that result.

Admission findings, such as an unsupported effect, unread or unsupported picture, watermark or unresolved browser-only brand value, select the existing renderer with the reasons stated. The CLI sends the whole document to its browser tier once. This is a declared fallback, chosen before delivery, so a receipt must list the choice in fallbacks[] with its findings (R15). A beforeExport, PDF-finishing or render-integrity failure is a failed run, never a renderer admission finding, and remains fatal even with --html-fallback. An admitted Node PDF's finishing or encryption error keeps its original message and cause as PdfFinishingError; the CLI refuses both browser escalation and HTML substitution. That separate flag permits an HTML artifact when the requested format cannot be produced; it does not permit a broken render to become a successful export.

Finishing preserves the existing limits. Strong AES-256 encryption runs last, after print geometry and metadata, and encrypted bytes receive no later Content Credentials update. A source picture that already carries Content Credentials selects the browser even when final signing is disabled, because that path records the picture as an ingredient. The PDF/X pass withholds its claim for a named-only output colour profile, selected fonts that are not embedded, unmanaged RGB images, shadings or transparency groups under a CMYK intent, or encryption. Those checks are conservative guards, not an independent PDF/X certification. RGB operations output does not establish CMYK print conformance.

SVGZ uses the same SVG drawing result, dimensions and metadata, wrapped in gzip. Decoding the wrapper returns that SVG; it introduces no renderer or different admission rules. The compiler and snapshot are shared with SVG, and composed stories and credentialed pictures retain their browser owner.

The native PowerPoint producer also evaluates admitted solid paths through drawing operations. Its compatibility reading carries one closed contour of box-local EMU cubics, decoded and mirrored by the original producer before paint callbacks. This is native deck geometry, not the Lolly Design preview's CSS geometry. The compiler copies the contour and resolved paints; the emitter reads those detached facts and writes the existing native path. Plain authored rows that change during a callback, accessor or inherited records, open or multiple contours, gradients, effects and unsupported paint stay with the original lowering. Reflective Proxy traps remain observable and are outside the plain-row comparison; a failed descriptor read keeps the original lowering without suppressing authored getter errors. The authored instance and native writer contracts do not change. Complete deck-data and fixed-time archive comparisons are implementation evidence; they do not establish PowerPoint visual acceptance or freeze a shared evaluation type.

Outlined strike-through uses the ascent of each run's resolved HarfBuzz font instance, including its variation axes. The host returns font-unit ascent and units-per-em; the engine validates those facts and applies the current Lolly Design HTML reference's CSS auto placement and thickness. SVG and PDF consume the same rectangle with the run's colour, opacity, transform and clip. The font's OS/2 strike position is not that CSS policy and is not an admission prerequisite. Missing ascent remains a text-decoration finding; a guessed font ascent must never replace the resolved face.

Outlined underline follows the same reference's CSS auto policy and needs no font metric: a line one tenth of the font size thick, at least 1 px, with its top max(1, ceil(thickness / 2)) px under the alphabetic baseline and the same solid-line pixel rounding. The reference clears the line where glyph ink crosses it (text-decoration-skip-ink: auto). The host returns each cluster's outline from text.toPath; the engine finds where each outline enters the line, widens that gap by the line's thickness, at most 13 px, and cuts it on whole pixels, because the reference clips without anti-aliasing. Characters the reference draws through, such as CJK, Hangul, slashes and low lines, keep the line. Spaces that hang at a wrap are a fragment of their own, so their line continues past the last glyph in the space's own colour. A host that returns no clusters, an outline that cannot be read, or a pictograph whose place in the reference's emoji-sequence set cannot be reproduced leaves a text-decoration finding.

The two shells write identical SVG bytes for the same fixture page because each host lends only facts: the shaped advances and outlines from HarfBuzz, the face files and their metrics, and each picture's own bytes and media kind. Everything that shapes the output, from the layout to the picture's type, size and encoding, runs once in the engine. A host interface that passed encoded results instead, such as a data URL or a picture size, would let the two shells drift. These adapters and their export tests are implementation evidence; they do not build the draft EvaluationReceiptV1 or establish a released conformance suite.

Emoji, models and policy

Numerical kernels and graphics devices

These rules come from the first WebGPU and Rust kernel work (plan 295), added on 2026-10-07. They describe what the tree now does for LUT grading and curve geometry, and they bind any later renderer.

Redaction is an explicit field

Source and processing evidence

The DAM review adds a requirement to the draft receipt, not a new implemented receipt type (plan 314; R15). Each observed resource must identify its selected file, source revision, representation and digest where observed. Declared dependencies, observed inputs and imported assertions remain distinguishable. A source timestamp or catalog cache version is never evidence that the run read particular bytes (records).

Where retained, processing evidence must name the actual model/service revision, operation and job/attempt reference, the effective processing authority and the result digests. Detailed recipes, private grant evidence and spend records remain separately authorised host or Lolly Work data. A public receipt may carry only permitted references or reduced facts. It must never contain service credentials, signed read URLs or an unapproved private prompt (R3, R15; packages/core/src/rights-v1.ts).

A generation recipe imported from another system remains external evidence. The host must record its origin, completeness and any withheld fields; it must never describe that import as a Lolly-observed execution. Missing settings, models or source inputs leave replay unproven. Reusing the resulting asset does not repeat the generation (records, R15).

Source access, contextual use eligibility and review are observations with their own issuer, subject, context, observed time and validity where supplied. Their retained evidence explains the earlier run. A later consequential action must perform the fresh checks its authority requires; an old receipt cannot renew a grant (policy, R7).

These records are conditional on recording policy. Source history must never turn a local utility with retention none into a durably logged operation (D11). No new provenance assertion is emitted by this amendment; any future write follows its format and publication policy.

Recorded, withheld and unobserved

A receipt must never imply that it holds every private input (R15).

A reader must therefore be able to tell three states apart: recorded, withheld and never observed. A host that drops a field silently collapses those three into one answer.

A decision a person made must be recorded against the facts it was made about, never as a blanket permission. RightsDecisionV1 in packages/core/src/rights-v1.ts is the precedent already shipping: a decision carries a fingerprint of the situation as it stood, and the evaluator applies the choice only while the facts still hash to it.

Replaying an interaction

A claimed replayable interaction must reproduce the specified semantic state under the named conformance suite, from a pinned initial state and a normalised timestamped input trace (R15, R8).

One normalisation is needed before any comparison. Signing timestamps and provenance containers need not be byte-identical for a visual or semantic result, and stripSvgC2pa in packages/node-shell/src/lolly-file.ts is the existing normalisation both sides of a comparison must apply. docs/determinism.md states the reason: a default export is signed afresh with a new key and timestamp on every run, so two correct runs differ in exactly that block.

A live run is a weaker case again. engine/src/runtime.ts runs the onFrame and onLevel hooks once per frame or sample, leaves them outside the time box and drops overlapping samples so a slow per-frame render throttles itself. The frame count of such a run is an observation of the machine that ran it. A host must therefore never claim a byte replay of a live-input run, and Q4 below carries the default for what it records instead.

Open points

Q1 and Q5 are answered in Conformance and fidelity. Q6 is answered in Status and open points.

Precedents