openscript 0.4.0__py3-none-any.whl

openscript/strategy/sizing.py

@@ -0,0 +1,229 @@
+"""How much each order of a call sends, and which position it is sent against, 17.1.
+
+**This is the half of a call that is arithmetic.** ``placing`` says what each call
+means and dispatches to the two functions here; these two decide how many orders
+the call becomes, how large each is, and which position reference each one
+carries.
+
+The two entry points are ``entering``, for a call that states a side and a size,
+and ``flattening``, for one that reduces what the leg holds. What they differ
+about is not the split but the budget: an entry sends the size the script wrote
+whatever the leg holds, so the only question is where its units land; a close
+chooses its own number, so it may only choose one that has settled.
+
+**No order crosses zero.** An instruction that would take a leg from long to
+short is two orders, one that closes the outgoing position and one that opens the
+replacement, each carrying its own position reference, so that a fill arriving
+late can still say which of the two it settled.
+
+**The reference is minted in every unit; only the arithmetic waits.** The split
+subtracts a position folded from filled quantities from a quantity the script
+stated, and those are the same kind of number only in a declaration counting in
+units. Minting a reference needs none of that arithmetic, so an order the engine
+cannot size against the leg is still sent on a position of its own rather than on
+the outgoing one. What does not hold is written where a reader meets it:
+``stdlib.md`` 17.1 and ``errors.md`` OS7005.
+"""
+
+from dataclasses import dataclass, replace
+from typing import Any, List, Optional, Protocol, Sequence, Tuple
+
+from .closable import Closing, closable_units
+from .holdings import Book, Holding, divide, holdings, joining, opposing, outgoing_for
+from .intents import Identity, IntentBar, Placement  # noqa: F401  the context states them
+from .rows import Reduction
+
+
+class PlacingContext(Book, Closing, Protocol):
+    """What the mapping and the refusals read: the declaration, the leg and the ledger."""
+
+    instrument: Identity
+    product: str
+    #: The unit a quantity the script stated is counted in, ``language.md`` 13.3.
+    qty_type: str
+    #: The size an order that names none takes, from the declaration.
+    declared_qty: float
+    #: The instrument's tick size, absent where the host states none.
+    tick_size: Optional[float]
+    #: Entries allowed in one direction before one is refused.
+    pyramiding: float
+    bar: IntentBar
+
+    def avg_price(self) -> Optional[float]:
+        """The average price of the open position, absent while flat."""
+
+    def mint(self) -> int:
+        """A fresh position, for the replacement half of a flip."""
+
+
+@dataclass(frozen=True)
+class MappedOrder:
+    """One order a call sends, and what that order takes out of the leg."""
+
+    placement: Placement
+    reduces: Optional[Reduction] = None
+
+
+def adding(placement: Placement) -> MappedOrder:
+    """An order that adds to a position, or whose size the engine cannot count."""
+    return MappedOrder(placement=placement, reduces=None)
+
+
+@dataclass(frozen=True)
+class Entry:
+    """What an entering order states, at one quantity and one position."""
+
+    side: str
+    limit: Optional[float]
+    trigger: Optional[float]
+    order_type: str
+    tag: str
+
+
+def _placing(entry: Entry, qty: float, qty_type: str, position_ref: int) -> Placement:
+    return Placement(
+        kind="place",
+        side=entry.side,
+        qty=qty,
+        qty_type=qty_type,
+        order_type=entry.order_type,
+        limit=entry.limit,
+        trigger=entry.trigger,
+        tag=entry.tag,
+        position_ref=position_ref,
+    )
+
+
+def _opening_on(ctx: Any, book: Sequence[Holding], side: str) -> int:
+    """The reference an order that opens or adds to a position carries."""
+    found = joining(book, side)
+    return ctx.mint() if found is None else found
+
+
+def entering(ctx: Any, entry: Entry, qty: Optional[float]) -> Tuple[MappedOrder, ...]:
+    """The orders an entry sends, which is two where it crosses zero.
+
+    The closing half is what is left to close, not what the leg holds: an order
+    the destination has not answered has filled nothing, so a leg with a close
+    already going has nothing left for the outgoing half to take.
+
+    What it crosses is decided per position, not from the leg's net. The net is
+    folded from settled fills, so on a silent destination it reads zero while an
+    entry is still going and an opposing entry is not seen as opposing anything
+    at all. The question is about one position, so it is asked of one position,
+    and the answer is the same whether or not the destination has answered yet.
+    """
+    # The declaration's own size where the call named none, ``stdlib.md`` 17.2.
+    wanted = ctx.declared_qty if qty is None else qty
+    book = holdings(ctx)
+    # Nothing to cross: the leg holds no position this order opposes, so it opens
+    # one or joins the one it is on the side of.
+    if not opposing(book, entry.side):
+        return (adding(_placing(entry, wanted, ctx.qty_type, _opening_on(ctx, book, entry.side))),)
+
+    if ctx.qty_type != "units":
+        return (
+            MappedOrder(
+                # A position of its own, in every unit, because minting one needs
+                # no lot size. On the outgoing reference this order was the
+                # crossing 17.1 refuses outright.
+                placement=_placing(entry, wanted, ctx.qty_type, ctx.mint()),
+                # Unreadable in units, so it is taken to have reduced the whole of
+                # what was left: ``closable`` says why that is the only safe
+                # reading.
+                reduces=Reduction(part=None, claimed=closable_units(ctx, None), counted=False),
+            ),
+        )
+
+    # What each position it opposes can absorb, oldest first. A position holding
+    # six is sent six of the nine, whether those six have settled or are still
+    # going, because six of this order is what brings that position back to zero.
+    shares, left = divide(book, entry.side, wanted, lambda one: one.units)
+    out: List[MappedOrder] = [
+        MappedOrder(
+            placement=_placing(entry, share.units, "units", share.ref),
+            reduces=Reduction(part=None, claimed=share.units, counted=True),
+        )
+        for share in shares
+    ]
+    if left == 0:
+        return tuple(out)
+    # The replacement is a position of its own where the leg holds none on this
+    # side, so that a fill on an outgoing order settles the position it belonged
+    # to.
+    out.append(adding(_placing(entry, left, "units", _opening_on(ctx, book, entry.side))))
+    return tuple(out)
+
+
+def _reducing(side: str, qty: float, qty_type: str, tag: str, position_ref: int) -> Placement:
+    return Placement(
+        kind="place",
+        side=side,
+        qty=qty,
+        qty_type=qty_type,
+        order_type="market",
+        tag=tag,
+        position_ref=position_ref,
+    )
+
+
+def flattening(
+    ctx: Any,
+    units: float,
+    side: str,
+    qty: Optional[float],
+    tag: str,
+    part: Optional[str],
+) -> Tuple[MappedOrder, ...]:
+    """The orders a flattening call sends, which is one per position it reduces.
+
+    It is divided across the positions holding it, oldest first, each bounded by
+    what has settled on it and is not already working against it. Sized against
+    the whole leg and attached to a single reference, one order was large enough
+    to take the first of them through zero and out the other side.
+
+    A quantity the engine cannot read is one order. It cannot be divided at all,
+    so it goes on the position it is closing, oldest first, and that position is
+    what it may take past zero: the one shape of 17.1 an engine does not keep.
+    """
+    # Nothing to flatten and no size named: an instruction about a position the
+    # strategy does not hold, which is not an error and is not an order either.
+    if units <= 0 and qty is None:
+        return ()
+    sending = units if qty is None else qty
+    # A quantity the engine worked out is counted as itself. One the script
+    # stated in a unit the engine cannot read is counted as the whole of what was
+    # left, which is what keeps a close after it from sending the position again.
+    counted = qty is None or ctx.qty_type == "units"
+    book = holdings(ctx)
+    if not counted:
+        outgoing = outgoing_for(ctx, book, side)
+        # Where the leg holds no position on the side the close reduces the call
+        # sends nothing, whatever it stated: a close is never minted a position,
+        # so there is nothing for it to be sent against.
+        if outgoing is None:
+            return ()
+        return (
+            MappedOrder(
+                placement=_reducing(side, sending, ctx.qty_type, tag, outgoing),
+                reduces=Reduction(part=part, claimed=units, counted=False),
+            ),
+        )
+    # Anything left when every position it reduces is full is left unsent rather
+    # than pushed onto one of them past its own size. By construction there is
+    # nothing left: what a close may send is the leg's settled net less what is
+    # working against it, and that is never more than the positions on that side
+    # hold.
+    shares, _left = divide(book, side, sending, lambda one: one.settled)
+    return tuple(
+        MappedOrder(
+            placement=_reducing(side, share.units, "units", tag, share.ref),
+            reduces=Reduction(part=part, claimed=share.units, counted=True),
+        )
+        for share in shares
+    )
+
+
+def at_position(order: MappedOrder, ref: int) -> MappedOrder:
+    """The same order sent against another position, which a split makes."""
+    return MappedOrder(placement=replace(order.placement, position_ref=ref), reduces=order.reduces)

openscript/strategy/statuses.py

@@ -0,0 +1,65 @@
+"""The status vocabulary of ``stdlib.md`` section 17.7, and what each word does.
+
+The words themselves are the page's and the table there is the authority. What
+is here is the three facts the fold needs to be able to ask: whether a word is
+one of the seven, whether it ends an order, and how far along its life it sits.
+``tests/test_statuses.py`` reads the table out of the page and fails the day one
+of the three stops being what the page says, which is the arrangement this
+engine already uses for every other constant it carries: the package a host
+installs does not ship the specification, so the values live here and a test
+holds them to the document.
+
+**A rank rather than an ordering of the seven words.** Two of them share the
+middle rank because an order that is live and one that is waiting for its
+trigger are the same distance from the end, and either may follow the other
+without the status going backwards.
+
+**``placed`` is the engine's own.** It means an intent has left and nothing has
+come back, and a host cannot report a state the destination has never described,
+so it is the one word the last column of the table refuses a host.
+"""
+
+from typing import FrozenSet, Optional, Tuple
+
+#: The seven words a row's status may take, in the order the page prints them.
+STATUSES: Tuple[str, ...] = (
+    "placed",
+    "working",
+    "triggerPending",
+    "filled",
+    "cancelled",
+    "rejected",
+    "expired",
+)
+
+#: The four that end an order. A terminal row still takes a fill, under 17.8, so
+#: this decides what the status may become and nothing about what the quantity
+#: may do.
+TERMINAL: FrozenSet[str] = frozenset({"filled", "cancelled", "rejected", "expired"})
+
+#: The six a host may send in a frame, which is every word but the engine's own.
+HOST_SENDABLE: Tuple[str, ...] = tuple(one for one in STATUSES if one != "placed")
+
+#: The word a row is appended at.
+PLACED = "placed"
+
+
+def is_terminal(status: str) -> bool:
+    """Whether this word ends an order."""
+    return status in TERMINAL
+
+
+def status_from(word: str) -> Optional[str]:
+    """The word a host sent, or nothing where it is not one of the seven.
+
+    A word outside the vocabulary leaves a row's status alone and the rest of
+    the frame folds anyway, which is ``row``'s decision and is written there.
+    """
+    return word if word in STATUSES else None
+
+
+def rank_of(status: str) -> int:
+    """How far along its life a status sits: 0 sent, 1 live, 2 ended."""
+    if status == PLACED:
+        return 0
+    return 2 if is_terminal(status) else 1

openscript/surface/__init__.py

@@ -0,0 +1,115 @@
+"""The chart surface: what a run draws, in the channels a case asserts it through.
+
+``compiled-program.md`` section 11 maps a compiled program to a chart, and this
+package is the half of that map an engine can perform: the declarations in
+``outputs`` against the channels a bar wrote, folded into the ordered lists
+``conformance.md`` section 4 compares. A host wanting the rest of the descriptor,
+a legend, a pane, a settings dialog, builds it from the program, which carries
+every declared field; nothing here decides how anything is drawn.
+
+## The encoding, and the part of it the page does not fix
+
+Section 4 fixes the shape of a channel, "an ordered list, and each element is a
+flat object of named fields", and section 6 fixes how each kind of field is
+compared, a colour as four integer channels and a string as an exact sequence of
+code points. **It names no field of a surface row.** The first engine writes
+none of these channels into a case either, so there is no second implementation
+to read them off. What follows is therefore this engine's reading, stated here
+rather than spread over five modules, and recorded in the stage's report as a
+question for the page.
+
+**A row is a thing the host was handed to draw, and there is no row for a thing
+it was not.** That is ``stdlib.md`` section 18's closing sentence turned into an
+encoding: "An absent value reaching any of these is a gap, never a zero: a line
+breaks, a band stops, a level is not drawn, a bar keeps its own colour, a cell is
+blank". So a marker fires or it does not, a bar is painted or it keeps its own
+colour, a band spans a bar or stops at it, and each of those is a row present or
+a row absent. A length difference is then the first thing a report names, which
+section 6 says is what a reader of a failed case wants to see.
+
+**A row carries what the run computed, and the identity of the declaration it
+belongs to.** The bar index, the declaration's key or its ordinal, and the value
+the channel held. It does not carry the declaration's own fields: a marker's
+shape, a level's title, a band's opacity and a plot's colour are fixed before bar
+0 and are in the compiled program that both engines were handed, so a row
+repeating one would compare the compiler's output twice and call it an engine
+agreeing with an engine. ``spec/decisions.md`` 14 reaches the same place from the
+other side: the suite asserts columns, markers, fills, levels and paint, never a
+plot's default style colour.
+
+## What this engine does not draw
+
+Two of section 2's channels are not answered, and they are named rather than
+answered emptily, because an empty channel compares equal to an empty
+expectation and is a pass nobody earned (``conformance.md`` section 8).
+
+``table`` and ``drawings`` are the two, and the reason is the same for both:
+4.11 keeps them out of the channels on purpose, a grid's cells are written by
+library calls against a handle and a drawing is an object in the heap, and this
+engine's library holds neither the grid calls nor the ``draw`` namespace. A
+program that declares a grid or creates a drawing calls a function this engine's
+manifest does not have, so it is already refused at load with OS6004 naming the
+function; the sentences below are what a case asserting either channel is told.
+
+The ``alerts`` and ``log`` channels are not this package's: an alert is raised by
+the bar cycle (``run.py``, section 5.4) and a log line is written by a library
+call this engine does not hold.
+"""
+
+from typing import Any, Callable, Dict, List, Sequence
+
+from ..program import LoadedProgram
+from ..run import BarResult
+from .bands import FILLS, fills_channel
+from .levels import LEVELS, levels_channel
+from .marks import MARKERS, markers_channel
+from .paints import PAINTS, paint_channel
+from .published import published
+
+#: The surface channels of section 2 this engine answers.
+ANSWERED = (MARKERS, FILLS, LEVELS) + tuple(name for name, _field in PAINTS)
+
+#: The surface channels it does not, each with what a case asserting one is told.
+UNANSWERED: Dict[str, str] = {
+    "table": (
+        "the table channel: a grid's cells are written by library calls against a handle rather "
+        "than through channels (compiled-program.md 4.11), and this engine's library holds "
+        "neither table nor cell, so a program declaring a grid is refused at load naming the "
+        "function"
+    ),
+    "drawings": (
+        "the drawings channel: a free drawing is an object in the heap that the draw namespace "
+        "creates and mutates (compiled-program.md 4.11, stdlib.md 14.4), and this engine's "
+        "library holds none of those calls, so a program creating one is refused at load naming "
+        "the function"
+    ),
+}
+
+
+def surface_channels(
+    program: LoadedProgram,
+    executions: Sequence[BarResult],
+    spell: Callable[[Any], Any],
+) -> Dict[str, List[Dict[str, Any]]]:
+    """Every surface channel this engine answers, for one run.
+
+    ``executions`` is what the caller driving the bars got back, in the order it
+    ran them, a moving bar's repeated executions included: the fold to one row
+    per bar is ``published.py``'s and not the caller's. ``spell`` is how one
+    value is written into a case file, which is ``adapter.spellings.as_reported``
+    for the adapter and identity for a caller reading the machine's own values.
+    A channel a case does not assert costs the list it is not asked for, which is
+    cheap enough that answering all five is simpler than answering some.
+    """
+    bars = published(executions)
+    found: Dict[str, List[Dict[str, Any]]] = {
+        MARKERS: markers_channel(program, bars, spell),
+        FILLS: fills_channel(program, bars, spell),
+        LEVELS: levels_channel(program, bars, spell),
+    }
+    for name, declared in PAINTS:
+        found[name] = paint_channel(program, bars, declared, spell)
+    return found
+
+
+__all__ = ["ANSWERED", "UNANSWERED", "surface_channels"]

openscript/surface/bands.py

@@ -0,0 +1,103 @@
+"""The fills channel: where a shaded band is drawn, and the colour it is drawn in.
+
+``compiled-program.md`` 2.8, the ``fills[]`` table: a band names the two plot
+keys it is drawn between, a colour for each side, and a channel beside each
+colour for the bars where the script computed one instead of declaring it.
+
+**A band is drawn on a bar where both of its columns have a value.**
+``stdlib.md`` 18: "An absent value reaching any of these is a gap, never a zero:
+a line breaks, a band stops". So a row exists for a bar the band spans and there
+is no row for a bar it does not, which is what makes the case the conformance
+page names in section 7, a fill stopping across an absent bar, a difference in
+this channel rather than a difference nobody can see. The two columns are read
+through the plot keys, because ``between`` carries keys and not channels.
+
+**A row carries the colours the bar computed and nothing the program declares.**
+A band with two constant colours computes nothing per bar, so both fields are
+null on every row and the row says only that the band is drawn there; the
+colours are in the program both engines read. A band with a colour channel
+carries what that channel held. Null therefore means "this bar computed no
+colour for that side", which covers a side that was never per-bar and a per-bar
+side that was absent on this bar. Whether a host draws the declared colour on
+such a bar or leaves the band unpainted is not written down anywhere, and this
+engine reports the fact rather than deciding it; the stage's report carries the
+question.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Sequence
+
+from ..diagnostics import ScriptError, malformed
+from ..program import LoadedProgram
+from ..values import ABSENT
+from .plots import channel_of_key
+from .published import Published, channel_named, value_of
+
+#: Section 2's vocabulary for this channel.
+FILLS = "fills"
+
+#: The two sides of a band, as 2.8 spells them, each with the field that carries
+#: a channel for it.
+SIDES = (("colorUp", "colorUpChannel"), ("colorDown", "colorDownChannel"))
+
+
+@dataclass(frozen=True)
+class Band:
+    """One declared band, with every name it carries resolved to a channel."""
+
+    index: int
+    between: Sequence[int]
+    colours: Sequence[Optional[int]]
+
+
+def bands_of(program: LoadedProgram) -> List[Band]:
+    """Every declared band, resolved once rather than on every bar.
+
+    Resolved before the first bar is read, so a program naming a plot key
+    nothing declares, or a channel past the end of the table, is refused whole
+    rather than on the bar the band would first have been drawn on.
+    """
+    raw = program.raw
+    found: List[Band] = []
+    for at, one in enumerate(raw["outputs"][FILLS]):
+        path = f"outputs.{FILLS}[{at}]"
+        between = one.get("between")
+        if not isinstance(between, (list, tuple)) or len(between) != 2:
+            raise ScriptError(
+                malformed(f"{path}.between", "is not the two plot keys a band is drawn between")
+            )
+        found.append(
+            Band(
+                index=at,
+                between=[
+                    channel_of_key(raw, key, f"{path}.between[{side}]")
+                    for side, key in enumerate(between)
+                ],
+                colours=[channel_named(raw, one, field, path) for _colour, field in SIDES],
+            )
+        )
+    return found
+
+
+def fills_channel(
+    program: LoadedProgram, bars: Sequence[Published], spell: Any
+) -> List[Dict[str, Any]]:
+    """Every band on every bar it is drawn on, oldest bar first.
+
+    Declaration order inside a bar, which is the order the bands are drawn in
+    and the order a legend lists them in.
+    """
+    declared = bands_of(program)
+    if not declared:
+        return []
+    rows: List[Dict[str, Any]] = []
+    for bar in bars:
+        for band in declared:
+            if any(value_of(program, bar, one) is ABSENT for one in band.between):
+                continue
+            row: Dict[str, Any] = {"barIndex": bar.index, "fill": band.index}
+            for (colour, _field), channel in zip(SIDES, band.colours):
+                held = ABSENT if channel is None else value_of(program, bar, channel)
+                row[colour] = None if held is ABSENT else spell(held)
+            rows.append(row)
+    return rows

openscript/surface/levels.py

@@ -0,0 +1,44 @@
+"""The levels channel: the horizontal lines a host draws after the run.
+
+``compiled-program.md`` 2.8, the ``levels[]`` table: "A level's price arrives
+through a channel and is therefore evaluated every bar, and the level drawn is
+the one from the last bar executed." So this channel is not one row per bar. It
+is one row per level, holding the value the last bar left, which is the only
+value a host ever draws.
+
+A level whose last value is absent is not drawn (``stdlib.md`` 18: "a level is
+not drawn"), so it has no row, and the ordinal on each row is what says which
+of the declared levels is missing. The declaration's title, colour, style and
+width are the program's and are not repeated here, for the reason the door's
+docstring gives.
+"""
+
+from typing import Any, Dict, List, Sequence
+
+from ..program import LoadedProgram
+from ..values import ABSENT
+from .published import Published, value_of
+
+#: Section 2's vocabulary for this channel.
+LEVELS = "levels"
+
+
+def levels_channel(
+    program: LoadedProgram, bars: Sequence[Published], spell: Any
+) -> List[Dict[str, Any]]:
+    """Each declared level, with the value the last bar executed left in it.
+
+    A run with no bars draws none: there is no last bar for a level to take its
+    price from, and a level drawn at a price nothing computed would be a line
+    across a chart with no data behind it.
+    """
+    if not bars:
+        return []
+    last = bars[-1]
+    rows: List[Dict[str, Any]] = []
+    for at, one in enumerate(program.raw["outputs"][LEVELS]):
+        value = value_of(program, last, one["channel"])
+        if value is ABSENT:
+            continue
+        rows.append({"level": at, "value": spell(value)})
+    return rows

openscript/surface/marks.py

@@ -0,0 +1,52 @@
+"""The markers channel: one row per marker a bar drew.
+
+``compiled-program.md`` 2.8, the ``markers[]`` table: one entry per ``signal()``
+call site, carrying the channel that holds the marker's text, and "a marker is
+emitted when its channel holds a string for the bar, and not otherwise". Both
+halves of that sentence are the rule below, and the second half is the one worth
+stating: a channel holding a number, a colour or absence draws nothing, and a
+call site that fired twice on a bar left the last text written, which is the
+last write winning (2.7) rather than a rule of this surface's own.
+
+The other half of when a marker is drawn is deferral, which ``published.py``
+holds for every channel at once: 5.4 holds a marker back on a bar that is still
+moving, so the first execution of a moving bar writes the text and step 9 throws
+it away. Section 12.6's trace prints that row as ``held``, and the test beside
+this module is measured against that column.
+
+**A row carries what the engine computed and the identity it belongs to.** The
+bar, the call site's key and the text. The marker's position, its shape and its
+two colours are declared before bar 0 and are in the program every engine read,
+so a row repeating them would assert the compiler's output through the engine's
+channel; ``spec/decisions.md`` 14 says the same thing about a plot's declared
+colour, that the suite asserts what a run produced. The door's docstring records
+the encoding and what the page leaves open about it.
+"""
+
+from typing import Any, Dict, List, Sequence
+
+from ..program import LoadedProgram
+from .published import Published, value_of
+
+#: Section 2's vocabulary for this channel, which a case names in ``asserts``.
+MARKERS = "markers"
+
+
+def markers_channel(
+    program: LoadedProgram, bars: Sequence[Published], spell: Any
+) -> List[Dict[str, Any]]:
+    """Every marker drawn, oldest bar first and declaration order inside a bar.
+
+    Declaration order rather than the order the call sites ran in: an engine
+    reporting the order of execution would report a script's branches, and two
+    engines agreeing on the branches is what the values channel is for.
+    """
+    declared = program.raw["outputs"][MARKERS]
+    rows: List[Dict[str, Any]] = []
+    for bar in bars:
+        for one in declared:
+            text = value_of(program, bar, one["channel"])
+            if not isinstance(text, str):
+                continue
+            rows.append({"barIndex": bar.index, "key": one["key"], "text": spell(text)})
+    return rows

openscript/surface/paints.py

@@ -0,0 +1,58 @@
+"""The two paint channels: the price bars' colour, and the pane's background.
+
+``compiled-program.md`` 2.8: ``barColor`` and ``background`` are each either
+null or one channel, and there is one of each per program. A script with three
+``barColor()`` calls writes the same channel three times and the last write on
+the bar wins, which is 2.7's rule for every channel and needs no sentence here.
+
+**A bar with no paint has no row.** ``stdlib.md`` 14.3 says ``barColor(none)``
+and ``background(none)`` leave the bar alone and that passing an absent colour
+is not an error, and 18 says an absent value reaching a surface is a gap and
+never a zero. So a row is a bar that was painted, carrying the bar and the
+colour, and a bar that was not painted is the row that is not there. The two
+channels are projected by one function because they are one shape: an engine
+with a rule for the background that it did not have for the bars would be two
+answers to one question.
+
+**What is in the row is what the channel held.** A colour reaches a case file as
+the four integer channels of ``conformance.md`` section 6, spelled ``#rrggbbaa``
+after the alpha conversion of ``compiled-program.md`` 3.1, and the spelling is
+the caller's: ``adapter.spellings`` states that conversion once and this module
+does not state it again. A channel declared ``color`` that held something else
+is reported as what it held rather than dropped, because 3.5 has no check that
+an ``EMIT`` matches its channel's declared type, and a value silently missing
+from a channel is the failure this whole surface exists to avoid.
+"""
+
+from typing import Any, Dict, List, Sequence
+
+from ..program import LoadedProgram
+from ..values import ABSENT
+from .published import Published, value_of
+
+#: Section 2's vocabulary for the two channels, against the field of ``outputs``
+#: each is read from. The names differ by a plural: a case asserts ``barColors``,
+#: one row per painted bar, and a program declares ``barColor``, one channel.
+PAINTS = (("barColors", "barColor"), ("background", "background"))
+
+
+def paint_channel(
+    program: LoadedProgram, bars: Sequence[Published], declared: str, spell: Any
+) -> List[Dict[str, Any]]:
+    """Every bar the named paint was applied to, oldest first.
+
+    ``declared`` is the field of ``outputs``: ``barColor`` or ``background``. A
+    program that declares neither paints nothing, and its channel is null rather
+    than a channel that is never written.
+    """
+    held = program.raw["outputs"].get(declared)
+    if held is None:
+        return []
+    channel = held["channel"]
+    rows: List[Dict[str, Any]] = []
+    for bar in bars:
+        colour = value_of(program, bar, channel)
+        if colour is ABSENT:
+            continue
+        rows.append({"barIndex": bar.index, "color": spell(colour)})
+    return rows